Open History to see the last commit
1---
2id: TextAdapter
3title: TextAdapter
4---
5
6# Interface: TextAdapter\<TModel, TProviderOptions, TInputModalities, TMessageMetadataByModality, TToolCapabilities, TToolCallMetadata, TSystemPromptMetadata\>
7
8Defined in: [packages/ai/src/activities/chat/adapter.ts:67](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L67)
9
10Text adapter interface with pre-resolved generics.
11
12An adapter is created by a provider function: `provider('model')` → `adapter`
13All type resolution happens at the provider call site, not in this interface.
14
15Generic parameters:
16- TModel: The specific model name (e.g., 'gpt-4o')
17- TProviderOptions: Provider-specific options for this model (already resolved)
18- TInputModalities: Supported input modalities for this model (already resolved)
19- TMessageMetadata: Metadata types for content parts (already resolved)
20- TToolCapabilities: Tuple of tool-kind strings supported by this model, resolved from `supports.tools`
21- TToolCallMetadata: Metadata type that round-trips with tool calls (e.g. Gemini's `thoughtSignature`)
22- TSystemPromptMetadata: Provider-typed metadata accepted on each
23 `systemPrompts[i]` entry (e.g. Anthropic `cache_control`). Defaults to
24 `never` — adapters without per-prompt metadata reject the `metadata`
25 field at the call site.
26
27## Type Parameters
28
29### TModel
30
31`TModel` *extends* `string`
32
33### TProviderOptions
34
35`TProviderOptions` *extends* `Record`\<`string`, `any`\>
36
37### TInputModalities
38
39`TInputModalities` *extends* `ReadonlyArray`\<[`Modality`](../type-aliases/Modality.md)\>
40
41### TMessageMetadataByModality
42
43`TMessageMetadataByModality` *extends* [`DefaultMessageMetadataByModality`](DefaultMessageMetadataByModality.md)
44
45### TToolCapabilities
46
47`TToolCapabilities` *extends* `ReadonlyArray`\<`string`\> = `ReadonlyArray`\<`string`\>
48
49### TToolCallMetadata
50
51`TToolCallMetadata` = `unknown`
52
53### TSystemPromptMetadata
54
55`TSystemPromptMetadata` = `never`
56
57## Properties
58
59### ~types
60
61```ts
62~types: object;
63```
64
65Defined in: [packages/ai/src/activities/chat/adapter.ts:95](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L95)
66
67**`Internal`**
68
69Type-only properties for inference. Not assigned at runtime.
70
71#### inputModalities
72
73```ts
74inputModalities: TInputModalities;
75```
76
77#### messageMetadataByModality
78
79```ts
80messageMetadataByModality: TMessageMetadataByModality;
81```
82
83#### providerOptions
84
85```ts
86providerOptions: TProviderOptions;
87```
88
89#### systemPromptMetadata
90
91```ts
92systemPromptMetadata: TSystemPromptMetadata;
93```
94
95#### toolCallMetadata
96
97```ts
98toolCallMetadata: TToolCallMetadata;
99```
100
101#### toolCapabilities
102
103```ts
104toolCapabilities: TToolCapabilities;
105```
106
107***
108
109### chatStream()
110
111```ts
112chatStream: (options) => AsyncIterable<AGUIEvent>;
113```
114
115Defined in: [packages/ai/src/activities/chat/adapter.ts:107](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L107)
116
117Stream text completions from the model
118
119#### Parameters
120
121##### options
122
123[`TextOptions`](TextOptions.md)\<`TProviderOptions`\>
124
125#### Returns
126
127`AsyncIterable`\<[`AGUIEvent`](../type-aliases/AGUIEvent.md)\>
128
129***
130
131### kind
132
133```ts
134readonly kind: "text";
135```
136
137Defined in: [packages/ai/src/activities/chat/adapter.ts:77](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L77)
138
139Discriminator for adapter kind
140
141***
142
143### model
144
145```ts
146readonly model: TModel;
147```
148
149Defined in: [packages/ai/src/activities/chat/adapter.ts:81](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L81)
150
151The model this adapter is configured for
152
153***
154
155### name
156
157```ts
158readonly name: string;
159```
160
161Defined in: [packages/ai/src/activities/chat/adapter.ts:79](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L79)
162
163Provider name identifier (e.g., 'openai', 'anthropic')
164
165***
166
167### requires?
168
169```ts
170readonly optional requires: readonly CapabilityHandle[];
171```
172
173Defined in: [packages/ai/src/activities/chat/adapter.ts:90](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L90)
174
175Capabilities this adapter requires at runtime. `chat()` validates that the
176configured middleware provides each one. Model adapters omit this; harness
177adapters (e.g. a future `claudeCode()`) declare e.g. `[sandboxCapability]`.
178Runtime access to capabilities from inside the adapter is not yet wired —
179this is the declaration/validation surface only.
180
181***
182
183### structuredOutput()
184
185```ts
186structuredOutput: (options) => Promise<StructuredOutputResult<unknown>>;
187```
188
189Defined in: [packages/ai/src/activities/chat/adapter.ts:119](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L119)
190
191Generate structured output using the provider's native structured output API.
192This method uses stream: false and sends the JSON schema to the provider
193to ensure the response conforms to the expected structure.
194
195#### Parameters
196
197##### options
198
199`StructuredOutputOptions`\<`TProviderOptions`\>
200
201Structured output options containing chat options and JSON schema
202
203#### Returns
204
205`Promise`\<`StructuredOutputResult`\<`unknown`\>\>
206
207Promise with the raw data (validation is done in the chat function)
208
209***
210
211### structuredOutputStream()?
212
213```ts
214optional structuredOutputStream: (options) => AsyncIterable<AGUIEvent>;
215```
216
217Defined in: [packages/ai/src/activities/chat/adapter.ts:136](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L136)
218
219Stream structured output using the provider's native streaming structured
220output API (stream + response_format json_schema in a single request).
221
222Optional — adapters without native streaming JSON omit this method and the
223activity layer synthesizes a stream around the non-streaming
224`structuredOutput` call.
225
226Implementations must emit standard AG-UI lifecycle events (RUN_STARTED,
227TEXT_MESSAGE_*, RUN_FINISHED) carrying raw JSON text deltas, plus a final
228`CUSTOM` event named `structured-output.complete` whose `value` is
229`{ object, raw, reasoning? }`.
230
231#### Parameters
232
233##### options
234
235`StructuredOutputOptions`\<`TProviderOptions`\>
236
237#### Returns
238
239`AsyncIterable`\<[`AGUIEvent`](../type-aliases/AGUIEvent.md)\>
240
241***
242
243### supportsCombinedToolsAndSchema()?
244
245```ts
246optional supportsCombinedToolsAndSchema: (modelOptions?) => boolean;
247```
248
249Defined in: [packages/ai/src/activities/chat/adapter.ts:159](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/chat/adapter.ts#L159)
250
251Declares whether the adapter supports combining `tools` and a
252schema-constrained final answer in a single streaming request.
253
254When `true`, the engine wires `outputSchema` into the regular
255`chatStream()` call and skips the separate `runStructuredFinalization`
256round-trip. The model's natural final turn carries the
257schema-constrained JSON text and the engine harvests it from the agent
258loop's accumulated content.
259
260When `false`, `undefined`, or the method is omitted, the engine runs
261the agent loop without `outputSchema` and then issues a separate
262`structuredOutput` / `structuredOutputStream` call against the JSON
263schema for finalization (the legacy path).
264
265The method receives the per-call `modelOptions` so providers whose
266support depends on the resolved upstream model (e.g. OpenRouter) can
267answer per-request. Most adapters can return a constant.
268
269#### Parameters
270
271##### modelOptions?
272
273`TProviderOptions`
274
275#### Returns
276
277`boolean`