Interface: TextOptions<TProviderOptionsSuperset, TProviderOptionsForModel, TContext>

Defined in: packages/ai/src/types.ts:873

Options passed into the SDK and further piped to the AI provider.

Type Parameters

TProviderOptionsSuperset

TProviderOptionsSuperset extends Record<string, any> = Record<string, any>

TProviderOptionsForModel

TProviderOptionsForModel = TProviderOptionsSuperset

TContext

TContext = unknown

Properties

abortController?

optional abortController: AbortController;

Defined in: packages/ai/src/types.ts:988

AbortController for request cancellation.

Allows you to cancel an in-progress request using an AbortController. Useful for implementing timeouts or user-initiated cancellations.

Example

const abortController = new AbortController();
setTimeout(() => abortController.abort(), 5000); // Cancel after 5 seconds
await chat({ ..., abortController });

See

https://developer.mozilla.org/en-US/docs/Web/API/AbortController

agentLoopStrategy?

optional agentLoopStrategy: AgentLoopStrategy;

Defined in: packages/ai/src/types.ts:901

approvals?

optional approvals: ReadonlyMap<string, boolean>;

Defined in: packages/ai/src/types.ts:1031

Client approval decisions for this run, keyed by approval id. The engine populates this from approvals carried on the incoming messages. Harness adapters consult it to resolve ask-policy permission requests (the agent pauses on a risky action; the client re-runs with a decision recorded here). Undefined for direct adapter usage outside the chat engine.

capabilities?

optional capabilities: CapabilityContext;

Defined in: packages/ai/src/types.ts:1022

Middleware capability context for this run. The engine populates it with the live middleware context so harness adapters that declare requires: [SomeCapability] can read provided capabilities from inside chatStream — e.g. getSandbox(options.capabilities). Capabilities are provisioned by middleware setup before the adapter runs. Undefined for direct adapter usage outside the chat engine.

context?

optional context: TContext;

Defined in: packages/ai/src/types.ts:885

Runtime context provided by the caller and passed to middleware and server-side tool implementations.

conversationId?

optional conversationId: string;

Defined in: packages/ai/src/types.ts:974

Deprecated

Use threadId instead. conversationId is the legacy pre-AG-UI name for the same concept (a stable per-conversation identifier used to correlate client/server devtools events). When conversationId is omitted, the runtime falls back to threadId automatically, so most callers can simply pass threadId (or rely on chatParamsFromRequest, which surfaces it on params).

Will be removed in a future major release.

lazyToolsConfig?

optional lazyToolsConfig: LazyToolsConfig;

Defined in: packages/ai/src/types.ts:925

Optional configuration for lazy-tool discovery (tools marked lazy: true). Tunes how much of each lazy tool's description appears in the discovery catalog. Optional — defaults to { includeDescription: 'none' }.

logger

logger: InternalLogger;

Defined in: packages/ai/src/types.ts:995

Internal logger threaded from the chat entry point. Adapter implementations must call logger.request() before SDK calls, logger.provider() for each chunk received, and logger.errors() in catch blocks.

maxToolCallsPerTurn?

optional maxToolCallsPerTurn: number;

Defined in: packages/ai/src/types.ts:919

Maximum number of tool calls to execute from a single model turn (or pending/resume batch). 0 skips all execution for that batch.

Models can emit many parallel tool calls in one turn. agentLoopStrategy (including maxIterations / maxToolCalls) is only evaluated between turns, so without this cap a single runaway turn can still execute an unbounded fan-out.

When set, only the first maxToolCallsPerTurn calls are executed; the remainder receive error tool results so the message history stays consistent. Unset means no per-turn execution cap. Must be a non-negative finite number when set.

Pair with the maxToolCalls(n) strategy for a cumulative emitted-call budget across the run (skipped calls still count toward that budget).

messages

messages: ModelMessage<
  | string
  | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
  | null>[];

Defined in: packages/ai/src/types.ts:879

metadata?

optional metadata: Record<string, any>;

Defined in: packages/ai/src/types.ts:936

Observability metadata attached to this call. Surfaced to middleware, devtools, and the event client; values may be arbitrarily structured (objects, arrays). Adapters never forward this field onto the provider wire request.

To send provider-side request metadata, use the provider's modelOptions field instead, where the provider supports one (e.g. OpenAI's and OpenRouter's metadata are both Record).

model

model: string;

Defined in: packages/ai/src/types.ts:878

modelOptions?

optional modelOptions: TProviderOptionsForModel;

Defined in: packages/ai/src/types.ts:937

outputSchema?

optional outputSchema: SchemaInput;

Defined in: packages/ai/src/types.ts:963

Schema for structured output.

Two distinct use sites:

User-facing (activity layer): accepts any SchemaInput — Zod, ArkType, Valibot, or a raw JSON Schema. The activity layer converts to JSON Schema before handing off.
Adapter-facing (chatStream call): the engine populates this with a pre-converted JSON Schema only when the adapter declared supportsCombinedToolsAndSchema(modelOptions) === true. The adapter should then wire the schema into the upstream request (e.g. response_format: { type: 'json_schema', ... }, text.format, output_format) alongside any tools. The model's natural final turn carries the schema-constrained JSON text and the engine harvests it from the agent loop without a separate finalization round-trip.
Adapters that did NOT declare the capability never see this field populated — the engine instead invokes structuredOutput / structuredOutputStream after the agent loop.

parentRunId?

optional parentRunId: string;

Defined in: packages/ai/src/types.ts:1012

Parent run ID for AG-UI protocol nested run correlation. Surfaced for observability/middleware; not consumed by the LLM call.

request?

optional request: Request | RequestInit;

Defined in: packages/ai/src/types.ts:938

runId?

optional runId: string;

Defined in: packages/ai/src/types.ts:1007

Run ID for AG-UI protocol run correlation. When provided, this will be used in RunStartedEvent and RunFinishedEvent. If not provided, a unique ID will be generated.

systemPrompts?

optional systemPrompts: SystemPrompt[];

Defined in: packages/ai/src/types.ts:900

System prompts to include with the request.

Accepts plain strings (the common case) or { content, metadata } objects that let providers attach typed metadata (e.g. Anthropic cache_control for prompt caching) per prompt. At the chat call site the adapter narrows metadata's type via ~types['systemPromptMetadata'] — providers that don't declare one default to never, which makes the field carry no meaningful value (TypeScript will only accept undefined there). Provider-foreign metadata that reaches an adapter via JS / as any is silently dropped, never written to the wire.