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

TextAdapter.md

277 lines7.2 KB

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`