Response unstable

Defines a shared data model for AI model output.

Responses are represented as typed parts so different providers can expose text, reasoning, tool calls, files, sources, metadata, finish information, and errors through one shape. The same model is used for complete responses and streaming responses, where start, delta, and end parts describe content as it arrives. This module also carries provider metadata and schemas used by tools that need to validate response parts.

112 exports Since v4.0.0 Source

Configuration

DocumentSourcePartMetadata

interface unstable

Since v4.0.0

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

Signature

interface DocumentSourcePartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ErrorPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ErrorPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

FilePartMetadata

interface unstable

Since v4.0.0

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

Signature

interface FilePartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

FinishPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface FinishPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ReasoningDeltaPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ReasoningDeltaPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ReasoningEndPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ReasoningEndPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ReasoningPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ReasoningPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ReasoningStartPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ReasoningStartPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ResponseMetadataPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ResponseMetadataPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

TextDeltaPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface TextDeltaPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

TextEndPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface TextEndPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

TextPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface TextPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

TextStartPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface TextStartPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ToolApprovalRequestPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ToolApprovalRequestPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ToolCallPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ToolCallPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ToolParamsDeltaPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ToolParamsDeltaPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ToolParamsEndPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ToolParamsEndPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ToolParamsStartPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ToolParamsStartPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

ToolResultPartMetadata

interface unstable

Since v4.0.0

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

Signature

interface ToolResultPartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

UrlSourcePartMetadata

interface unstable

Since v4.0.0

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

Signature

interface UrlSourcePartMetadata extends ProviderMetadata {
  [key: string]: Json;
}

Constructors

makePart

unstable

Since v4.0.0

Creates a new response content part of the specified type.

Signature

declare function makePart<Type extends "error" | "source" | "tool-approval-request" | "file" | "response-metadata" | "finish" | "text" | "reasoning" | "tool-call" | "text-start" | "text-delta" | "text-end" | "reasoning-start" | "reasoning-delta" | "reasoning-end" | "tool-params-start" | "tool-params-delta" | "tool-params-end" | "tool-result">(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<ToolApprovalRequestPart, {
  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" | "metadata" | "~effect/ai/Response/Part"> & {
  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<ToolApprovalRequestPart, {
    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<ToolApprovalRequestPart, {
  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 Creating response content parts

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
})

const result = [textPart.type, toolCallPart.name] // => ["text", "get_weather"]

toolApprovalRequestPart

unstable

Since v4.0.0

Constructs a new tool approval request part.

Signature

declare function toolApprovalRequestPart(params: ConstructorParams<ToolApprovalRequestPart>): ToolApprovalRequestPart

toolCallPart

unstable

Since v4.0.0

Constructs a new tool call part.

Signature

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

toolResultPart

unstable

Since v4.0.0

Constructs a new tool result part.

Signature

declare function toolResultPart<Params extends ConstructorParams<ToolResultPart<string, unknown, unknown>>>(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

Guards

isPart

unstable

Since v4.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 unstable

Since v4.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> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

AllPartsEncoded

type unstable

Since v4.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 | ToolApprovalRequestPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded

AnyPart

type unstable

Since v4.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> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

AnyPartEncoded

type unstable

Since v4.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 | ToolApprovalRequestPartEncoded | FilePartEncoded | DocumentSourcePartEncoded | UrlSourcePartEncoded | ResponseMetadataPartEncoded | FinishPartEncoded | ErrorPartEncoded

BasePart

interface unstable

Since v4.0.0

Base interface for all response content parts, including the type identifier and optional metadata.

Signature

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

BasePartEncoded

interface unstable

Since v4.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 unstable

Since v4.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 preliminary: boolean;
  readonly providerExecuted: boolean;
}

DocumentSourcePart

interface unstable

Since v4.0.0

Response part representing a document source reference 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 unstable

Since v4.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 unstable

Since v4.0.0

Response part indicating that an error occurred generating the response.

Signature

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

Example Creating an error part

import { Response } from "effect/ai"

const errorPart: Response.ErrorPart = Response.makePart("error", {
  error: new Error("boom")
})
const result = [errorPart.type, errorPart.error instanceof Error] // => ["error", true]

ErrorPartEncoded

interface unstable

Since v4.0.0

Encoded representation of error parts for serialization.

Signature

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

FilePart

interface unstable

Since v4.0.0

Response part representing a file attachment.

Details

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

Signature

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

Example Creating a file part

import { Response } from "effect/ai"

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

FilePartEncoded

interface unstable

Since v4.0.0

Encoded representation of file parts for serialization.

Signature

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

FinishPart

interface unstable

Since v4.0.0

Response part indicating the completion of a response generation.

Signature

interface FinishPart extends BasePart<"finish", FinishPartMetadata> {
  readonly reason: "length" | "error" | "stop" | "content-filter" | "tool-calls" | "pause" | "other" | "unknown";
  readonly response?: {
    readonly headers: {
      [key: string]: string | Redacted<string>;
    };
    readonly status: number;
  };
  readonly usage: Usage;
}

Example Creating a finish part

import { Response } from "effect/ai"

const finishPart: Response.FinishPart = Response.makePart("finish", {
  reason: "stop",
  usage: new Response.Usage({
    inputTokens: {
      uncached: undefined,
      total: 50,
      cacheRead: undefined,
      cacheWrite: undefined
    },
    outputTokens: {
      total: 25,
      text: undefined,
      reasoning: undefined
    }
  }),
  response: undefined
})
const result = [finishPart.reason, finishPart.usage.inputTokens.total] // => ["stop", 50]

FinishPartEncoded

interface unstable

Since v4.0.0

Encoded representation of finish parts for serialization.

Signature

interface FinishPartEncoded extends BasePartEncoded<"finish", FinishPartMetadata> {
  readonly reason: "length" | "error" | "stop" | "content-filter" | "tool-calls" | "pause" | "other" | "unknown";
  readonly response?: {
    readonly headers: {
      [key: string]: string | Redacted<string>;
    };
    readonly status: number;
  };
  readonly usage: {
    readonly inputTokens: {
      readonly cacheRead?: number;
      readonly cacheWrite?: number;
      readonly total?: number;
      readonly uncached?: number;
    };
    readonly outputTokens: {
      readonly reasoning?: number;
      readonly text?: number;
      readonly total?: number;
    };
  };
}

FinishReason

unstable

Since v4.0.0

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

Details

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.Literals<["stop", "length", "content-filter", "tool-calls", "error", "pause", "other", "unknown"]>

FinishReason

type unstable

Since v4.0.0

Type of the reason why a model stopped generating a response.

Details

Values include normal stops, token-limit stops, content filtering, tool-call pauses, provider errors, and unknown provider-specific finish reasons.

Signature

type FinishReason = typeof FinishReason.Type

Part

type unstable

Since v4.0.0

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

Signature

type Part<Tools extends Record<string, Tool.Any>, ParametersMode extends ToolParametersMode = "decoded"> = TextPart | ReasoningPart | ToolCallParts<Tools, ParametersMode> | ToolResultParts<Tools> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart

PartEncoded

type unstable

Since v4.0.0

Encoded representation of non-streaming response parts for serialization.

Signature

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

ProviderMetadata

type unstable

Since v4.0.0

Type of provider-specific metadata attached to response parts, keyed by provider-specific names with JSON or null values.

Signature

type ProviderMetadata = typeof ProviderMetadata.Type

ReasoningDeltaPart

interface unstable

Since v4.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 unstable

Since v4.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 unstable

Since v4.0.0

Response part indicating the completion of a streaming reasoning chunk.

Signature

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

ReasoningEndPartEncoded

interface unstable

Since v4.0.0

Encoded representation of reasoning end parts for serialization.

Signature

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

ReasoningPart

interface unstable

Since v4.0.0

Response part carrying provider-supplied reasoning text, such as an exposed reasoning summary or explanation. Do not assume it contains hidden chain-of-thought.

Signature

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

Example Creating a reasoning part

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..."
})
reasoningPart.type // => "reasoning"

ReasoningPartEncoded

interface unstable

Since v4.0.0

Encoded representation of reasoning parts for serialization.

Signature

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

ReasoningStartPart

interface unstable

Since v4.0.0

Response part indicating the start of streaming reasoning content with a unique reasoning chunk identifier.

Signature

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

ReasoningStartPartEncoded

interface unstable

Since v4.0.0

Encoded representation of reasoning start parts for serialization.

Signature

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

ResponseMetadataPart

interface unstable

Since v4.0.0

Response part containing metadata about the large language model response.

Signature

interface ResponseMetadataPart extends BasePart<"response-metadata", ResponseMetadataPartMetadata> {
  readonly id?: string;
  readonly modelId?: string;
  readonly request?: {
    readonly hash?: string;
    readonly headers: {
      [key: string]: string | Redacted<string>;
    };
    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE" | "QUERY";
    readonly url: string;
    readonly urlParams: readonly Array<readonly [string, string | Redacted<string>]>;
  };
  readonly timestamp?: Utc;
}

Example Creating a metadata part

import { DateTime } from "effect"
import { Response } from "effect/ai"

const metadataPart: Response.ResponseMetadataPart = Response.makePart(
  "response-metadata",
  {
    id: "resp_123",
    modelId: "gpt-4",
    timestamp: DateTime.makeUnsafe("2024-01-01T00:00:00Z"),
    request: undefined
  }
)
const result = [metadataPart.id, metadataPart.modelId] // => ["resp_123", "gpt-4"]

ResponseMetadataPartEncoded

interface unstable

Since v4.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 request?: {
    readonly hash?: string;
    readonly headers: {
      [key: string]: string | Redacted<string>;
    };
    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "TRACE" | "QUERY";
    readonly url: string;
    readonly urlParams: readonly Array<readonly [string, string | Redacted<string>]>;
  };
  readonly timestamp?: string;
}

StreamPart

type unstable

Since v4.0.0

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

Signature

type StreamPart<Tools extends Record<string, Tool.Any>, ParametersMode extends ToolParametersMode = "decoded"> = TextStartPart | TextDeltaPart | TextEndPart | ReasoningStartPart | ReasoningDeltaPart | ReasoningEndPart | ToolParamsStartPart | ToolParamsDeltaPart | ToolParamsEndPart | ToolCallParts<Tools, ParametersMode> | ToolResultParts<Tools> | ToolApprovalRequestPart | FilePart | DocumentSourcePart | UrlSourcePart | ResponseMetadataPart | FinishPart | ErrorPart

StreamPartEncoded

type unstable

Since v4.0.0

Encoded representation of streaming response parts for serialization.

Signature

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

TextDeltaPart

interface unstable

Since v4.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 unstable

Since v4.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 unstable

Since v4.0.0

Response part indicating the completion of a streaming text chunk.

Signature

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

TextEndPartEncoded

interface unstable

Since v4.0.0

Encoded representation of text end parts for serialization.

Signature

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

TextPart

interface unstable

Since v4.0.0

Response part representing plain text content.

Signature

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

Example Creating a text part

import { Response } from "effect/ai"

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

TextPartEncoded

interface unstable

Since v4.0.0

Encoded representation of text parts for serialization.

Signature

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

TextStartPart

interface unstable

Since v4.0.0

Response part indicating the start of streaming text content with a unique text chunk identifier.

Signature

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

TextStartPartEncoded

interface unstable

Since v4.0.0

Encoded representation of text start parts for serialization.

Signature

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

ToolApprovalRequestPart

interface unstable

Since v4.0.0

Response part representing a tool approval request.

Details

Emitted when a tool requires user approval before execution. The framework checks the tool's needsApproval property and emits this part instead of executing the tool when approval is required.

Signature

interface ToolApprovalRequestPart extends BasePart<"tool-approval-request", ToolApprovalRequestPartMetadata> {
  readonly approvalId: string;
  readonly toolCallId: string;
}

Example Creating an approval request part

import { Response } from "effect/ai"

const approvalRequest: Response.ToolApprovalRequestPart = Response.makePart(
  "tool-approval-request",
  {
    approvalId: "approval_123",
    toolCallId: "call_456"
  }
)
const result = [approvalRequest.approvalId, approvalRequest.toolCallId] // => ["approval_123", "call_456"]

ToolApprovalRequestPartEncoded

interface unstable

Since v4.0.0

Encoded representation of tool approval request parts for serialization.

Signature

interface ToolApprovalRequestPartEncoded extends BasePartEncoded<"tool-approval-request", ToolApprovalRequestPartMetadata> {
  readonly approvalId: string;
  readonly toolCallId: string;
}

ToolCallPart

interface unstable

Since v4.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;
}

Example Creating a tool call part

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

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

const toolCallPart: Response.ToolCallPart<
  "get_weather",
  {
    readonly city: string
    readonly units?: "celsius" | "fahrenheit"
  }
> = Response.makePart("tool-call", {
  id: "call_123",
  name: "get_weather",
  params: { city: "San Francisco", units: "celsius" },
  providerExecuted: false
})
const result = [toolCallPart.name, toolCallPart.params.city] // => ["get_weather", "San Francisco"]

ToolCallPartEncoded

interface unstable

Since v4.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;
}

ToolParamsDeltaPart

interface unstable

Since v4.0.0

Response part containing incremental tool parameter content.

Details

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 unstable

Since v4.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 unstable

Since v4.0.0

Response part indicating the end of streaming tool parameters.

Details

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 unstable

Since v4.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 unstable

Since v4.0.0

Response part indicating the start of streaming tool parameters.

Details

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;
}

ToolParamsStartPartEncoded

interface unstable

Since v4.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;
}

ToolResultFailure

interface unstable

Since v4.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 unstable

Since v4.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 Creating a tool result part

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,
  preliminary: false
})
const result = [toolResultPart.name, toolResultPart.result.temperature] // => ["get_weather", 22]

ToolResultPartEncoded

interface unstable

Since v4.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 preliminary?: boolean;
  readonly providerExecuted?: boolean;
  readonly result: unknown;
}

ToolResultSuccess

interface unstable

Since v4.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 unstable

Since v4.0.0

Response part representing a URL source reference 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 unstable

Since v4.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

unstable

Since v4.0.0

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

Details

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 inputTokens: {
    readonly cacheRead?: number;
    readonly cacheWrite?: number;
    readonly total?: number;
    readonly uncached?: number;
  };
  readonly outputTokens: {
    readonly reasoning?: number;
    readonly text?: number;
    readonly total?: number;
  };
} {
  constructor(...args: [props: {
    readonly inputTokens: {
      readonly cacheRead?: number;
      readonly cacheWrite?: number;
      readonly total?: number;
      readonly uncached?: number;
    };
    readonly outputTokens: {
      readonly reasoning?: number;
      readonly text?: number;
      readonly total?: number;
    };
  }, options?: MakeOptions]);
}

Schemas

AllParts

unstable

Since v4.0.0

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

Details

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) => Codec<AllParts<T extends Any ? Tools<T> : WithHandlerTools<T>>, AllPartsEncoded, ResultDecodingServices<Tools<T>[keyof Tools<T>]>, ResultEncodingServices<Tools<T>[keyof Tools<T>]>>

Example Building a response parts schema

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

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

const allPartsSchema = Response.AllParts(myToolkit)
Schema.isSchema(allPartsSchema) // => true

DocumentSourcePart

unstable

Since v4.0.0

Schema for validation and encoding of document source parts.

When to use

Use to validate or encode document source references returned as response content parts.

Details

Validates type: "source", sourceType: "document", required id, mediaType, and title, optional fileName, and the metadata fields inherited from response parts.

See

UrlSourcePart for URL source references
DocumentSourcePartEncoded for the encoded document source representation

Signature

declare const DocumentSourcePart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly fileName: optionalKey<String>;
  readonly id: String;
  readonly mediaType: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly sourceType: tag<"document">;
  readonly title: String;
  readonly type: tag<"source">;
}>

ErrorPart

unstable

Since v4.0.0

Schema for validation and encoding of error parts.

Details

Validates and encodes error parts with type: "error" and an error payload kept as unknown.

Gotchas

The decoded error value is not guaranteed to be an Error; narrow it before reading Error-specific fields.

Signature

declare const ErrorPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly error: Unknown;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"error">;
}>

FilePart

unstable

Since v4.0.0

Schema for validation and encoding of file parts.

Details

Decoded data is a Uint8Array; encoded data is a base64 string through Schema.Uint8ArrayFromBase64.

Signature

declare const FilePart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly data: Uint8ArrayFromBase64;
  readonly mediaType: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"file">;
}>

FinishPart

unstable

Since v4.0.0

Schema for finish response parts.

Details

Validates type: "finish", reason through FinishReason, usage through Usage, and optional provider HTTP response details.

Signature

declare const FinishPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly reason: Literals<["stop", "length", "content-filter", "tool-calls", "error", "pause", "other", "unknown"]>;
  readonly response: optional<Struct<{
    readonly headers: $Record<String, Union<readonly [String, Redacted<String>]>>;
    readonly status: Int;
  }>>;
  readonly type: tag<"finish">;
  readonly usage: typeof Usage;
}>

HttpRequestDetails

unstable

Since v4.0.0

Alias of AiError.HttpRequestDetails.

Signature

declare const HttpRequestDetails: Struct<{
  readonly hash: optional<String>;
  readonly headers: $Record<String, Union<readonly [String, Redacted<String>]>>;
  readonly method: Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE", "QUERY"]>;
  readonly url: String;
  readonly urlParams: $Array<Tuple<readonly [String, Union<readonly [String, Redacted<String>]>]>>;
}>

HttpResponseDetails

unstable

Since v4.0.0

Alias of AiError.HttpResponseDetails.

Signature

declare const HttpResponseDetails: Struct<{
  readonly headers: $Record<String, Union<readonly [String, Redacted<String>]>>;
  readonly status: Int;
}>

Part

unstable

Since v4.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) => Codec<Part<T extends Any ? Tools<T> : WithHandlerTools<T>, "decoded">, PartEncoded, ResultDecodingServices<Tools<T>[keyof Tools<T>]>, ResultEncodingServices<Tools<T>[keyof Tools<T>]>>

ProviderMetadata

unstable

Since v4.0.0

Schema for provider-specific metadata attached to response parts, represented as a record from provider-specific keys to JSON values or null.

Signature

declare const ProviderMetadata: Schema.$Record<Schema.String, Schema.NullOr<Schema.Codec<Schema.Json>>>

ReasoningDeltaPart

unstable

Since v4.0.0

Schema for validation and encoding of reasoning delta parts.

Signature

declare const ReasoningDeltaPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly delta: String;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"reasoning-delta">;
}>

ReasoningEndPart

unstable

Since v4.0.0

Schema for validation and encoding of reasoning end parts.

Signature

declare const ReasoningEndPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"reasoning-end">;
}>

ReasoningPart

unstable

Since v4.0.0

Schema for validation and encoding of reasoning parts.

Signature

declare const ReasoningPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly text: String;
  readonly type: tag<"reasoning">;
}>

ReasoningStartPart

unstable

Since v4.0.0

Schema for validation and encoding of reasoning start parts.

Signature

declare const ReasoningStartPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"reasoning-start">;
}>

ResponseMetadataPart

unstable

Since v4.0.0

Schema for validation and encoding of response metadata parts.

Signature

declare const ResponseMetadataPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: optional<String>;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly modelId: optional<String>;
  readonly request: optional<Struct<{
    readonly hash: optional<String>;
    readonly headers: $Record<String, Union<readonly [String, Redacted<String>]>>;
    readonly method: Literals<readonly ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS", "TRACE", "QUERY"]>;
    readonly url: String;
    readonly urlParams: $Array<Tuple<readonly [String, Union<readonly [String, Redacted<...>]>]>>;
  }>>;
  readonly timestamp: optional<DateTimeUtcFromString>;
  readonly type: tag<"response-metadata">;
}>

StreamPart

unstable

Since v4.0.0

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

Signature

declare const StreamPart: <T extends WithHandler<any> | Any>(toolkit: T) => Codec<StreamPart<T extends Any ? Tools<T> : WithHandlerTools<T>, "decoded">, StreamPartEncoded, ResultDecodingServices<Tools<T>[keyof Tools<T>]>, ResultEncodingServices<Tools<T>[keyof Tools<T>]>>

TextDeltaPart

unstable

Since v4.0.0

Schema for validation and encoding of text delta parts.

Signature

declare const TextDeltaPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly delta: String;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"text-delta">;
}>

TextEndPart

unstable

Since v4.0.0

Schema for validation and encoding of text end parts.

Signature

declare const TextEndPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"text-end">;
}>

TextPart

unstable

Since v4.0.0

Schema for validation and encoding of text parts.

Signature

declare const TextPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly text: String;
  readonly type: tag<"text">;
}>

TextStartPart

unstable

Since v4.0.0

Schema for validation and encoding of text start parts.

Signature

declare const TextStartPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"text-start">;
}>

ToolApprovalRequestPart

unstable

Since v4.0.0

Schema for validation and encoding of tool approval request parts.

Signature

declare const ToolApprovalRequestPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly approvalId: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly toolCallId: String;
  readonly type: tag<"tool-approval-request">;
}>

ToolCallPart

unstable

Since v4.0.0

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

Signature

declare const ToolCallPart: <Name extends string, Params extends Constraint>(name: Name, params: Params) => Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly name: Literal<Name>;
  readonly params: Params;
  readonly providerExecuted: withDecodingDefaultKey<Boolean>;
  readonly type: Literal<"tool-call">;
}>

ToolParamsDeltaPart

unstable

Since v4.0.0

Schema for validation and encoding of tool params delta parts.

Signature

declare const ToolParamsDeltaPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly delta: String;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"tool-params-delta">;
}>

ToolParamsEndPart

unstable

Since v4.0.0

Schema for validation and encoding of tool params end parts.

Signature

declare const ToolParamsEndPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly type: tag<"tool-params-end">;
}>

ToolParamsStartPart

unstable

Since v4.0.0

Schema for validation and encoding of tool params start parts.

Signature

declare const ToolParamsStartPart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly name: String;
  readonly providerExecuted: withDecodingDefaultKey<Boolean>;
  readonly type: tag<"tool-params-start">;
}>

ToolResultPart

unstable

Since v4.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 Constraint, Failure extends Constraint>(name: Name, success: Success, failure: Failure) => Codec<ToolResultPart<Name, Success["Type"], Failure["Type"]>, ToolResultPartEncoded, Success["DecodingServices"] | Failure["DecodingServices"], Success["EncodingServices"] | Failure["EncodingServices"]>

UrlSourcePart

unstable

Since v4.0.0

Schema for validation and encoding of url source parts.

Signature

declare const UrlSourcePart: Struct<{
  readonly "~effect/ai/Response/Part": withDecodingDefaultKey<tag<"~effect/ai/Response/Part">>;
  readonly id: String;
  readonly metadata: withDecodingDefault<$Record<String, Codec<Json, Json, never, never>>>;
  readonly sourceType: tag<"url">;
  readonly title: String;
  readonly type: tag<"source">;
  readonly url: URLFromString;
}>

Utility Types

ConstructorParams

type unstable

Since v4.0.0

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

Signature

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

ToolCallParts

type unstable

Since v4.0.0

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

Signature

type ToolCallParts<Tools extends Record<string, Tool.Any>, ParametersMode extends ToolParametersMode = "decoded"> = ParametersMode extends "deferred" ? ToolCallPartForName<Tools, "opaque", keyof Tools> | ToolCallPart<string, unknown> : ToolCallPartForName<Tools, ParametersMode, keyof Tools>

ToolParametersMode

type unstable

Since v4.0.0

Controls tool parameter decoding. "deferred" allows undeclared tool names with opaque parameters, leaving validation to the caller.

Signature

type ToolParametersMode = "decoded" | "encoded" | "opaque" | "deferred"

ToolResultParts

type unstable

Since v4.0.0

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

Signature

type ToolResultParts<Tools extends Record<string, Tool.Any>> = ToolResultPartForName<Tools, keyof Tools>