Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

TextOptions.md

325 lines8.6 KB

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)