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

TextOptions.md

304 lines8.2 KB

1---
2id: TextOptions
3title: TextOptions
4---
5​
6# Interface: TextOptions\<TProviderOptionsSuperset, TProviderOptionsForModel\>
7​
8Defined in: [packages/typescript/ai/src/types.ts:728](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L728)
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## Properties
23​
24### abortController?
25​
26```ts
27optional abortController: AbortController;
28```
29​
30Defined in: [packages/typescript/ai/src/types.ts:832](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L832)
31​
32AbortController for request cancellation.
33​
34Allows you to cancel an in-progress request using an AbortController.
35Useful for implementing timeouts or user-initiated cancellations.
36​
37#### Example
38​
39```ts
40const abortController = new AbortController();
41setTimeout(() => abortController.abort(), 5000); // Cancel after 5 seconds
42await chat({ ..., abortController });
43```
44​
45#### See
46​
47https://developer.mozilla.org/en-US/docs/Web/API/AbortController
48​
49***
50​
51### agentLoopStrategy?
52​
53```ts
54optional agentLoopStrategy: AgentLoopStrategy;
55```
56​
57Defined in: [packages/typescript/ai/src/types.ts:750](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L750)
58​
59***
60​
61### ~~conversationId?~~
62​
63```ts
64optional conversationId: string;
65```
66​
67Defined in: [packages/typescript/ai/src/types.ts:818](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L818)
68​
69#### Deprecated
70​
71Use `threadId` instead. `conversationId` is the legacy
72pre-AG-UI name for the same concept (a stable per-conversation
73identifier used to correlate client/server devtools events). When
74`conversationId` is omitted, the runtime falls back to `threadId`
75automatically, so most callers can simply pass `threadId` (or rely
76on `chatParamsFromRequest`, which surfaces it on `params`).
77​
78Will be removed in a future major release.
79​
80***
81​
82### logger
83​
84```ts
85logger: InternalLogger;
86```
87​
88Defined in: [packages/typescript/ai/src/types.ts:839](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L839)
89​
90Internal logger threaded from the chat entry point. Adapter implementations
91must call `logger.request()` before SDK calls, `logger.provider()` for each
92chunk received, and `logger.errors()` in catch blocks.
93​
94***
95​
96### maxTokens?
97​
98```ts
99optional maxTokens: number;
100```
101​
102Defined in: [packages/typescript/ai/src/types.ts:785](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L785)
103​
104The maximum number of tokens to generate in the response.
105​
106Provider usage:
107- OpenAI: `max_output_tokens` (number) - includes visible output and reasoning tokens
108- Anthropic: `max_tokens` (number, required) - range x >= 1
109- Gemini: `generationConfig.maxOutputTokens` (number)
110​
111***
112​
113### messages
114​
115```ts
116messages: ModelMessage<
117 | string
118 | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
119 | null>[];
120```
121​
122Defined in: [packages/typescript/ai/src/types.ts:733](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L733)
123​
124***
125​
126### metadata?
127​
128```ts
129optional metadata: Record<string, any>;
130```
131​
132Defined in: [packages/typescript/ai/src/types.ts:796](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L796)
133​
134Additional metadata to attach to the request.
135Can be used for tracking, debugging, or passing custom information.
136Structure and constraints vary by provider.
137​
138Provider usage:
139- OpenAI: `metadata` (Record<string, string>) - max 16 key-value pairs, keys max 64 chars, values max 512 chars
140- Anthropic: `metadata` (Record<string, any>) - includes optional user_id (max 256 chars)
141- Gemini: Not directly available in TextProviderOptions
142​
143***
144​
145### model
146​
147```ts
148model: string;
149```
150​
151Defined in: [packages/typescript/ai/src/types.ts:732](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L732)
152​
153***
154​
155### modelOptions?
156​
157```ts
158optional modelOptions: TProviderOptionsForModel;
159```
160​
161Defined in: [packages/typescript/ai/src/types.ts:797](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L797)
162​
163***
164​
165### outputSchema?
166​
167```ts
168optional outputSchema: SchemaInput;
169```
170​
171Defined in: [packages/typescript/ai/src/types.ts:807](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L807)
172​
173Schema for structured output.
174When provided, the adapter should use the provider's native structured output API
175to ensure the response conforms to this schema.
176The schema will be converted to JSON Schema format before being sent to the provider.
177Supports any Standard JSON Schema compliant library (Zod, ArkType, Valibot, etc.).
178​
179***
180​
181### parentRunId?
182​
183```ts
184optional parentRunId: string;
185```
186​
187Defined in: [packages/typescript/ai/src/types.ts:856](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L856)
188​
189Parent run ID for AG-UI protocol nested run correlation.
190Surfaced for observability/middleware; not consumed by the LLM call.
191​
192***
193​
194### request?
195​
196```ts
197optional request: Request | RequestInit;
198```
199​
200Defined in: [packages/typescript/ai/src/types.ts:798](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L798)
201​
202***
203​
204### runId?
205​
206```ts
207optional runId: string;
208```
209​
210Defined in: [packages/typescript/ai/src/types.ts:851](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L851)
211​
212Run ID for AG-UI protocol run correlation.
213When provided, this will be used in RunStartedEvent and RunFinishedEvent.
214If not provided, a unique ID will be generated.
215​
216***
217​
218### systemPrompts?
219​
220```ts
221optional systemPrompts: SystemPrompt[];
222```
223​
224Defined in: [packages/typescript/ai/src/types.ts:749](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L749)
225​
226System prompts to include with the request.
227​
228Accepts plain strings (the common case) or `{ content, metadata }`
229objects that let providers attach typed metadata (e.g. Anthropic
230`cache_control` for prompt caching) per prompt. At the chat call site
231the adapter narrows `metadata`'s type via `~types['systemPromptMetadata']`
232— providers that don't declare one default to `never`, which makes the
233field carry no meaningful value (TypeScript will only accept
234`undefined` there). Provider-foreign metadata that reaches an adapter
235via JS / `as any` is silently dropped, never written to the wire.
236​
237#### See
238​
239SystemPrompt
240​
241***
242​
243### temperature?
244​
245```ts
246optional temperature: number;
247```
248​
249Defined in: [packages/typescript/ai/src/types.ts:763](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L763)
250​
251Controls the randomness of the output.
252Higher values (e.g., 0.8) make output more random, lower values (e.g., 0.2) make it more focused and deterministic.
253Range: [0.0, 2.0]
254​
255Note: Generally recommended to use either temperature or topP, but not both.
256​
257Provider usage:
258- OpenAI: `temperature` (number) - in text.top_p field
259- Anthropic: `temperature` (number) - ranges from 0.0 to 1.0, default 1.0
260- Gemini: `generationConfig.temperature` (number) - ranges from 0.0 to 2.0
261​
262***
263​
264### threadId?
265​
266```ts
267optional threadId: string;
268```
269​
270Defined in: [packages/typescript/ai/src/types.ts:845](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L845)
271​
272Thread ID for AG-UI protocol run correlation.
273When provided, this will be used in RunStartedEvent and RunFinishedEvent.
274​
275***
276​
277### tools?
278​
279```ts
280optional tools: Tool<any, any, any>[];
281```
282​
283Defined in: [packages/typescript/ai/src/types.ts:734](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L734)
284​
285***
286​
287### topP?
288​
289```ts
290optional topP: number;
291```
292​
293Defined in: [packages/typescript/ai/src/types.ts:776](https://github.com/TanStack/ai/blob/main/packages/typescript/ai/src/types.ts#L776)
294​
295Nucleus sampling parameter. An alternative to temperature sampling.
296The model considers the results of tokens with topP probability mass.
297For example, 0.1 means only tokens comprising the top 10% probability mass are considered.
298​
299Note: Generally recommended to use either temperature or topP, but not both.
300​
301Provider usage:
302- OpenAI: `text.top_p` (number)
303- Anthropic: `top_p` (number | null)
304- Gemini: `generationConfig.topP` (number)