Open History to see the last commit
1---
2id: TextOptions
3title: TextOptions
4---
5
6# Interface: TextOptions\<TProviderOptionsSuperset, TProviderOptionsForModel, TContext\>
7
8Defined in: [packages/ai/src/types.ts:873](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L873)
9
10Options passed into the SDK and further piped to the AI provider.
11
12## Type Parameters
13
14### TProviderOptionsSuperset
15
16`TProviderOptionsSuperset` *extends* `Record`\<`string`, `any`\> = `Record`\<`string`, `any`\>
17
18### TProviderOptionsForModel
19
20`TProviderOptionsForModel` = `TProviderOptionsSuperset`
21
22### TContext
23
24`TContext` = `unknown`
25
26## Properties
27
28### abortController?
29
30```ts
31optional abortController: AbortController;
32```
33
34Defined in: [packages/ai/src/types.ts:988](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L988)
35
36AbortController for request cancellation.
37
38Allows you to cancel an in-progress request using an AbortController.
39Useful for implementing timeouts or user-initiated cancellations.
40
41#### Example
42
43```ts
44const abortController = new AbortController();
45setTimeout(() => abortController.abort(), 5000); // Cancel after 5 seconds
46await chat({ ..., abortController });
47```
48
49#### See
50
51https://developer.mozilla.org/en-US/docs/Web/API/AbortController
52
53***
54
55### agentLoopStrategy?
56
57```ts
58optional agentLoopStrategy: AgentLoopStrategy;
59```
60
61Defined in: [packages/ai/src/types.ts:901](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L901)
62
63***
64
65### approvals?
66
67```ts
68optional approvals: ReadonlyMap<string, boolean>;
69```
70
71Defined in: [packages/ai/src/types.ts:1031](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1031)
72
73Client approval decisions for this run, keyed by approval id. The engine
74populates this from approvals carried on the incoming messages. Harness
75adapters consult it to resolve `ask`-policy permission requests (the agent
76pauses on a risky action; the client re-runs with a decision recorded
77here). Undefined for direct adapter usage outside the chat engine.
78
79***
80
81### capabilities?
82
83```ts
84optional capabilities: CapabilityContext;
85```
86
87Defined in: [packages/ai/src/types.ts:1022](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1022)
88
89Middleware capability context for this run. The engine populates it with
90the live middleware context so harness adapters that declare
91`requires: [SomeCapability]` can read provided capabilities from inside
92`chatStream` — e.g. `getSandbox(options.capabilities)`. Capabilities are
93provisioned by middleware `setup` before the adapter runs. Undefined for
94direct adapter usage outside the chat engine.
95
96***
97
98### context?
99
100```ts
101optional context: TContext;
102```
103
104Defined in: [packages/ai/src/types.ts:885](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L885)
105
106Runtime context provided by the caller and passed to middleware and
107server-side tool implementations.
108
109***
110
111### ~~conversationId?~~
112
113```ts
114optional conversationId: string;
115```
116
117Defined in: [packages/ai/src/types.ts:974](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L974)
118
119#### Deprecated
120
121Use `threadId` instead. `conversationId` is the legacy
122pre-AG-UI name for the same concept (a stable per-conversation
123identifier used to correlate client/server devtools events). When
124`conversationId` is omitted, the runtime falls back to `threadId`
125automatically, so most callers can simply pass `threadId` (or rely
126on `chatParamsFromRequest`, which surfaces it on `params`).
127
128Will be removed in a future major release.
129
130***
131
132### lazyToolsConfig?
133
134```ts
135optional lazyToolsConfig: LazyToolsConfig;
136```
137
138Defined in: [packages/ai/src/types.ts:925](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L925)
139
140Optional configuration for lazy-tool discovery (tools marked `lazy: true`).
141Tunes how much of each lazy tool's description appears in the discovery
142catalog. Optional — defaults to `{ includeDescription: 'none' }`.
143
144***
145
146### logger
147
148```ts
149logger: InternalLogger;
150```
151
152Defined in: [packages/ai/src/types.ts:995](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L995)
153
154Internal logger threaded from the chat entry point. Adapter implementations
155must call `logger.request()` before SDK calls, `logger.provider()` for each
156chunk received, and `logger.errors()` in catch blocks.
157
158***
159
160### messages
161
162```ts
163messages: ModelMessage<
164 | string
165 | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
166 | null>[];
167```
168
169Defined in: [packages/ai/src/types.ts:879](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L879)
170
171***
172
173### metadata?
174
175```ts
176optional metadata: Record<string, any>;
177```
178
179Defined in: [packages/ai/src/types.ts:936](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L936)
180
181Observability metadata attached to this call. Surfaced to middleware,
182devtools, and the event client; values may be arbitrarily structured
183(objects, arrays). Adapters never forward this field onto the provider
184wire request.
185
186To send provider-side request metadata, use the provider's
187`modelOptions` field instead, where the provider supports one (e.g.
188OpenAI's and OpenRouter's `metadata` are both Record<string, string>).
189
190***
191
192### model
193
194```ts
195model: string;
196```
197
198Defined in: [packages/ai/src/types.ts:878](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L878)
199
200***
201
202### modelOptions?
203
204```ts
205optional modelOptions: TProviderOptionsForModel;
206```
207
208Defined in: [packages/ai/src/types.ts:937](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L937)
209
210***
211
212### outputSchema?
213
214```ts
215optional outputSchema: SchemaInput;
216```
217
218Defined in: [packages/ai/src/types.ts:963](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L963)
219
220Schema for structured output.
221
222**Two distinct use sites:**
223
2241. **User-facing (activity layer):** accepts any
225 [SchemaInput](../type-aliases/SchemaInput.md) — Zod, ArkType, Valibot, or a raw JSON Schema.
226 The activity layer converts to JSON Schema before handing off.
227
2282. **Adapter-facing (`chatStream` call):** the engine populates this with
229 a pre-converted JSON Schema **only** when the adapter declared
230 `supportsCombinedToolsAndSchema(modelOptions) === true`. The adapter
231 should then wire the schema into the upstream request (e.g.
232 `response_format: { type: 'json_schema', ... }`, `text.format`,
233 `output_format`) alongside any `tools`. The model's natural final
234 turn carries the schema-constrained JSON text and the engine
235 harvests it from the agent loop without a separate finalization
236 round-trip.
237
238 Adapters that did NOT declare the capability never see this field
239 populated — the engine instead invokes `structuredOutput` /
240 `structuredOutputStream` after the agent loop.
241
242***
243
244### parentRunId?
245
246```ts
247optional parentRunId: string;
248```
249
250Defined in: [packages/ai/src/types.ts:1012](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1012)
251
252Parent run ID for AG-UI protocol nested run correlation.
253Surfaced for observability/middleware; not consumed by the LLM call.
254
255***
256
257### request?
258
259```ts
260optional request: Request | RequestInit;
261```
262
263Defined in: [packages/ai/src/types.ts:938](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L938)
264
265***
266
267### runId?
268
269```ts
270optional runId: string;
271```
272
273Defined in: [packages/ai/src/types.ts:1007](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1007)
274
275Run ID for AG-UI protocol run correlation.
276When provided, this will be used in RunStartedEvent and RunFinishedEvent.
277If not provided, a unique ID will be generated.
278
279***
280
281### systemPrompts?
282
283```ts
284optional systemPrompts: SystemPrompt[];
285```
286
287Defined in: [packages/ai/src/types.ts:900](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L900)
288
289System prompts to include with the request.
290
291Accepts plain strings (the common case) or `{ content, metadata }`
292objects that let providers attach typed metadata (e.g. Anthropic
293`cache_control` for prompt caching) per prompt. At the chat call site
294the adapter narrows `metadata`'s type via `~types['systemPromptMetadata']`
295— providers that don't declare one default to `never`, which makes the
296field carry no meaningful value (TypeScript will only accept
297`undefined` there). Provider-foreign metadata that reaches an adapter
298via JS / `as any` is silently dropped, never written to the wire.
299
300#### See
301
302SystemPrompt
303
304***
305
306### threadId?
307
308```ts
309optional threadId: string;
310```
311
312Defined in: [packages/ai/src/types.ts:1001](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L1001)
313
314Thread ID for AG-UI protocol run correlation.
315When provided, this will be used in RunStartedEvent and RunFinishedEvent.
316
317***
318
319### tools?
320
321```ts
322optional tools: AnyTool[];
323```
324
325Defined in: [packages/ai/src/types.ts:880](https://github.com/TanStack/ai/blob/main/packages/ai/src/types.ts#L880)