TanStack
diff --git a/‎.changeset/gemini-text-interactions.md‎
Lines changed: 19 additions & 0 deletions b/‎.changeset/gemini-text-interactions.md‎
Lines changed: 19 additions & 0 deletions
diff --git a/‎docs/adapters/gemini.md‎
Lines changed: 217 additions & 16 deletions b/‎docs/adapters/gemini.md‎
Lines changed: 217 additions & 16 deletions
@@ -0,0 +1,19 @@
+---
+'@tanstack/ai-gemini': minor
+---
+
+feat(ai-gemini): add experimental `geminiTextInteractions()` adapter for Gemini's stateful Interactions API (Beta)
+
+Routes through `client.interactions.create` instead of `client.models.generateContent`, so callers can pass `previous_interaction_id` via `modelOptions` and let the server retain conversation history. On each run, the returned interaction id is surfaced via an AG-UI `CUSTOM` event (`name: 'gemini.interactionId'`) emitted just before `RUN_FINISHED` — feed it back on the next turn via `modelOptions.previous_interaction_id`.
+
+Exported from a dedicated `@tanstack/ai-gemini/experimental` subpath so the experimental status is load-bearing in your editor and bundle:
+
+```ts
+import { geminiTextInteractions } from '@tanstack/ai-gemini/experimental'
+```
+
+Scope: text/chat output with function tools, plus the built-in tools `google_search`, `code_execution`, `url_context`, `file_search`, and `computer_use`. Built-in tool activity is surfaced as AG-UI `CUSTOM` events named `gemini.googleSearchCall` / `gemini.googleSearchResult` (and the matching `codeExecutionCall`/`Result`, `urlContextCall`/`Result`, `fileSearchCall`/`Result` variants), carrying the raw Interactions delta payload. Function-tool `TOOL_CALL_*` events are unchanged, and `finishReason` stays `stop` when only built-in tools ran — the core chat loop has nothing to execute.
+
+`google_search_retrieval`, `google_maps`, and `mcp_server` are not supported on this adapter and throw a targeted error explaining the alternative. Image/audio output via Interactions is also not routed through this adapter — use `geminiText()`, `geminiImage`, or `geminiSpeech` for those.
+
+Marked `@experimental` — the underlying Interactions API is Beta and Google explicitly flags possible breaking changes.
@@ -31,7 +31,7 @@ import { chat } from "@tanstack/ai";
 import { geminiText } from "@tanstack/ai-gemini";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Hello!" }],
 });
 ```
@@ -42,7 +42,7 @@ const stream = chat({
 import { chat } from "@tanstack/ai";
 import { createGeminiChat } from "@tanstack/ai-gemini";
 
-const adapter = createGeminiChat("gemini-2.5-pro", process.env.GEMINI_API_KEY!, {
+const adapter = createGeminiChat("gemini-3.1-pro-preview", process.env.GEMINI_API_KEY!, {
   // ... your config options
 });
 
@@ -61,7 +61,7 @@ const config: Omit<GeminiTextConfig, "apiKey"> = {
   baseURL: "https://generativelanguage.googleapis.com/v1beta", // Optional
 };
 
-const adapter = createGeminiChat("gemini-2.5-pro", process.env.GEMINI_API_KEY!, config);
+const adapter = createGeminiChat("gemini-3.1-pro-preview", process.env.GEMINI_API_KEY!, config);
 ```
 
 
@@ -75,7 +75,7 @@ export async function POST(request: Request) {
   const { messages } = await request.json();
 
   const stream = chat({
-    adapter: geminiText("gemini-2.5-pro"),
+    adapter: geminiText("gemini-3.1-pro-preview"),
     messages,
   });
 
@@ -104,19 +104,211 @@ const getCalendarEvents = getCalendarEventsDef.server(async ({ date }) => {
 });
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages,
   tools: [getCalendarEvents],
 });
 ```
 
+## Stateful Conversations — Interactions API (Experimental)
+
+Gemini's [Interactions API](https://ai.google.dev/gemini-api/docs/interactions) (currently in Beta) offers server-side conversation state — the Gemini equivalent of OpenAI's Responses API. Instead of replaying the full message history on every turn, you pass a `previous_interaction_id` and the server retains the transcript. This also improves cache hit rates for repeated prefixes.
+
+The `geminiTextInteractions` adapter routes through `client.interactions.create` and surfaces the server-assigned interaction id via an AG-UI `CUSTOM` event (`name: 'gemini.interactionId'`) emitted just before `RUN_FINISHED`, so you can chain turns.
+
+> **⚠️ Experimental.** Google marks the Interactions API as Beta and explicitly flags possible breaking changes until it reaches general availability. The adapter is exported from the `@tanstack/ai-gemini/experimental` subpath so the experimental status is load-bearing in your editor and bundle. Text output, function tools, and the built-in tools `google_search`, `code_execution`, `url_context`, `file_search`, and `computer_use` are supported. `google_search_retrieval`, `google_maps`, and `mcp_server` still throw on this adapter — use `geminiText()` for those or wait for follow-up work.
+
+### Basic Usage
+
+```typescript
+import { chat } from "@tanstack/ai";
+import {
+  geminiTextInteractions,
+  type GeminiInteractionsCustomEventValue,
+} from "@tanstack/ai-gemini/experimental";
+
+// Turn 1: introduce yourself, capture the interaction id.
+let interactionId: string | undefined;
+
+for await (const chunk of chat({
+  adapter: geminiTextInteractions("gemini-3.5-flash"),
+  messages: [{ role: "user", content: "Hi, my name is Amir." }],
+})) {
+  if (chunk.type === "CUSTOM" && chunk.name === "gemini.interactionId") {
+    const value = chunk.value as GeminiInteractionsCustomEventValue<
+      "gemini.interactionId"
+    >;
+    interactionId = value.interactionId;
+  }
+}
+
+// Turn 2: only send the new turn's content — the server has the history.
+for await (const chunk of chat({
+  adapter: geminiTextInteractions("gemini-3.5-flash"),
+  messages: [{ role: "user", content: "What is my name?" }],
+  modelOptions: {
+    previous_interaction_id: interactionId,
+  },
+})) {
+  // ...stream "Your name is Amir." back to the client.
+}
+```
+
+### Wiring with `useChat` (React)
+
+The Interactions API is stateful and **does not accept multi-turn history without a `previous_interaction_id`** — if a chat client sends `[user, assistant, user]` to a fresh interaction the adapter throws `cannot send prior conversation history on a fresh interaction`. To make `useChat` work, persist the server-assigned id and send it back on the next turn:
+
+**Server route** (e.g. TanStack Start handler):
+
+```typescript
+import {
+  chat,
+  chatParamsFromRequestBody,
+  toServerSentEventsResponse,
+} from "@tanstack/ai";
+import { geminiTextInteractions } from "@tanstack/ai-gemini/experimental";
+
+export async function POST({ request }: { request: Request }) {
+  const params = await chatParamsFromRequestBody(await request.json());
+
+  // The client sends body.previousInteractionId; AG-UI maps `body` into
+  // `forwardedProps` on the wire.
+  const previousInteractionId =
+    typeof params.forwardedProps.previousInteractionId === "string"
+      ? params.forwardedProps.previousInteractionId
+      : undefined;
+
+  const stream = chat({
+    adapter: geminiTextInteractions("gemini-3.5-flash"),
+    messages: params.messages,
+    modelOptions: {
+      previous_interaction_id: previousInteractionId,
+      store: true, // required for chaining on the next turn
+    },
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+**React client**:
+
+```tsx
+import { useEffect, useMemo, useState } from "react";
+import { fetchServerSentEvents, useChat } from "@tanstack/ai-react";
+import type { GeminiInteractionsCustomEventValue } from "@tanstack/ai-gemini/experimental";
+
+function GeminiChat() {
+  const [interactionId, setInteractionId] = useState<string | undefined>();
+
+  const body = useMemo(
+    () => (interactionId ? { previousInteractionId: interactionId } : {}),
+    [interactionId],
+  );
+
+  const { messages, setMessages, sendMessage } = useChat({
+    connection: fetchServerSentEvents("/api/chat"),
+    body,
+    onCustomEvent: (eventType, data) => {
+      if (eventType === "gemini.interactionId") {
+        const value = data as
+          | GeminiInteractionsCustomEventValue<"gemini.interactionId">
+          | undefined;
+        if (value?.interactionId) setInteractionId(value.interactionId);
+      }
+    },
+  });
+
+  // Switching provider/model resets the server-side chain — drop the id
+  // AND the local message history together, otherwise the next turn
+  // ships multi-turn messages with no previous_interaction_id and the
+  // adapter errors out.
+  const [provider, setProvider] = useState("gemini-interactions");
+  useEffect(() => {
+    setInteractionId(undefined);
+    setMessages([]);
+  }, [provider]);
+
+  // ...render messages, call sendMessage(input)
+}
+```
+
+The full working example is in [`examples/ts-react-chat`](https://github.com/TanStack/ai/tree/main/examples/ts-react-chat) — see `src/routes/index.tsx` for the client and `src/routes/api.tanchat.ts` for the route.
+
+### How it differs from `geminiText`
+
+| Concern | `geminiText` | `geminiTextInteractions` |
+| --- | --- | --- |
+| Underlying endpoint | `models:generateContent` | `interactions:create` |
+| Conversation state | Stateless — send full history each turn | Stateful — server retains transcript via `previous_interaction_id` |
+| Provider options shape | camelCase (`stopSequences`, `responseModalities`, `safetySettings`) | snake_case (`generation_config`, `response_modalities`, `previous_interaction_id`) |
+| Built-in tools | `google_search`, `code_execution`, `url_context`, `file_search`, `google_maps`, `google_search_retrieval`, `computer_use` | `google_search`, `code_execution`, `url_context`, `file_search`, `computer_use` (only the first four stream `CUSTOM` event activity; `computer_use` is accepted in the request but does not currently emit per-delta events) |
+| Stability | GA | Experimental (Google Beta) |
+
+### Provider Options
+
+The adapter exposes Interactions-specific options on `modelOptions`:
+
+```typescript
+import { geminiTextInteractions } from "@tanstack/ai-gemini/experimental";
+
+const stream = chat({
+  adapter: geminiTextInteractions("gemini-3.5-flash"),
+  messages,
+  modelOptions: {
+    // Stateful chaining — passed only on turn 2+.
+    previous_interaction_id: "int_abc123",
+
+    // Persist the interaction server-side (default true). Must be true for
+    // previous_interaction_id to work on the *next* turn.
+    store: true,
+
+    // Per-request system instruction (interaction-scoped — re-specify each turn).
+    system_instruction: "You are a helpful assistant.",
+
+    // snake_case generation config distinct from geminiText's camelCase one.
+    generation_config: {
+      thinking_level: "LOW",
+      thinking_summaries: "auto",
+      stop_sequences: ["<done>"],
+    },
+
+    response_modalities: ["text"],
+  },
+});
+```
+
+### Reading the interaction id
+
+The server's interaction id arrives as an AG-UI `CUSTOM` event emitted just before `RUN_FINISHED`:
+
+```typescript
+for await (const chunk of stream) {
+  if (chunk.type === "CUSTOM" && chunk.name === "gemini.interactionId") {
+    const id = (chunk.value as { interactionId: string }).interactionId;
+    // Persist `id` wherever you store per-user conversation pointers —
+    // pass it back on the next turn as `previous_interaction_id`.
+  }
+}
+```
+
+### Caveats
+
+- **Multi-turn history requires `previous_interaction_id`.** The Interactions API has no stateless replay path — sending more than one message in `messages` without a `previous_interaction_id` throws. Chat UIs that maintain local history must capture the server-assigned id and chain (see [Wiring with `useChat`](#wiring-with-usechat-react)). On provider/model switch, also clear the local message buffer.
+- **Tools, `system_instruction`, and `generation_config` are interaction-scoped.** Per Google's docs these are NOT inherited from a prior interaction via `previous_interaction_id` — pass them again on every turn you need them.
+- `store: false` is incompatible with `previous_interaction_id` (no state to recall) and with `background: true`.
+- Retention (as of the time of writing): **55 days on the Paid Tier, 1 day on the Free Tier.** See [Google's Interactions API docs](https://ai.google.dev/gemini-api/docs/interactions) for current retention policy.
+- Built-in tools in scope (`google_search`, `code_execution`, `url_context`, `file_search`, `computer_use`) are wired through as request tools. Per-delta activity for the four search/exec tools streams back as AG-UI `CUSTOM` events — `gemini.googleSearchCall` / `gemini.googleSearchResult` (and the matching `codeExecutionCall`/`Result`, `urlContextCall`/`Result`, `fileSearchCall`/`Result`) — carrying the raw Interactions delta. `computer_use` is accepted in the request but the Interactions API does not currently emit per-delta `CUSTOM` events for it. Function-tool `TOOL_CALL_*` events are unchanged, and `finishReason` stays `stop` when only built-in tools ran.
+- `google_search_retrieval`, `google_maps`, and `mcp_server` still throw a targeted error on this adapter. Use `geminiText()` for the first two, or wait for a dedicated follow-up for `mcp_server`.
+- Image and audio output via Interactions aren't routed through this adapter yet — it's text-only. Use `geminiImage` / `geminiSpeech` for non-text generation for now.
+
 ## Model Options
 
 Gemini supports various model-specific options:
 
 ```typescript
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages,
   modelOptions: {
     maxOutputTokens: 2048,
@@ -159,7 +351,7 @@ import { summarize } from "@tanstack/ai";
 import { geminiSummarize } from "@tanstack/ai-gemini";
 
 const result = await summarize({
-  adapter: geminiSummarize("gemini-2.5-pro"),
+  adapter: geminiSummarize("gemini-3.1-pro-preview"),
   text: "Your long text to summarize...",
   maxLength: 100,
   style: "concise", // "concise" | "bullet-points" | "paragraph"
@@ -275,7 +467,7 @@ import { generateSpeech } from "@tanstack/ai";
 import { geminiSpeech } from "@tanstack/ai-gemini";
 
 const result = await generateSpeech({
-  adapter: geminiSpeech("gemini-2.5-flash-preview-tts"),
+  adapter: geminiSpeech("gemini-3.1-flash-tts-preview"),
   text: "Hello from Gemini TTS!",
 });
 
@@ -332,7 +524,16 @@ Creates a Gemini text/chat adapter.
 
 **Parameters:**
 
-- `model` - Gemini chat model id (e.g. `"gemini-2.5-pro"`)
+- `model` - Gemini chat model id (e.g. `"gemini-3.1-pro-preview"`)
+- `config?.baseURL` - Custom base URL (optional)
+
+### `geminiTextInteractions(model, config?)` / `createGeminiTextInteractions(model, apiKey, config?)` (experimental)
+
+Creates a Gemini Interactions API text adapter. Backs the stateful conversation pattern via `previous_interaction_id`. Exported from `@tanstack/ai-gemini/experimental`.
+
+**Parameters:**
+
+- `model` - Gemini chat model id (e.g. `"gemini-3.5-flash"`)
 - `config?.baseURL` - Custom base URL (optional)
 
 ### `geminiSummarize(model, config?)` / `createGeminiSummarize(model, apiKey, config?)`
@@ -380,7 +581,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { codeExecutionTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Calculate the first 10 Fibonacci numbers" }],
   tools: [codeExecutionTool()],
 });
@@ -399,7 +600,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { fileSearchTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Find the quarterly revenue figures" }],
   tools: [
     fileSearchTool({
@@ -423,7 +624,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { googleSearchTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "What's the weather in Tokyo right now?" }],
   tools: [googleSearchTool()],
 });
@@ -443,7 +644,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { googleSearchRetrievalTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Explain the latest JavaScript proposals" }],
   tools: [
     googleSearchRetrievalTool({
@@ -467,7 +668,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { googleMapsTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Find coffee shops near Union Square, SF" }],
   tools: [googleMapsTool()],
 });
@@ -486,7 +687,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { urlContextTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Summarise https://example.com/article" }],
   tools: [urlContextTool()],
 });
@@ -506,7 +707,7 @@ import { geminiText } from "@tanstack/ai-gemini";
 import { computerUseTool } from "@tanstack/ai-gemini/tools";
 
 const stream = chat({
-  adapter: geminiText("gemini-2.5-pro"),
+  adapter: geminiText("gemini-3.1-pro-preview"),
   messages: [{ role: "user", content: "Navigate to example.com in the browser" }],
   tools: [
     computerUseTool({