Skip to content
Effect 4.0 is here. One ecosystem. Zero dependencies.

Response

The Response module provides data structures to represent responses from large language models.

This module defines the complete structure of AI model responses, including various content parts for text, reasoning, tool calls, files, and metadata, supporting both streaming and non-streaming responses.

Example 

import { Response } from "@effect/ai"


// Create a simple text response part
const textResponse = Response.makePart("text", {
  text: "The weather is sunny today!"
})


// Create a tool call response part
const toolCallResponse = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco" },
  providerExecuted: false
})
123 exports Since v1.0.0 Source

Constructors

documentSourcePart

Since v1.0.0

Constructs a new document source part.

Signature

declare function documentSourcePart(params: ConstructorParams<DocumentSourcePart>): DocumentSourcePart

errorPart

Since v1.0.0

Constructs a new error part.

Signature

declare function errorPart(params: ConstructorParams<ErrorPart>): ErrorPart

filePart

Since v1.0.0

Constructs a new file part.

Signature

declare function filePart(params: ConstructorParams<FilePart>): FilePart

finishPart

Since v1.0.0

Constructs a new finish part.

Signature

declare function finishPart(params: ConstructorParams<FinishPart>): FinishPart

makePart

Since v1.0.0

Creates a new response content part of the specified type.

Signature

declare function makePart<Type extends "error" | "text" | "reasoning" | "file" | "tool-call" | "tool-result" | "text-start" | "text-delta" | "text-end" | "reasoning-start" | "reasoning-delta" | "reasoning-end" | "tool-params-start" | "tool-params-delta" | "tool-params-end" | "source" | "response-metadata" | "finish">(type: Type, params: Omit<Extract<TextStartPart, {
  type: Type;
}> | Extract<TextDeltaPart, {
  type: Type;
}> | Extract<TextEndPart, {
  type: Type;
}> | Extract<ReasoningStartPart, {
  type: Type;
}> | Extract<ReasoningDeltaPart, {
  type: Type;
}> | Extract<ReasoningEndPart, {
  type: Type;
}> | Extract<ToolParamsStartPart, {
  type: Type;
}> | Extract<ToolParamsDeltaPart, {
  type: Type;
}> | Extract<ToolParamsEndPart, {
  type: Type;
}> | Extract<FilePart, {
  type: Type;
}> | Extract<DocumentSourcePart, {
  type: Type;
}> | Extract<UrlSourcePart, {
  type: Type;
}> | Extract<ResponseMetadataPart, {
  type: Type;
}> | Extract<FinishPart, {
  type: Type;
}> | Extract<ErrorPart, {
  type: Type;
}> | Extract<TextPart, {
  type: Type;
}> | Extract<ReasoningPart, {
  type: Type;
}> | Extract<ToolCallPart<any, any>, {
  type: Type;
}> | Extract<ToolResultSuccess<any, any>, {
  type: Type;
}> | Extract<ToolResultFailure<any, any>, {
  type: Type;
}>, "type" | "~effect/ai/Content/Part" | "metadata"> & {
  readonly metadata?: Extract<TextStartPart, {
    type: Type;
  }> | Extract<TextDeltaPart, {
    type: Type;
  }> | Extract<TextEndPart, {
    type: Type;
  }> | Extract<ReasoningStartPart, {
    type: Type;
  }> | Extract<ReasoningDeltaPart, {
    type: Type;
  }> | Extract<ReasoningEndPart, {
    type: Type;
  }> | Extract<ToolParamsStartPart, {
    type: Type;
  }> | Extract<ToolParamsDeltaPart, {
    type: Type;
  }> | Extract<ToolParamsEndPart, {
    type: Type;
  }> | Extract<FilePart, {
    type: Type;
  }> | Extract<DocumentSourcePart, {
    type: Type;
  }> | Extract<UrlSourcePart, {
    type: Type;
  }> | Extract<ResponseMetadataPart, {
    type: Type;
  }> | Extract<FinishPart, {
    type: Type;
  }> | Extract<ErrorPart, {
    type: Type;
  }> | Extract<TextPart, {
    type: Type;
  }> | Extract<ReasoningPart, {
    type: Type;
  }> | Extract<ToolCallPart<any, any>, {
    type: Type;
  }> | Extract<ToolResultSuccess<any, any>, {
    type: Type;
  }> | Extract<ToolResultFailure<any, any>, {
    type: Type;
  }>["metadata"];
}): Extract<TextStartPart, {
  type: Type;
}> | Extract<TextDeltaPart, {
  type: Type;
}> | Extract<TextEndPart, {
  type: Type;
}> | Extract<ReasoningStartPart, {
  type: Type;
}> | Extract<ReasoningDeltaPart, {
  type: Type;
}> | Extract<ReasoningEndPart, {
  type: Type;
}> | Extract<ToolParamsStartPart, {
  type: Type;
}> | Extract<ToolParamsDeltaPart, {
  type: Type;
}> | Extract<ToolParamsEndPart, {
  type: Type;
}> | Extract<FilePart, {
  type: Type;
}> | Extract<DocumentSourcePart, {
  type: Type;
}> | Extract<UrlSourcePart, {
  type: Type;
}> | Extract<ResponseMetadataPart, {
  type: Type;
}> | Extract<FinishPart, {
  type: Type;
}> | Extract<ErrorPart, {
  type: Type;
}> | Extract<TextPart, {
  type: Type;
}> | Extract<ReasoningPart, {
  type: Type;
}> | Extract<ToolCallPart<any, any>, {
  type: Type;
}> | Extract<ToolResultSuccess<any, any>, {
  type: Type;
}> | Extract<ToolResultFailure<any, any>, {
  type: Type;
}>

Example 

import { Response } from "@effect/ai"


const textPart = Response.makePart("text", {
  text: "Hello, world!"
})


const toolCallPart = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco" },
  providerExecuted: false
})

reasoningDeltaPart

Since v1.0.0

Constructs a new reasoning delta part.

Signature

declare function reasoningDeltaPart(params: ConstructorParams<ReasoningDeltaPart>): ReasoningDeltaPart

reasoningEndPart

Since v1.0.0

Constructs a new reasoning end part.

Signature

declare function reasoningEndPart(params: ConstructorParams<ReasoningEndPart>): ReasoningEndPart

reasoningPart

Since v1.0.0

Constructs a new reasoning part.

Signature

declare function reasoningPart(params: ConstructorParams<ReasoningPart>): ReasoningPart

reasoningStartPart

Since v1.0.0

Constructs a new reasoning start part.

Signature

declare function reasoningStartPart(params: ConstructorParams<ReasoningStartPart>): ReasoningStartPart

responseMetadataPart

Since v1.0.0

Constructs a new response metadata part.

Signature

declare function responseMetadataPart(params: ConstructorParams<ResponseMetadataPart>): ResponseMetadataPart

textDeltaPart

Since v1.0.0

Constructs a new text delta part.

Signature

declare function textDeltaPart(params: ConstructorParams<TextDeltaPart>): TextDeltaPart

textEndPart

Since v1.0.0

Constructs a new text end part.

Signature

declare function textEndPart(params: ConstructorParams<TextEndPart>): TextEndPart

textPart

Since v1.0.0

Constructs a new text part.

Signature

declare function textPart(params: ConstructorParams<TextPart>): TextPart

textStartPart

Since v1.0.0

Constructs a new text start part.

Signature

declare function textStartPart(params: ConstructorParams<TextStartPart>): TextStartPart

toolCallPart

Since v1.0.0

Constructs a new tool call part.

Signature

declare function toolCallPart<Name extends string, Params>(params: ConstructorParams<ToolCallPart<Name, Params>>): ToolCallPart<Name, Params>

toolParamsDeltaPart

Since v1.0.0

Constructs a new tool params delta part.

Signature

declare function toolParamsDeltaPart(params: ConstructorParams<ToolParamsDeltaPart>): ToolParamsDeltaPart

toolParamsEndPart

Since v1.0.0

Constructs a new tool params end part.

Signature

declare function toolParamsEndPart(params: ConstructorParams<ToolParamsEndPart>): ToolParamsEndPart

toolParamsStartPart

Since v1.0.0

Constructs a new tool params start part.

Signature

declare function toolParamsStartPart(params: ConstructorParams<ToolParamsStartPart>): ToolParamsStartPart

toolResultPart

Since v1.0.0

Constructs a new tool result part.

Signature

declare function toolResultPart<Params extends ConstructorParams<ToolResultPart<string, any, any>>>(params: Params): Params extends {
  readonly isFailure: false;
  readonly name: Name;
  readonly result: Success;
} ? ToolResultPart<Name, Success, never> : Params extends {
  readonly isFailure: true;
  readonly name: Name;
  readonly result: Failure;
} ? ToolResultPart<Name, never, Failure> : never

urlSourcePart

Since v1.0.0

Constructs a new URL source part.

Signature

declare function urlSourcePart(params: ConstructorParams<UrlSourcePart>): UrlSourcePart

Guards

isPart

Since v1.0.0

Type guard to check if a value is a Response Part.

Signature

declare function isPart(u: unknown): u is AnyPart

Models

AllParts

type
Since v1.0.0

Union type for all response parts with tool-specific typing.

Signature

type AllParts<Tools extends Record<string, Tool.Any>> = TextPart | TextStartPart | TextDeltaPart | TextEndPart | ReasoningPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallParts<Tools> | ToolResultParts<Tools> | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

AllPartsEncoded

type
Since v1.0.0

Encoded representation of all response parts for serialization.

Signature

type AllPartsEncoded = TextPartEncoded | TextStartPartEncoded | TextDeltaPartEncoded | TextEndPartEncoded | ReasoningPartEncoded | ReasoningStartPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolParamsStartPartEncoded | ToolParamsDeltaPartEncoded | ToolParamsEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded

AnyPart

type
Since v1.0.0

Union type representing all possible response content parts.

Signature

type AnyPart = TextPart | TextStartPart | TextDeltaPart | TextEndPart | ReasoningPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallPart<any, any> | ToolResultPart<any, any, any> | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

AnyPartEncoded

type
Since v1.0.0

Encoded representation of all possible response content parts for serialization.

Signature

type AnyPartEncoded = TextPartEncoded | TextStartPartEncoded | TextDeltaPartEncoded | TextEndPartEncoded | ReasoningPartEncoded | ReasoningStartPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolParamsStartPartEncoded | ToolParamsDeltaPartEncoded | ToolParamsEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded

BasePart

interface
Since v1.0.0

Base interface for all response content parts.

Provides common structure including type identifier and optional metadata.

Signature

interface BasePart<Type extends string, Metadata extends ProviderMetadata> {
  readonly "~effect/ai/Content/Part": "~effect/ai/Content/Part";
  readonly metadata: Metadata;
  readonly type: Type;
}

BasePartEncoded

interface
Since v1.0.0

Base interface for encoded response content parts.

Signature

interface BasePartEncoded<Type extends string, Metadata extends ProviderMetadata> {
  readonly metadata?: Metadata;
  readonly type: Type;
}

BaseToolResult

interface
Since v1.0.0

The base fields of a tool result part.

Signature

interface BaseToolResult<Name extends string> extends BasePart<"tool-result", ToolResultPartMetadata> {
  readonly encodedResult: unknown;
  readonly id: string;
  readonly name: Name;
  readonly providerExecuted: boolean;
  readonly providerName?: string;
}

DocumentSourcePart

interface
Since v1.0.0

Response part representing a document source reference.

Used to reference documents that were used in generating the response.

Signature

interface DocumentSourcePart extends BasePart<"source", DocumentSourcePartMetadata> {
  readonly fileName?: string;
  readonly id: string;
  readonly mediaType: string;
  readonly sourceType: "document";
  readonly title: string;
}

DocumentSourcePartEncoded

interface
Since v1.0.0

Encoded representation of document source parts for serialization.

Signature

interface DocumentSourcePartEncoded extends BasePartEncoded<"source", DocumentSourcePartMetadata> {
  readonly fileName?: string;
  readonly id: string;
  readonly mediaType: string;
  readonly sourceType: "document";
  readonly title: string;
}

ErrorPart

interface
Since v1.0.0

Response part indicating that an error occurred generating the response.

Signature

interface ErrorPart extends BasePart<"error", ErrorPartMetadata> {
  readonly error: unknown;
}

Example 

import { Response } from "@effect/ai"


const errorPart: Response.ErrorPart = Response.makePart("error", {
  error: new Error("boom")
})

ErrorPartEncoded

interface
Since v1.0.0

Encoded representation of error parts for serialization.

Signature

interface ErrorPartEncoded extends BasePartEncoded<"error", ErrorPartMetadata> {
  readonly error: unknown;
}

FilePart

interface
Since v1.0.0

Response part representing a file attachment.

Supports various file types including images, documents, and binary data.

Signature

interface FilePart extends BasePart<"file", FilePartMetadata> {
  readonly data: Uint8Array;
  readonly mediaType: string;
}

Example 

import { Response } from "@effect/ai"


const imagePart: Response.FilePart = Response.makePart("file", {
  mediaType: "image/jpeg",
  data: new Uint8Array([1, 2, 3]),
})

FilePartEncoded

interface
Since v1.0.0

Encoded representation of file parts for serialization.

Signature

interface FilePartEncoded extends BasePartEncoded<"file", FilePartMetadata> {
  readonly data: string;
  readonly mediaType: string;
}

FinishPart

interface
Since v1.0.0

Response part indicating the completion of a response generation.

Signature

interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
  readonly reason: ["stop", "length", "content-filter", "tool-calls", "error", "pause", "other", "unknown"];
  readonly usage: Usage;
}

Example 

import { Response } from "@effect/ai"


const finishPart: Response.FinishPart = Response.makePart("finish", {
  reason: "stop",
  usage: {
    inputTokens: 50,
    outputTokens: 25,
    totalTokens: 75
  }
})

FinishPartEncoded

interface
Since v1.0.0

Encoded representation of finish parts for serialization.

Signature

interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartMetadata> {
  readonly reason: ["stop", "length", "content-filter", "tool-calls", "error", "pause", "other", "unknown"];
  readonly usage: {
    readonly cachedInputTokens?: number;
    readonly inputTokens: number | undefined;
    readonly outputTokens: number | undefined;
    readonly reasoningTokens?: number;
    readonly totalTokens: number | undefined;
  };
}

FinishReason

Since v1.0.0

Represents the reason why a model finished generation of a response.

Possible finish reasons:

  • "stop": The model generated a stop sequence.
  • "length": The model exceeded its token budget.
  • "content-filter": The model generated content which violated a content filter.
  • "tool-calls": The model triggered a tool call.
  • "error": The model encountered an error.
  • "pause": The model requested to pause execution.
  • "other": The model stopped for a reason not supported by this protocol.
  • "unknown": The model did not specify a finish reason.

Signature

declare const FinishReason: Schema.Literal<["stop", "length", "content-filter", "tool-calls", "error", "pause", "other", "unknown"]>

FinishReason

type
Since v1.0.0

Signature

type FinishReason = typeof FinishReason.Type

Part

type
Since v1.0.0

A type for representing non-streaming response parts with tool-specific typing.

Signature

type Part<Tools extends Record<string, Tool.Any>, EncodedToolParameters extends boolean = false> = TextPart | ReasoningPart | ToolCallParts<Tools, EncodedToolParameters> | ToolResultParts<Tools> | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart

PartEncoded

type
Since v1.0.0

Encoded representation of non-streaming response parts for serialization.

Signature

type PartEncoded = TextPartEncoded | ReasoningPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded

ProviderMetadata

type
Since v1.0.0

Signature

type ProviderMetadata = typeof ProviderMetadata.Type

ReasoningDeltaPart

interface
Since v1.0.0

Response part containing incremental reasoning content to be added to the existing chunk of reasoning text with the same unique identifier.

Signature

interface ReasoningDeltaPart extends BasePart<"reasoning-delta", ReasoningDeltaPartMetadata> {
  readonly delta: string;
  readonly id: string;
}

ReasoningDeltaPartEncoded

interface
Since v1.0.0

Encoded representation of reasoning delta parts for serialization.

Signature

interface ReasoningDeltaPartEncoded extends BasePartEncoded<"reasoning-delta", ReasoningDeltaPartMetadata> {
  readonly delta: string;
  readonly id: string;
}

ReasoningEndPart

interface
Since v1.0.0

Response part indicating the end of streaming reasoning content.

Marks the completion of a chunk of reasoning content.

Signature

interface ReasoningEndPart extends BasePart<"reasoning-end", ReasoningEndPartMetadata> {
  readonly id: string;
}

ReasoningEndPartEncoded

interface
Since v1.0.0

Encoded representation of reasoning end parts for serialization.

Signature

interface ReasoningEndPartEncoded extends BasePartEncoded<"reasoning-end", ReasoningEndPartMetadata> {
  readonly id: string;
}

ReasoningPart

interface
Since v1.0.0

Response part representing reasoning or chain-of-thought content.

Contains the internal reasoning process or explanation from the large language model.

Signature

interface ReasoningPart extends BasePart<"reasoning", ReasoningPartMetadata> {
  readonly text: string;
}

Example 

import { Response } from "@effect/ai"


const reasoningPart: Response.ReasoningPart = Response.makePart("reasoning", {
  text: "Let me think step by step: First I need to analyze the user's question...",
})

ReasoningPartEncoded

interface
Since v1.0.0

Encoded representation of reasoning parts for serialization.

Signature

interface ReasoningPartEncoded extends BasePartEncoded<"reasoning", ReasoningPartMetadata> {
  readonly text: string;
}

ReasoningStartPart

interface
Since v1.0.0

Response part indicating the start of streaming reasoning content.

Marks the beginning of a reasoning chunk with a unique identifier.

Signature

interface ReasoningStartPart extends BasePart<"reasoning-start", ReasoningStartPartMetadata> {
  readonly id: string;
}

ReasoningStartPartEncoded

interface
Since v1.0.0

Encoded representation of reasoning start parts for serialization.

Signature

interface ReasoningStartPartEncoded extends BasePartEncoded<"reasoning-start", ReasoningStartPartMetadata> {
  readonly id: string;
}

ResponseMetadataPart

interface
Since v1.0.0

Response part containing metadata about the large language model response.

Signature

interface ResponseMetadataPart extends BasePart<"response-metadata", ResponseMetadataPartMetadata> {
  readonly id: Option<string>;
  readonly modelId: Option<string>;
  readonly timestamp: Option<Utc>;
}

Example 

import { Response } from "@effect/ai"
import { Option, DateTime } from "effect"


const metadataPart: Response.ResponseMetadataPart = Response.makePart("response-metadata", {
  id: Option.some("resp_123"),
  modelId: Option.some("gpt-4"),
  timestamp: Option.some(DateTime.unsafeNow())
})

ResponseMetadataPartEncoded

interface
Since v1.0.0

Encoded representation of response metadata parts for serialization.

Signature

interface ResponseMetadataPartEncoded extends BasePartEncoded<"response-metadata", ResponseMetadataPartMetadata> {
  readonly id?: string;
  readonly modelId?: string;
  readonly timestamp?: string;
}

StreamPart

type
Since v1.0.0

A type for representing streaming response parts with tool-specific typing.

Signature

type StreamPart<Tools extends Record<string, Tool.Any>, EncodedToolParameters extends boolean = false> = TextStartPart | TextDeltaPart | TextEndPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallParts<Tools, EncodedToolParameters> | ToolResultParts<Tools> | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

StreamPartEncoded

type
Since v1.0.0

Encoded representation of streaming response parts for serialization.

Signature

type StreamPartEncoded = TextStartPartEncoded | TextDeltaPartEncoded | TextEndPartEncoded | ReasoningStartPartEncoded | ReasoningDeltaPartEncoded | ReasoningEndPartEncoded | ToolParamsStartPartEncoded | ToolParamsDeltaPartEncoded | ToolParamsEndPartEncoded | ToolCallPartEncoded | ToolResultPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded

TextDeltaPart

interface
Since v1.0.0

Response part containing incremental text content to be added to the existing text chunk with the same unique identifier.

Signature

interface TextDeltaPart extends BasePart<"text-delta", TextDeltaPartMetadata> {
  readonly delta: string;
  readonly id: string;
}

TextDeltaPartEncoded

interface
Since v1.0.0

Encoded representation of text delta parts for serialization.

Signature

interface TextDeltaPartEncoded extends BasePartEncoded<"text-delta", TextDeltaPartMetadata> {
  readonly delta: string;
  readonly id: string;
}

TextEndPart

interface
Since v1.0.0

Response part indicating the end of streaming text content.

Marks the completion of a text chunk.

Signature

interface TextEndPart extends BasePart<"text-end", TextEndPartMetadata> {
  readonly id: string;
}

TextEndPartEncoded

interface
Since v1.0.0

Encoded representation of text end parts for serialization.

Signature

interface TextEndPartEncoded extends BasePartEncoded<"text-end", TextEndPartMetadata> {
  readonly id: string;
}

TextPart

interface
Since v1.0.0

Response part representing plain text content.

Signature

interface TextPart extends BasePart<"text", TextPartMetadata> {
  readonly text: string;
}

Example 

import { Response } from "@effect/ai"


const textPart: Response.TextPart = Response.makePart("text", {
  text: "The answer to your question is 42.",
})

TextPartEncoded

interface
Since v1.0.0

Encoded representation of text parts for serialization.

Signature

interface TextPartEncoded extends BasePartEncoded<"text", TextPartMetadata> {
  readonly text: string;
}

TextStartPart

interface
Since v1.0.0

Response part indicating the start of streaming text content.

Marks the beginning of a text chunk with a unique identifier.

Signature

interface TextStartPart extends BasePart<"text-start", TextStartPartMetadata> {
  readonly id: string;
}

TextStartPartEncoded

interface
Since v1.0.0

Encoded representation of text start parts for serialization.

Signature

interface TextStartPartEncoded extends BasePartEncoded<"text-start", TextStartPartMetadata> {
  readonly id: string;
}

ToolCallPart

interface
Since v1.0.0

Response part representing a tool call request.

Signature

interface ToolCallPart<Name extends string, Params> extends BasePart<"tool-call", ToolCallPartMetadata> {
  readonly id: string;
  readonly name: Name;
  readonly params: Params;
  readonly providerExecuted: boolean;
  readonly providerName?: string;
}

Example 

import { Response } from "@effect/ai"
import { Schema } from "effect"


const weatherParams = Schema.Struct({
  city: Schema.String,
  units: Schema.optional(Schema.Literal("celsius", "fahrenheit"))
})


const toolCallPart: Response.ToolCallPart<
  "get_weather",
  typeof weatherParams.fields
> = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco", units: "celsius" },
  providerExecuted: false,
})

ToolCallPartEncoded

interface
Since v1.0.0

Encoded representation of tool call parts for serialization.

Signature

interface ToolCallPartEncoded extends BasePartEncoded<"tool-call", ToolCallPartMetadata> {
  readonly id: string;
  readonly name: string;
  readonly params: unknown;
  readonly providerExecuted?: boolean;
  readonly providerName?: string;
}

ToolParamsDeltaPart

interface
Since v1.0.0

Response part containing incremental tool parameter content.

Represents a chunk of tool parameters being streamed, containing the incremental JSON content that forms the tool parameters.

Signature

interface ToolParamsDeltaPart extends BasePart<"tool-params-delta", ToolParamsDeltaPartMetadata> {
  readonly delta: string;
  readonly id: string;
}

ToolParamsDeltaPartEncoded

interface
Since v1.0.0

Encoded representation of tool params delta parts for serialization.

Signature

interface ToolParamsDeltaPartEncoded extends BasePartEncoded<"tool-params-delta", ToolParamsDeltaPartMetadata> {
  readonly delta: string;
  readonly id: string;
}

ToolParamsEndPart

interface
Since v1.0.0

Response part indicating the end of streaming tool parameters.

Marks the completion of a tool parameter stream, indicating that all parameter data has been sent and the tool call is ready to be executed.

Signature

interface ToolParamsEndPart extends BasePart<"tool-params-end", ToolParamsEndPartMetadata> {
  readonly id: string;
}

ToolParamsEndPartEncoded

interface
Since v1.0.0

Encoded representation of tool params end parts for serialization.

Signature

interface ToolParamsEndPartEncoded extends BasePartEncoded<"tool-params-end", ToolParamsEndPartMetadata> {
  readonly id: string;
}

ToolParamsStartPart

interface
Since v1.0.0

Response part indicating the start of streaming tool parameters.

Marks the beginning of tool parameter streaming with metadata about the tool call.

Signature

interface ToolParamsStartPart extends BasePart<"tool-params-start", ToolParamsStartPartMetadata> {
  readonly id: string;
  readonly name: string;
  readonly providerExecuted: boolean;
  readonly providerName?: string;
}

ToolParamsStartPartEncoded

interface
Since v1.0.0

Encoded representation of tool params start parts for serialization.

Signature

interface ToolParamsStartPartEncoded extends BasePartEncoded<"tool-params-start", ToolParamsStartPartMetadata> {
  readonly id: string;
  readonly name: string;
  readonly providerExecuted?: boolean;
  readonly providerName?: string;
}

ToolResultFailure

interface
Since v1.0.0

Represents a failed tool call result.

Signature

interface ToolResultFailure<Name extends string, Failure> extends BaseToolResult<Name> {
  readonly isFailure: true;
  readonly result: Failure;
}

ToolResultPart

type
Since v1.0.0

Response part representing the result of a tool call.

Signature

type ToolResultPart<Name extends string, Success, Failure> = ToolResultSuccess<Name, Success> | ToolResultFailure<Name, Failure>

Example 

import { Either } from "effect"
import { Response } from "@effect/ai"


interface WeatherData {
  temperature: number
  condition: string
  humidity: number
}


const toolResultPart: Response.ToolResultPart<
  "get_weather",
  WeatherData,
  never
> = Response.toolResultPart({
  id: "call_123",
  name: "get_weather",
  isFailure: false,
  result: {
    temperature: 22,
    condition: "sunny",
    humidity: 65
  },
  encodedResult: {
    temperature: 22,
    condition: "sunny",
    humidity: 65
  },
  providerExecuted: false
})

ToolResultPartEncoded

interface
Since v1.0.0

Encoded representation of tool result parts for serialization.

Signature

interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", ToolResultPartMetadata> {
  readonly id: string;
  readonly isFailure: boolean;
  readonly name: string;
  readonly providerExecuted?: boolean;
  readonly providerName?: string;
  readonly result: unknown;
}

ToolResultSuccess

interface
Since v1.0.0

Represents a successful tool call result.

Signature

interface ToolResultSuccess<Name extends string, Success> extends BaseToolResult<Name> {
  readonly isFailure: false;
  readonly result: Success;
}

UrlSourcePart

interface
Since v1.0.0

Response part representing a URL source reference.

Used to reference web URLs that were used in generating the response.

Signature

interface UrlSourcePart extends BasePart<"source", UrlSourcePartMetadata> {
  readonly id: string;
  readonly sourceType: "url";
  readonly title: string;
  readonly url: URL;
}

UrlSourcePartEncoded

interface
Since v1.0.0

Encoded representation of URL source parts for serialization.

Signature

interface UrlSourcePartEncoded extends BasePartEncoded<"source", UrlSourcePartMetadata> {
  readonly id: string;
  readonly sourceType: "url";
  readonly title: string;
  readonly url: string;
}

Usage

Since v1.0.0

Represents usage information for a request to a large language model provider.

If the model provider returns additional usage information than what is specified here, you can generally find that information under the provider metadata of the finish part of the response.

Signature

declare class Usage extends {
  readonly cachedInputTokens?: number;
  readonly inputTokens: number | undefined;
  readonly outputTokens: number | undefined;
  readonly reasoningTokens?: number;
  readonly totalTokens: number | undefined;
} {
  constructor(...args: [props: {
    readonly cachedInputTokens?: number;
    readonly inputTokens: number | undefined;
    readonly outputTokens: number | undefined;
    readonly reasoningTokens?: number;
    readonly totalTokens: number | undefined;
  }, options?: MakeOptions]);
}

ProviderOptions

DocumentSourcePartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a DocumentSourcePart through module augmentation.

Signature

interface DocumentSourcePartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ErrorPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ErrorPart through module augmentation.

Signature

interface ErrorPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

FilePartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a FilePart through module augmentation.

Signature

interface FilePartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

FinishPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a FinishPart through module augmentation.

Signature

interface FinishPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ReasoningDeltaPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ReasoningDeltaPart through module augmentation.

Signature

interface ReasoningDeltaPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ReasoningEndPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ReasoningEndPart through module augmentation.

Signature

interface ReasoningEndPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ReasoningPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ReasoningPart through module augmentation.

Signature

interface ReasoningPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ReasoningStartPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ReasoningStartPart through module augmentation.

Signature

interface ReasoningStartPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ResponseMetadataPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ResponseMetadataPart through module augmentation.

Signature

interface ResponseMetadataPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

TextDeltaPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a TextDeltaPart through module augmentation.

Signature

interface TextDeltaPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

TextEndPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a TextEndPart through module augmentation.

Signature

interface TextEndPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

TextPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a TextPart through module augmentation.

Signature

interface TextPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

TextStartPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a TextStartPart through module augmentation.

Signature

interface TextStartPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ToolCallPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ToolCallPart through module augmentation.

Signature

interface ToolCallPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ToolParamsDeltaPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ToolParamsDeltaPart through module augmentation.

Signature

interface ToolParamsDeltaPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ToolParamsEndPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ToolParamsEndPart through module augmentation.

Signature

interface ToolParamsEndPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ToolParamsStartPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ToolParamsStartPart through module augmentation.

Signature

interface ToolParamsStartPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

ToolResultPartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a ToolResultPart through module augmentation.

Signature

interface ToolResultPartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

UrlSourcePartMetadata

interface
Since v1.0.0

Represents provider-specific metadata that can be associated with a UrlSourcePart through module augmentation.

Signature

interface UrlSourcePartMetadata extends ProviderMetadata {
  [key: string]: unknown;
  [key: number]: unknown;
  [key: symbol]: unknown;
}

Schemas

AllParts

Since v1.0.0

Creates a Schema for all response parts based on a toolkit.

Generates a schema that includes all possible response parts, with tool call and tool result parts dynamically created based on the provided toolkit.

Signature

declare const AllParts: <T extends WithHandler<any> | Any>(toolkit: T) => any

Example 

import { Response, Tool, Toolkit } from "@effect/ai"
import { Schema } from "effect"


const myToolkit = Toolkit.make(
  Tool.make("GetWeather", {
    parameters: { city: Schema.String },
    success: Schema.Struct({ temperature: Schema.Number })
  })
)


const allPartsSchema = Response.AllParts(myToolkit)

DocumentSourcePart

Since v1.0.0

Schema for validation and encoding of document source parts.

Signature

declare const DocumentSourcePart: any

ErrorPart

Since v1.0.0

Schema for validation and encoding of error parts.

Signature

declare const ErrorPart: any

FilePart

Since v1.0.0

Schema for validation and encoding of file parts.

Signature

declare const FilePart: any

FinishPart

Since v1.0.0

Schema for validation and encoding of finish parts.

Signature

declare const FinishPart: any

Part

Since v1.0.0

Creates a Schema for non-streaming response parts based on a toolkit.

Signature

declare const Part: <T extends WithHandler<any> | Any>(toolkit: T) => any

ProviderMetadata

Since v1.0.0

Schema for provider-specific metadata which can be attached to response parts.

Provider-specific metadata is namespaced by provider and has the structure:

Signature

declare const ProviderMetadata: $Record<Key, Constraint>

Example 

{
  "<provider-specific-key>": {
    // Provider-specific metadata
  }
}

ReasoningDeltaPart

Since v1.0.0

Schema for validation and encoding of reasoning delta parts.

Signature

declare const ReasoningDeltaPart: any

ReasoningEndPart

Since v1.0.0

Schema for validation and encoding of reasoning end parts.

Signature

declare const ReasoningEndPart: any

ReasoningPart

Since v1.0.0

Schema for validation and encoding of reasoning parts.

Signature

declare const ReasoningPart: any

ReasoningStartPart

Since v1.0.0

Schema for validation and encoding of reasoning start parts.

Signature

declare const ReasoningStartPart: any

ResponseMetadataPart

Since v1.0.0

Schema for validation and encoding of response metadata parts.

Signature

declare const ResponseMetadataPart: any

StreamPart

Since v1.0.0

Creates a Schema for streaming response parts based on a toolkit.

Signature

declare const StreamPart: <T extends WithHandler<any> | Any>(toolkit: T) => any

TextDeltaPart

Since v1.0.0

Schema for validation and encoding of text delta parts.

Signature

declare const TextDeltaPart: any

TextEndPart

Since v1.0.0

Schema for validation and encoding of text end parts.

Signature

declare const TextEndPart: any

TextPart

Since v1.0.0

Schema for validation and encoding of text parts.

Signature

declare const TextPart: any

TextStartPart

Since v1.0.0

Schema for validation and encoding of text start parts.

Signature

declare const TextStartPart: any

ToolCallPart

Since v1.0.0

Creates a Schema for tool call parts with specific tool name and parameters.

Signature

declare const ToolCallPart: <Name extends string, Params extends AnyParametersSchema>(name: Name, params: Params) => any

ToolParamsDeltaPart

Since v1.0.0

Schema for validation and encoding of tool params delta parts.

Signature

declare const ToolParamsDeltaPart: any

ToolParamsEndPart

Since v1.0.0

Schema for validation and encoding of tool params end parts.

Signature

declare const ToolParamsEndPart: any

ToolParamsStartPart

Since v1.0.0

Schema for validation and encoding of tool params start parts.

Signature

declare const ToolParamsStartPart: any

ToolResultPart

Since v1.0.0

Creates a Schema for tool result parts with specific tool name and result type.

Signature

declare const ToolResultPart: <Name extends string, Success extends Any, Failure extends All>(name: Name, success: Success, failure: Failure) => any

UrlSourcePart

Since v1.0.0

Schema for validation and encoding of url source parts.

Signature

declare const UrlSourcePart: any

Type Ids

PartTypeId

Since v1.0.0

Unique identifier for Response Part instances.

Signature

declare const PartTypeId: "~effect/ai/Content/Part"

PartTypeId

type
Since v1.0.0

Type-level representation of the Response Part identifier.

Signature

type PartTypeId = typeof PartTypeId

Utility Types

ConstructorParams

type
Since v1.0.0

A utility type for specifying the parameters required to construct a specific response part.

Signature

type ConstructorParams<Part extends AnyPart> = Omit<Part, PartTypeId | "type" | "sourceType" | "metadata"> & {
  readonly metadata?: Part["metadata"];
}

ToolCallParts

type
Since v1.0.0

Utility type that extracts tool call parts from a set of tools.

Signature

type ToolCallParts<Tools extends Record<string, Tool.Any>, EncodedParameters extends boolean = false> = { [Name in keyof Tools]: Name extends string ? ToolCallPart<Name, EncodedParameters extends true ? Tool.ParametersEncoded<Tools[Name]> : Tool.Parameters<Tools[Name]>> : never }[keyof Tools]

ToolResultParts

type
Since v1.0.0

Utility type that extracts tool result parts from a set of tools.

Signature

type ToolResultParts<Tools extends Record<string, Tool.Any>> = { [Name in keyof Tools]: Name extends string ? ToolResultPart<Name, Tool.Success<Tools[Name]>, Tool.Failure<Tools[Name]>> : never }[keyof Tools]