chat 4.30.0 → 4.32.0

package/docs/teams-primitives.mdx

@@ -0,0 +1,255 @@
+---
+title: Teams Low-Level APIs
+description: Use Teams Activity parsing, Bot Connector calls, Graph reads, formatting, Adaptive Cards, and Task Module helpers without the full Chat runtime.
+type: guide
+prerequisites:
+  - /adapters/official/teams
+related:
+  - /docs/handling-events
+  - /docs/cards
+  - /docs/modals
+---
+
+The Teams adapter is the right default for most bots. It validates Bot Framework requests through the Microsoft Teams SDK, parses Activities, stores conversation context, renders Adaptive Cards, reads Graph history, and routes events through `Chat`.
+
+Use the low-level Teams subpaths when your app already owns routing, state, sessions, or workflow execution and only needs Teams-specific primitives.
+
+| Subpath | Use for |
+|---------|---------|
+| `@chat-adapter/teams/webhook` | Parse Bot Framework Activity JSON, classify common payloads, and extract continuation data |
+| `@chat-adapter/teams/api` | Fetch-based Bot Connector calls for messages, updates, deletes, typing, and conversations |
+| `@chat-adapter/teams/graph` | Fetch-based Microsoft Graph reads for chats, channels, channel messages, and replies |
+| `@chat-adapter/teams/format` | Teams HTML, mention, Markdown-ish, and emoji string helpers |
+| `@chat-adapter/teams/cards` | Runtime-free conversion from simple card objects and input requests to Adaptive Cards |
+| `@chat-adapter/teams/modals` | Runtime-free Task Module Adaptive Card helpers and submit parsing |
+
+<Callout type="warning">
+  The webhook subpath parses Activities only. It does not verify Microsoft Bot Framework JWTs. For production request validation, use `createTeamsAdapter` or the Microsoft Teams SDK request pipeline before handing the Activity to these helpers.
+</Callout>
+
+## Webhooks
+
+Teams sends Bot Framework Activity JSON. `readTeamsWebhook` reads the request body and classifies the Activity, but it intentionally does not perform JWT validation.
+
+```typescript title="app/api/teams/route.ts" lineNumbers
+import { postTeamsMessage } from "@chat-adapter/teams/api";
+import { readTeamsWebhook } from "@chat-adapter/teams/webhook";
+
+export async function POST(request: Request) {
+  const payload = await readTeamsWebhook(request, {
+    botAppId: process.env.TEAMS_APP_ID,
+  });
+
+  if (payload.kind === "message") {
+    await postTeamsMessage({
+      conversationId: payload.continuation.conversationId,
+      credentials: {
+        appId: process.env.TEAMS_APP_ID!,
+        appPassword: process.env.TEAMS_APP_PASSWORD!,
+        tenantId: payload.continuation.tenantId,
+      },
+      markdownText: `received: ${payload.text}`,
+      serviceUrl: payload.continuation.serviceUrl,
+    });
+  }
+
+  return new Response(null, { status: 200 });
+}
+```
+
+`parseTeamsWebhookBody` returns typed payloads:
+
+| Kind | Teams surface |
+|------|---------------|
+| `message` | Message activities |
+| `message_reaction` | Reaction activities |
+| `card_action` | Adaptive Card actions and `Action.Submit` message activities |
+| `dialog_open` | Task Module `task/fetch` invokes |
+| `dialog_submit` | Task Module `task/submit` invokes |
+| `conversation_update` | Conversation membership and install context updates |
+| `installation_update` | App installation updates |
+| `unsupported` | Valid Activities not normalized by this helper yet |
+
+Message-like payloads include `continuation`, which contains provider-native reply context:
+
+```typescript
+type TeamsContinuation = {
+  activityId?: string;
+  channelId?: string;
+  conversationId: string;
+  replyToId?: string;
+  serviceUrl: string;
+  teamId?: string;
+  tenantId?: string;
+};
+```
+
+This is not a Chat SDK `Thread`. It is the durable Teams data you need to reply later with `@chat-adapter/teams/api`.
+
+## Bot Connector API
+
+The API subpath calls the Bot Framework Connector REST API with `fetch`. It does not import `@microsoft/teams.apps`.
+
+```typescript title="teams.ts" lineNumbers
+import {
+  deleteTeamsMessage,
+  postTeamsMessage,
+  sendTeamsTyping,
+  updateTeamsMessage,
+} from "@chat-adapter/teams/api";
+
+const credentials = {
+  appId: process.env.TEAMS_APP_ID!,
+  appPassword: process.env.TEAMS_APP_PASSWORD!,
+  tenantId: process.env.TEAMS_APP_TENANT_ID!,
+};
+
+const posted = await postTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  markdownText: "**hello**",
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+
+await updateTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  messageId: posted.id,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+  text: "updated",
+});
+
+await sendTeamsTyping({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+
+await deleteTeamsMessage({
+  conversationId: "19:abc@thread.tacv2",
+  credentials,
+  messageId: posted.id,
+  serviceUrl: "https://smba.trafficmanager.net/teams/",
+});
+```
+
+Use `accessToken` in `credentials` when your runtime already owns Microsoft token acquisition. A direct `accessToken` must be scoped for the API you call it against — the Bot Connector subpath (`/api`) needs a `https://api.botframework.com/.default` token, while the Graph subpath (`/graph`) needs a `https://graph.microsoft.com/.default` token. Passing the same token to both will fail against one of them. When you supply `appId`/`appPassword` instead, each subpath requests the correct scope for you.
+
+## Graph
+
+The Graph subpath reads Teams history with explicit Graph IDs. Unlike `TeamsAdapter`, it does not use the adapter state cache to infer `teamId`, `channelId`, or `chatId`.
+
+```typescript
+import { listTeamsChannelMessages } from "@chat-adapter/teams/graph";
+
+const messages = await listTeamsChannelMessages({
+  channelId: "19:channel@thread.tacv2",
+  credentials: {
+    appId: process.env.TEAMS_APP_ID!,
+    appPassword: process.env.TEAMS_APP_PASSWORD!,
+    tenantId: process.env.TEAMS_APP_TENANT_ID!,
+  },
+  limit: 25,
+  teamId: "19:team@thread.tacv2",
+});
+
+const latestText = messages.items[0]?.text;
+```
+
+Graph reads require the same Microsoft Graph permissions as the full adapter. Channel and group-chat reads can use RSC permissions; DM reads require Azure AD application permissions such as `Chat.Read.All`.
+
+## Formatting
+
+Teams renders message text as HTML. The format subpath provides small helpers for custom runtimes:
+
+```typescript
+import {
+  formatTeamsMention,
+  markdownToTeamsHtml,
+  teamsHtmlToMarkdown,
+} from "@chat-adapter/teams/format";
+
+const html = markdownToTeamsHtml(
+  `${formatTeamsMention("Ada")} approved **deploy v2.4.1**`
+);
+const markdown = teamsHtmlToMarkdown("<p>Hello <strong>world</strong></p>");
+```
+
+Use the full `TeamsFormatConverter` from `@chat-adapter/teams` when you need mdast conversion inside Chat SDK.
+
+## Cards
+
+The cards subpath converts simple card objects into Adaptive Card JSON without importing the full `chat` JSX runtime.
+
+```typescript title="cards.ts" lineNumbers
+import {
+  cardToAdaptiveCard,
+  cardToTeamsFallbackText,
+} from "@chat-adapter/teams/cards";
+import { postTeamsMessage } from "@chat-adapter/teams/api";
+
+const card = {
+  children: [
+    { content: "deploy v2.4.1?", type: "text" },
+    {
+      children: [
+        { id: "approve", label: "Approve", style: "primary", type: "button" },
+        { id: "deny", label: "Deny", style: "danger", type: "button" },
+      ],
+      type: "actions",
+    },
+  ],
+  title: "Deployment",
+  type: "card",
+} as const;
+
+await postTeamsMessage({
+  adaptiveCard: cardToAdaptiveCard(card),
+  conversationId: payload.continuation.conversationId,
+  credentials,
+  serviceUrl: payload.continuation.serviceUrl,
+  text: cardToTeamsFallbackText(card),
+});
+```
+
+Use the full Chat SDK card JSX when you want cross-platform rendering. Use `@chat-adapter/teams/cards` when you are building a Teams-only runtime and want Adaptive Card output directly.
+
+## Modals
+
+Teams Task Modules are invoke-based dialogs backed by Adaptive Cards. The modals subpath builds those cards and parses submit data.
+
+```typescript
+import {
+  modalToAdaptiveCard,
+  parseTeamsDialogSubmitValues,
+  toTeamsTaskModuleResponse,
+} from "@chat-adapter/teams/modals";
+
+const modal = {
+  callbackId: "deploy",
+  children: [
+    { content: "Why deploy now?", type: "text" },
+    { id: "reason", label: "Reason", type: "text_input" },
+  ],
+  title: "Deploy",
+  type: "modal",
+} as const;
+
+const card = modalToAdaptiveCard(modal, { contextId: "deploy-1" });
+const values = parseTeamsDialogSubmitValues(payload.value);
+
+return Response.json(
+  toTeamsTaskModuleResponse({ action: "update", modal }, { contextId: "deploy-1" })
+);
+```
+
+## Import Boundaries
+
+The low-level Teams subpaths are designed to avoid the full runtime import graph:
+
+- no `chat` import
+- no `@chat-adapter/shared` import
+- no `@microsoft/teams.apps` import
+- no full adapter import
+
+The package still installs the full Teams adapter dependencies. The subpaths keep your source and bundle imports clean, but they are not a package-size split.

package/docs/testing.mdx

@@ -5,7 +5,7 @@ type: guide
 prerequisites:
   - /docs/getting-started
 related:
-  - /docs/state
+  - /docs/state-adapters
   - /docs/handling-events
   - /docs/contributing/testing
 ---

package/docs/threads-messages-channels.mdx

@@ -83,7 +83,7 @@ await thread.startTyping();
 ```
 
 <Callout type="info">
-Not all platforms support typing indicators. The call is a no-op on unsupported platforms. See the [adapter feature matrix](/docs/adapters) for details.
+Not all platforms support typing indicators. The call is a no-op on unsupported platforms. See the [adapter feature matrix](/docs/platform-adapters) for details.
 </Callout>
 
 ### Message history
@@ -149,7 +149,7 @@ await scheduled.cancel();
 ```
 
 <Callout type="info">
-Scheduled messages are currently only supported by the Slack adapter. Other adapters throw `NotImplementedError`. See the [feature matrix](/docs/adapters) for details.
+Scheduled messages are currently only supported by the Slack adapter. Other adapters throw `NotImplementedError`. See the [feature matrix](/docs/platform-adapters) for details.
 </Callout>
 
 ## Messages

package/docs/usage.mdx

@@ -7,7 +7,7 @@ prerequisites:
 related:
   - /docs/handling-events
   - /docs/adapters
-  - /docs/state
+  - /docs/state-adapters
 ---
 
 The `Chat` class is the main entry point for your bot. It coordinates adapters, routes events to your handlers, and manages thread state.
@@ -34,10 +34,10 @@ bot.onNewMention(async (thread) => {
 ```
 
 <Callout type="info">
-  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/official/postgres) and [ioredis](/adapters/official/ioredis) as production state adapters. See [State Adapters](/docs/state) for all options.
+  This example uses Redis. Chat SDK also supports [PostgreSQL](/adapters/official/postgres) and [ioredis](/adapters/official/ioredis) as production state adapters. See [State Adapters](/docs/state-adapters) for all options.
 </Callout>
 
-Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override.
+Each adapter factory auto-detects credentials from environment variables (`SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `REDIS_URL`, etc.), so you can get started with zero config. Pass explicit values to override. For setup UIs and build scripts, the [`chat/adapters` catalog](/docs/adapters#adapter-catalog-chatadapters) lists official and vendor-official adapter env specs without importing adapter packages.
 
 ## Multiple adapters
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "chat",
-  "version": "4.30.0",
-  "description": "Unified chat abstraction for Slack, Teams, Google Chat, and Discord",
+  "version": "4.32.0",
+  "description": "Chat SDK — universal TypeScript toolkit for building multi-platform chat bots and AI agents on Slack, Teams, Google Chat, Discord, WhatsApp, and more",
   "type": "module",
   "engines": {
     "node": ">=20"
@@ -18,6 +18,10 @@
       "types": "./dist/ai/index.d.ts",
       "import": "./dist/ai/index.js"
     },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js"
+    },
     "./jsx-runtime": {
       "types": "./dist/jsx-runtime.d.ts",
       "import": "./dist/jsx-runtime.js"
@@ -65,9 +69,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vercel/chat.git",
-    "directory": "packages/chat-sdk"
+    "directory": "packages/chat"
   },
-  "homepage": "https://github.com/vercel/chat#readme",
+  "homepage": "https://chat-sdk.dev/docs",
   "bugs": {
     "url": "https://github.com/vercel/chat/issues"
   },
@@ -76,11 +80,26 @@
   },
   "keywords": [
     "chat",
+    "chat-sdk",
+    "chatbot",
+    "chat-bot",
+    "bot",
+    "bot-framework",
+    "messaging",
+    "multi-platform",
     "slack",
     "teams",
+    "microsoft-teams",
     "discord",
     "google-chat",
-    "bot"
+    "telegram",
+    "whatsapp",
+    "github",
+    "webhook",
+    "ai-agent",
+    "ai-sdk",
+    "typescript",
+    "vercel"
   ],
   "license": "MIT",
   "scripts": {

package/resources/guides/ai-gateway-and-ai-sdk.md

@@ -0,0 +1,224 @@
+# Build AI agents with AI Gateway and AI SDK
+
+**Author:** Ben Sabic
+
+---
+
+An AI agent is a model that runs in a loop, using tools to gather information or take action until it completes a task. The AI SDK gives you the TypeScript primitives to build that loop, and AI Gateway gives it one endpoint and one set of credentials for hundreds of models, so you can switch providers by changing a single string instead of managing separate accounts, keys, and rate limits.
+
+This guide takes you from your first model request to a working agent, then makes that agent reliable with model fallbacks, reachable in chat platforms with Chat SDK, and durable with the Workflow SDK.
+
+## Overview
+
+In this guide, you'll learn how to:
+
+*   Set up a [Next.js](https://nextjs.org/) project and authenticate to AI Gateway with OIDC tokens
+    
+*   Generate text, stream responses, and produce structured outputs
+    
+*   Give your agent tools so they can act, not just respond
+    
+*   Keep your agent available with model fallbacks
+    
+*   Run AI-generated code safely in isolated [Vercel Sandbox](https://vercel.com/sandbox) microVMs
+    
+*   Bring your agent to Slack, Teams, and other chat platforms with [Chat SDK](https://chat-sdk.dev/)
+    
+*   Give your agent secure, short-lived access to third-party APIs with [Vercel Connect](https://vercel.com/connect)
+    
+*   Make your agent durable and resumable with the [Workflow SDK](https://workflow-sdk.dev)
+    
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+*   A [Vercel account](https://vercel.com/signup)
+    
+*   Node.js 20 or later
+    
+*   [Vercel CLI](https://vercel.com/docs/cli) installed (`npm i -g vercel`)
+    
+
+## How it works
+
+AI Gateway is a single endpoint that sits in front of every supported provider. You send it a model string in the form `creator/model-name`, and the Gateway resolves the provider, authenticates, routes the request, and tracks usage. Because the AI SDK communicates with this endpoint natively, your application code remains the same whether you call Claude Opus 4.8, GPT-5.5, or Gemini 3.1 Pro. Tokens cost the same as they would from the provider directly, with no markup.
+
+The AI SDK provides the function-level API you'll build the agent from (`generateText`, `streamText`, `generateObject`, and the tool loop), and AI Gateway provides the infrastructure underneath: authentication, usage tracking, failover, and billing. The two are built with high cohesion but loose coupling, so you can adopt the SDK on its own and add Gateway features via provider options when needed.
+
+## Steps
+
+### 1\. Create a Next.js app
+
+Use `create-next-app` to bootstrap a new project:
+
+`pnpm create next-app@latest ai-gateway-demo --yes cd ai-gateway-demo`
+
+The `--yes` flag uses the recommended defaults: TypeScript, Tailwind CSS, ESLint, App Router, and Turbopack, with the `@/*` import alias. Omit the flag if you want to customize these options interactively.
+
+### 2\. Install the AI SDK
+
+Add the `ai` package to your project:
+
+`pnpm add ai`
+
+AI Gateway works with both AI SDK v5 and v6. Check your installed version with `pnpm list ai`.
+
+### 3\. Authenticate with OIDC
+
+AI Gateway authenticates requests using [Vercel OIDC tokens](https://vercel.com/docs/oidc), which Vercel generates and links to your project automatically. You don't need to create or store an API key.
+
+First, link your local project to a Vercel project:
+
+`vercel link`
+
+Then pull the environment variables, which include the OIDC token:
+
+`vercel env pull`
+
+This writes the token to your local environment file. OIDC tokens are valid for 12 hours, so during local development, you'll need to run `vercel env pull` again to refresh the token when it expires.
+
+When you deploy to Vercel, OIDC tokens are provisioned automatically, so no further setup is required in production.
+
+### 4\. Generate text
+
+Start with the simplest request: generate a single block of text. Create an API route at `app/api/chat/route.ts`. Pass a plain string model ID to `generateText` and the AI Gateway resolves the provider and routes the request. With OIDC authentication, you don't reference a key anywhere in your code:
+
+`import { generateText } from 'ai'; export async function GET() { const { text } = await generateText({ model: 'anthropic/claude-opus-4.8', prompt: 'Explain quantum computing in one paragraph.', }); return Response.json({ text }); }`
+
+Start the dev server and visit the route to see the response:
+
+`pnpm dev`
+
+### 5\. Stream responses
+
+For real-time output, use `streamText` and return a streamed response. This is the pattern you'll use for chat interfaces and any response long enough that waiting for the full result would hurt the experience:
+
+`import { streamText } from 'ai'; export async function POST(request: Request) { const { prompt } = await request.json(); const result = streamText({ model: 'openai/gpt-5.5', prompt, }); return result.toUIMessageStreamResponse(); }`
+
+To switch models, change the model string. No other code changes are required.
+
+### 6\. Generate structured outputs
+
+Use `generateObject` with a [Zod](https://zod.dev/) schema to get type-safe structured data instead of free text:
+
+`import { generateObject } from 'ai'; import { z } from 'zod'; export async function GET() { const { object } = await generateObject({ model: 'anthropic/claude-opus-4.8', schema: z.object({ name: z.string(), age: z.number(), city: z.string(), }), prompt: 'Extract: John is 30 years old and lives in NYC.', }); return Response.json(object); // { name: 'John', age: 30, city: 'NYC' } }`
+
+### 7\. Give your agent tools
+
+So far, the model has produced text and data, but it hasn't done anything. Tools change that: you define functions the model can invoke to fetch data, call an API, or act on the outside world, and the AI SDK runs the model in a loop, calling tools and feeding results back until the task is done. A model plus tools in a loop is an agent, and the AI SDK handles that loop for you.
+
+Define a tool with a description, an input schema, and an `execute` function:
+
+`import { generateText, tool } from 'ai'; import { z } from 'zod'; export async function GET() { const { text } = await generateText({ model: 'anthropic/claude-opus-4.8', tools: { getWeather: tool({ description: 'Get the current weather for a location', parameters: z.object({ location: z.string().describe('City name, e.g. San Francisco'), }), execute: async ({ location }) => ({ location, temperature: 72, condition: 'sunny', }), }), }, prompt: "What's the weather in Tokyo?", }); return Response.json({ text }); }`
+
+You now have a working agent. Everything that follows makes it more capable and more reliable: fallbacks keep it available, Sandbox lets it run code safely, Chat SDK puts it in front of users, and the Workflow SDK makes it durable.
+
+### 8\. Keep your agent available with fallbacks
+
+An agent makes many model calls over the course of a task, so it has many chances to hit a provider outage or error. That makes failover matter more for agents, not less. Pass a `models` array in `providerOptions.gateway` to list backup models, which the Gateway tries in order when the primary model fails:
+
+`import { streamText } from 'ai'; export async function POST(request: Request) { const { prompt } = await request.json(); const result = streamText({ model: 'openai/gpt-5.5', // Primary model prompt, providerOptions: { gateway: { models: ['anthropic/claude-opus-4.8', 'google/gemini-3.1-pro-preview'], // Fallbacks }, }, }); return result.toUIMessageStreamResponse(); }`
+
+In this example, the Gateway first attempts the primary model. If that fails, it tries `anthropic/claude-opus-4.7`, then `google/gemini-3.1-pro-preview`. The response comes from the first model that succeeds, and failover happens automatically without changes to your application logic.
+
+## Let your agent run code safely
+
+A capable agent often needs to do more than call predefined tools: it may generate code and run it, whether to compute a result, transform data, or test its own output. Executing model-generated code on your own infrastructure is risky because the code might consume excessive resources, read sensitive files, make unwanted network requests, or run destructive commands.
+
+[Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) provides the agent with an isolated environment to run the code. Each sandbox is an ephemeral Linux microVM with resource limits and automatic timeouts, so untrusted code runs without touching your production systems. It's a standalone SDK you can call from any environment, and the same OIDC token you pulled earlier authenticates both Sandbox and AI Gateway.
+
+Add the Sandbox SDK to your project:
+
+`pnpm add @vercel/sandbox ms`
+
+The pattern has two parts: generate code with the model via the AI Gateway, then write it to a fresh sandbox and run it. The sandbox is created, used, and stopped within a single request:
+
+``import ms from 'ms'; import { generateText } from 'ai'; import { Sandbox } from '@vercel/sandbox'; const SYSTEM_PROMPT = `You are a code generator. Write JavaScript that runs in Node.js. Output only the code, with no explanations or markdown.`; async function generateCode(task: string): Promise<string> { const { text } = await generateText({ model: 'anthropic/claude-sonnet-4.6', system: SYSTEM_PROMPT, prompt: `Write JavaScript code to: ${task}`, }); return text .replace(/^\s*```(?:javascript|js)?\s*/i, '') .replace(/\s*```\s*$/i, '') .trim(); } async function executeCode(code: string) { const sandbox = await Sandbox.create({ resources: { vcpus: 2 }, timeout: ms('2m'), runtime: 'node22', }); try { await sandbox.writeFiles([ { path: '/vercel/sandbox/code.mjs', content: Buffer.from(code) }, ]); const result = await sandbox.runCommand({ cmd: 'node', args: ['code.mjs'] }); const stdout = await result.stdout(); const stderr = await result.stderr(); return { output: stdout || stderr || '(no output)', exitCode: result.exitCode }; } finally { await sandbox.stop(); } }``
+
+This gives the agent two layers of safety: the system prompt steers the model away from dangerous operations, and the sandbox enforces isolation regardless of what the model produces. The sandbox captures both `stdout` and `stderr`, so the agent can read failures and retry without those failures affecting your host. For a complete walkthrough, see [How to execute AI-generated code safely with Vercel Sandbox](https://vercel.com/kb/guide/how-to-execute-ai-generated-code-safely).
+
+## Bring your agent to your users
+
+The agent you've built runs over an HTTP route, but your users may already be in Slack, Microsoft Teams, Discord, or Google Chat. [Chat SDK](https://chat-sdk.dev/) is a TypeScript library for building chatbots that work across these platforms from a single codebase, and it integrates directly with AI SDK. That means the same agent you call through AI Gateway can answer inside a thread without rebuilding it for each platform.
+
+Two helpers from the `chat/ai` subpath connect the two SDKs. Importing from `chat/ai` rather than the main `chat` entrypoint keeps the optional `ai` and `zod` peer dependencies out of bundles that don't use them.
+
+### Feed thread history to your agent
+
+`toAiMessages` converts an array of Chat SDK `Message` objects into the `{ role, content }[]` format the AI SDK expects. The output is structurally compatible with the AI SDK's `ModelMessage[]`, so you can pass it straight into a model call. Fetch recent messages from the thread, convert them, and use them as the agent's prompt:
+
+`import { toAiMessages } from 'chat/ai'; bot.onSubscribedMessage(async (thread, message) => { const result = await thread.adapter.fetchMessages(thread.id, { limit: 20 }); const history = await toAiMessages(result.messages); const response = await agent.stream({ prompt: history }); await thread.post(response.fullStream); });`
+
+`toAiMessages` maps messages authored by the bot to the `assistant` role and all others to `user`, sorts them chronologically, and includes image and text attachments as multipart content. For multi-user threads, pass `includeNames: true` so the model can tell speakers apart.
+
+### Let your agent act on the platform
+
+`createChatTools` provides the agent with a set of AI SDK tools for posting messages, adding reactions, and performing other platform actions. Pass it to your Chat instance alongside an AI SDK call:
+
+`import { Chat } from 'chat'; import { createChatTools } from 'chat/ai'; import { createSlackAdapter } from '@chat-adapter/slack'; import { createMemoryState } from '@chat-adapter/state-memory'; import { generateText } from 'ai'; const chat = new Chat({ userName: 'mybot', adapters: { slack: createSlackAdapter() }, state: createMemoryState(), }); const result = await generateText({ model: 'anthropic/claude-opus-4.8', tools: createChatTools({ chat, preset: 'messenger' }), prompt: 'Post a friendly hello in slack:C0123ABC and react to it with a thumbs up.', });`
+
+Each tool resolves the right adapter from the id prefix you give it (`slack:`, `discord:`, `gchat:`), so one agent can drive any platform your Chat instance is wired up to. Because the model string still routes through AI Gateway, you keep the provider failover and unified billing from the earlier steps while reaching users wherever they already work.
+
+## Give your agent secure access to third-party APIs
+
+Once your agent acts on outside services, such as posting to Slack, opening GitHub pull requests, or querying a data warehouse, it needs credentials for those providers. Bundling long-lived API keys into your deployment is risky: the secret sits in your environment indefinitely, applies to every request, and is hard to scope or revoke.
+
+[Vercel Connect](https://vercel.com/docs/connect) solves this by issuing short-lived provider tokens at runtime instead. You register a connector for a provider once, link it to your projects and environments, and your code requests a scoped token only when it needs one. The same OIDC token you've used throughout authenticates the request, so no provider secret lives in your deployment.
+
+Add the Connect SDK to your project:
+
+`pnpm add @vercel/connect`
+
+Request a token with `getToken`, passing the connector, the subject the token acts as, and the scopes you need:
+
+`import { getToken } from '@vercel/connect'; const token = await getToken('slack/acme-slack', { subject: { type: 'app' }, installationId: 'inst_workspace_xyz', scopes: ['chat:write'], });`
+
+The subject controls whose identity the token represents: `{ type: 'app' }` acts as your service, while `{ type: 'user', id: '...' }` acts on behalf of a specific user who authorized access once. The SDK caches tokens in-process and refreshes them automatically, so an agent that makes many provider calls in a single run requests a single token rather than one per call. Connect currently supports Slack, GitHub, and OAuth connectors in Beta. To set up your first connector, see [Access external APIs from your agents with Vercel Connect](https://vercel.com/kb/guide/vercel-connect).
+
+## Build durable agents with the Workflow SDK
+
+The agents you've built so far run in memory. If the process crashes, the function times out, or the user refreshes the page, the agent's progress is lost. That's fine for short, single-tool interactions, but it's costly for production agents that chain several tool calls, such as booking a flight or running a research task across multiple APIs.
+
+`WorkflowAgent` from `@ai-sdk/workflow` runs the same agent loop as the standard in-memory agent, but inside a [Vercel Workflow](https://vercel.com/docs/workflows). Each tool call becomes a durable step, so progress persists across process boundaries, and failed steps are retried from the last checkpoint instead of restarting the whole loop. Tools marked `needsApproval` can suspend the agent for hours or days until a user responds, which makes human-in-the-loop flows possible without a custom state store or polling.
+
+To get durability, the agent runs inside a function marked `'use workflow'`, and each tool's `execute` function is marked `'use step'`:
+
+``import { WorkflowAgent, type ModelCallStreamPart } from '@ai-sdk/workflow'; import { convertToModelMessages, tool, type UIMessage } from 'ai'; import { getWritable } from 'workflow'; import { z } from 'zod'; async function searchFlightsStep(input: { origin: string; destination: string; date: string; }) { 'use step'; const response = await fetch(`https://api.flights.example/search?...`); return response.json(); } export async function chat(messages: UIMessage[]) { 'use workflow'; const modelMessages = await convertToModelMessages(messages); const agent = new WorkflowAgent({ model: 'anthropic/claude-sonnet-4-6', instructions: 'You are a flight booking assistant.', tools: { searchFlights: tool({ description: 'Search for available flights', inputSchema: z.object({ origin: z.string(), destination: z.string(), date: z.string(), }), execute: searchFlightsStep, }), }, }); const result = await agent.stream({ messages: modelMessages, writable: getWritable<ModelCallStreamPart>(), }); return { messages: result.messages }; }``
+
+The model string is the same `creator/model-name` form you've used throughout, so the request still routes through AI Gateway with its failover and unified billing. What changes is the runtime: tool calls now persist, retry, and appear as discrete steps in the workflow dashboard. To add human approval, set `needsApproval: true` on a tool definition, which suspends the durable workflow until the user responds.
+
+Start with the standard in-memory agent, and reach for `WorkflowAgent` when tool calls outlive their request, approvals exceed function timeouts, or each call should be independently retryable and traced. For a full breakdown of what `WorkflowAgent` adds, how `needsApproval` works, and how to keep chat streams resumable across timeouts, see the [What is WorkflowAgent?](https://vercel.com/kb/guide/what-is-workflowagent) guide.
+
+## Best practices
+
+*   **Refresh your OIDC token during local development**: Tokens are valid for 12 hours. If requests start failing locally with an authentication error, run `vercel env pull` to get a fresh token.
+    
+*   **Set fallbacks for production traffic**: A single model and provider is a single point of failure. Listing two or three fallback models in `providerOptions.gateway` keeps requests available when one provider has an outage.
+    
+*   **Keep model IDs in configuration**: Because switching models is a single string change, storing model IDs in environment variables or a config file lets you switch providers without editing application code.
+    
+*   **Confirm your AI SDK version**: All core features are available in both v5 and v6, but v6 adds capabilities such as video generation. Run `pnpm list ai` to check, and see the [AI SDK v6 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-6-0) before upgrading.
+    
+
+## Resources and next steps
+
+*   Learn about [model routing and fallbacks](https://vercel.com/docs/ai-gateway/models-and-providers/provider-options) for finer control over provider preference
+    
+*   Read more about [OIDC authentication](https://vercel.com/docs/ai-gateway/authentication-and-byok/authentication) and how tokens work on Vercel
+    
+*   Explore the [AI SDK documentation](https://ai-sdk.dev/getting-started) for advanced patterns
+    
+*   Run AI-generated code safely with [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) and the [code execution guide](https://vercel.com/kb/guide/how-to-execute-ai-generated-code-safely)
+    
+*   Build a cross-platform chatbot with [Chat SDK](https://chat-sdk.dev/docs) and its [AI SDK integration](https://chat-sdk.dev/docs/ai/ai-sdk-tools)
+    
+*   Request short-lived provider tokens at runtime with [Vercel Connect](https://vercel.com/docs/connect)
+    
+*   Make your agents durable with [WorkflowAgent](https://vercel.com/kb/guide/what-is-workflowagent) and [Workflow SDK](https://workflow-sdk.dev/)
+    
+*   Browse the [model library](https://vercel.com/ai-gateway/models) to see every supported provider and model
+
+---
+
+[View full KB sitemap](/kb/sitemap.md)