chat 4.29.0 → 4.30.0

package/resources/guides/how-to-build-a-slack-bot-with-next-js-and-redis.md

@@ -35,7 +35,7 @@ Create a new Next.js app and add the Chat SDK and adapter packages:
 
 `npx create-next-app@latest my-slack-bot --typescript --app cd my-slack-bot pnpm add chat @chat-adapter/slack @chat-adapter/state-redis`
 
-The `chat` package is the Chat SDK core. The `@chat-adapter/slack` and `@chat-adapter/state-redis` packages are the [Slack platform adapter](https://chat-sdk.dev/adapters/slack) and [Redis state adapter](https://chat-sdk.dev/adapters/redis).
+The `chat` package is the Chat SDK core. The `@chat-adapter/slack` and `@chat-adapter/state-redis` packages are the [Slack platform adapter](https://chat-sdk.dev/adapters/official/slack) and [Redis state adapter](https://chat-sdk.dev/adapters/official/redis).
 
 ### 2\. Create a Slack app
 
@@ -129,6 +129,10 @@ Verify that `REDIS_URL` is reachable from your deployment environment. If runnin
 
 Make sure your webhook route passes `waitUntil` to the handler, as shown in step 5. Without it, serverless functions can terminate before your event handlers finish.
 
+* * *
+
+## Build with a template or read more.
+
 ---
 
 [View full KB sitemap](/kb/sitemap.md)

package/resources/guides/human-in-the-loop-with-chat-sdk-and-workflow-sdk.md

@@ -0,0 +1,176 @@
+# Human-in-the-Loop with Chat SDK and Workflow SDK
+
+**Author:** Ben Sabic
+
+---
+
+You can pause a durable workflow until a human approves it in Slack by combining Chat SDK and Workflow SDK. Chat SDK posts an interactive card with Approve and Deny buttons; Workflow SDK's `createWebhook` generates a URL that those buttons POST to when clicked, suspending the workflow until the click arrives. The workflow resumes with the click payload, decides what to do, and continues, with no `onAction` handler, no custom approval database, and no polling.
+
+This guide walks you through suspending a workflow with `createWebhook`, posting a Chat SDK approval card with `callbackUrl` buttons, and resuming the workflow based on the user's choice. You'll add a timeout so abandoned approvals can't suspend forever, and see how to extend the pattern to multiple decision points within a single workflow.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+*   Node.js 18 or later
+    
+*   An existing [Chat SDK](https://chat-sdk.dev) bot (see the [Slack agent guide](https://vercel.com/kb/guide/how-to-build-an-ai-agent-for-slack-with-chat-sdk-and-ai-sdk) or [Slack file bot guide](https://vercel.com/kb/guide/slack-bot-vercel-blob))
+    
+*   A project configured for [Workflow SDK](https://workflow-sdk.dev/docs/getting-started)
+    
+*   A [Vercel account](https://vercel.com/signup) if you're deploying to Vercel
+    
+
+> Workflow SDK runs against any [world](https://workflow-sdk.dev/worlds); a pluggable backend for storage, queuing, and authentication. When you deploy to Vercel, [Vercel Workflows](https://vercel.com/workflows) is selected automatically with zero configuration. For self-hosted setups, see [Postgres World](https://workflow-sdk.dev/worlds/postgres) and the other providers.
+
+## How it works
+
+Three pieces fit together:
+
+*   **Workflow SDK** runs the long-lived process. A function becomes durable when you mark it with `"use workflow"`: it can suspend, resume, and survive crashes without losing state. `createWebhook()` returns an object with a `url` that's a public endpoint. When you `await` it, the workflow is suspended until that endpoint receives an HTTP request.
+    
+*   **Chat SDK** presents the decision to a human. A `<Button callbackUrl="...">` posts the click's action data to the URL you supply, in addition to firing any `onAction` handler. When the URL is the workflow's `webhook.url`, the click resumes the workflow directly.
+    
+*   **The pairing** removes the usual glue. There's no separate approvals table, no `onAction` callback that has to look up which workflow is waiting, and no polling. The workflow suspends, the user clicks, and the same workflow function picks up where it left off with the click payload in hand.
+    
+
+`createWebhook()` is the right primitive when the workflow itself owns the resume URL. For cases where you'd rather keep the URL private and resume from your own server code, use `createHook()` with a deterministic business token instead.
+
+## Steps
+
+### 1\. Install dependencies
+
+Add Workflow SDK to a project that already has a Chat SDK bot set up:
+
+`pnpm add workflow`
+
+If you're starting from scratch, also install a few Chat SDK packages:
+
+`pnpm add chat @chat-adapter/slack @chat-adapter/state-redis`
+
+The `workflow` package is Workflow SDK's core. The `chat` package is the Chat SDK core, and `@chat-adapter/slack` and `@chat-adapter/state-redis` are the [Slack platform adapter](https://chat-sdk.dev/adapters/official/slack) and [Redis state adapter](https://chat-sdk.dev/adapters/official/redis). See the [Chat SDK getting started guide](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk) and [Slack agent guide](https://vercel.com/kb/guide/how-to-build-an-ai-agent-for-slack-with-chat-sdk-and-ai-sdk) if you don't have a bot yet.
+
+### 2\. Define the approval workflow
+
+Create `workflows/approval.ts`:
+
+``import { createWebhook } from "workflow"; import { finalizeApprovalCard, postApprovalCard, postReply, } from "@/lib/slack"; export async function requestDeployApproval(opts: { threadId: string; version: string; requestedBy: string; }) { "use workflow"; using webhook = createWebhook(); const messageId = await postApprovalCard({ threadId: opts.threadId, version: opts.version, requestedBy: opts.requestedBy, webhookUrl: webhook.url, }); const request = await webhook; const payload = await request.json(); if (payload.actionId === "approve") { await deploy(opts.version); await finalizeApprovalCard({ threadId: opts.threadId, messageId, version: opts.version, requestedBy: opts.requestedBy, outcome: `Approved by <@${payload.user.id}> — ${opts.version} deployed.`, }); await postReply( opts.threadId, `Deployed **${opts.version}** by <@${payload.user.id}>.`, ); } else { await finalizeApprovalCard({ threadId: opts.threadId, messageId, version: opts.version, requestedBy: opts.requestedBy, outcome: `Denied by <@${payload.user.id}>.`, }); await postReply( opts.threadId, `Deploy of **${opts.version}** denied by <@${payload.user.id}>.`, ); } } async function deploy(version: string) { "use step"; // Trigger your deploy here. This runs as a durable step, // so retries and observability come for free. }``
+
+The workflow is intentionally thin. It owns the webhook and the resume logic; everything else (posting the card, sending follow-up messages, triggering the deploy) is a step. That separation keeps the workflow body deterministic and pushes side effects into retryable units.
+
+Next, define the helper steps in `lib/slack.ts`:
+
+``import { Card, CardText, Actions, Button } from "chat"; import { bot } from "@/lib/bot"; export async function postApprovalCard(opts: { threadId: string; version: string; requestedBy: string; webhookUrl: string; }): Promise<string> { "use step"; const thread = bot.thread(opts.threadId); const sent = await thread.post( <Card title={`Deploy ${opts.version}?`} subtitle={`Requested by ${opts.requestedBy}`}> <CardText>Approve to roll out **{opts.version}**, or deny to abort.</CardText> <Actions> <Button id="approve" style="primary" callbackUrl={opts.webhookUrl}> Approve </Button> <Button id="deny" style="danger" callbackUrl={opts.webhookUrl}> Deny </Button> </Actions> </Card>, ); return sent.id; } // Re-render the approval card without the Actions block, swapping the // buttons for a static outcome line. The title, subtitle, and body text // stay the same so the thread keeps its context. export async function finalizeApprovalCard(opts: { threadId: string; messageId: string; version: string; requestedBy: string; outcome: string; }) { "use step"; const thread = bot.thread(opts.threadId); await thread.adapter.editMessage( thread.id, opts.messageId, <Card title={`Deploy ${opts.version}?`} subtitle={`Requested by ${opts.requestedBy}`}> <CardText>Approve to roll out **{opts.version}**, or deny to abort.</CardText> <CardText>{opts.outcome}</CardText> </Card>, ); } // Post a follow-up message as markdown so platforms with native markdown // support render bold/italic/links instead of literal asterisks. Plain // strings are passed through as-is — `{ markdown }` is the explicit form. export async function postReply(threadId: string, markdown: string) { "use step"; await bot.thread(threadId).post({ markdown }); }``
+
+`bot.thread(threadId)` constructs a `Thread` reference from a serialized ID, which is exactly the entry point Chat SDK provides for posting outside an event handler. Thread IDs follow the format `adapter:channel:thread` (for example, `slack:C123ABC:1234567890.123456`) and round-trip cleanly through JSON, so they're safe to pass as workflow inputs.
+
+**Key details in this workflow**
+
+*   The `using` declaration ensures the webhook is cleaned up automatically when the workflow exits, even if it throws.
+    
+*   Both buttons point at the same `webhook.url`. The `actionId` travels in the callback payload, so a single webhook handles all the buttons on the card.
+    
+*   `await webhook` suspends the workflow. The function pauses here until the user clicks, which could take seconds, hours, or days. Workflow SDK persists the state and resumes on the click.
+    
+*   The `deploy` function is marked `"use step"`, which makes it a durable step with automatic retries and observability. Workflow SDK only re-runs steps when they fail, not on resumption.
+    
+*   `postApprovalCard` returns the posted message's `id`, and `finalizeApprovalCard` calls `thread.adapter.editMessage` to re-render the card without buttons once the decision is in. That prevents a stale click on the original card from hitting the consumed webhook, and it leaves a clear audit trail in the thread.
+    
+*   `postReply` posts with `{ markdown }` rather than a bare string. The bare-string form is passed through as-is, so `**bold**` would render as literal asterisks on Slack and Teams; the `{ markdown }` form is converted to the platform's native markup.
+    
+
+If you need to preserve more of the original thread context across the workflow boundary (for example, the triggering message or thread metadata), use `thread.toJSON()` on the way in and [`bot.reviver()`](https://chat-sdk.dev/docs/api/thread) when restoring on the other side. For the approval flow above, the thread ID is enough.
+
+### 3\. Start the workflow
+
+Trigger the workflow from wherever the approval request originates.
+
+From a Chat SDK handler:
+
+`import { start } from "workflow/api"; import { requestDeployApproval } from "@/workflows/approval"; bot.onNewMention(async (thread, message) => { const version = parseVersion(message.text); if (!version) { await thread.post("Usage: @bot deploy v1.2.3"); return; } await start(requestDeployApproval, [ { threadId: thread.id, version, requestedBy: message.author.fullName, }, ]); });`
+
+`start` queues the workflow run and returns immediately with a run handle, allowing the mention handler to respond without blocking. The workflow takes over from there, posting the card, suspending on the webhook, and resuming when the user clicks.
+
+### 4\. Read the callback payload
+
+Chat SDK POSTs a JSON body to the callback URL with this shape:
+
+`{ "type": "action", "actionId": "approve", "value": "approve", "user": { "id": "U123", "name": "alice" }, "threadId": "slack:C123:1234567890.123", "messageId": "1234567890.456" }`
+
+\- `actionId` is the button's `id` prop: `"approve"` or `"deny"` in this workflow.
+
+\- `value` is the optional `value` prop you set on the button, a string for passing extra context to the handler. It's most useful when multiple buttons share an `id` (so `actionId` alone can't distinguish them) or when the button needs to carry a record identifier like `"item-123"`. In the approval workflow above, the buttons have distinct `id`s, so `value` isn't set and arrives as `undefined`.
+
+\- `user` is the user who clicked, regardless of who triggered the workflow.
+
+Use `actionId` to branch on which button was pressed, and [`user.id`](http://user.id) to record or validate who approved.
+
+## Handling multiple decision points
+
+For workflows that need more than one approval, call `createWebhook()` multiple times. Each call generates a fresh URL, so suspensions are independent:
+
+``export async function multiStageApproval(opts: { threadId: string }) { "use workflow"; using draftReview = createWebhook(); const draftTitle = "Approve draft?"; const draftMessageId = await postPrompt(opts.threadId, draftTitle, draftReview.url); const draftPayload = await (await draftReview).json(); if (draftPayload.actionId !== "approve") { await finalizePromptCard(opts.threadId, draftMessageId, draftTitle, `Rejected by <@${draftPayload.user.id}>.`); return; } await finalizePromptCard(opts.threadId, draftMessageId, draftTitle, `Approved by <@${draftPayload.user.id}>.`); using finalReview = createWebhook(); const finalTitle = "Approve final?"; const finalMessageId = await postPrompt(opts.threadId, finalTitle, finalReview.url); const finalPayload = await (await finalReview).json(); if (finalPayload.actionId !== "approve") { await finalizePromptCard(opts.threadId, finalMessageId, finalTitle, `Rejected by <@${finalPayload.user.id}>.`); return; } await finalizePromptCard(opts.threadId, finalMessageId, finalTitle, `Approved by <@${finalPayload.user.id}>.`); await publish(); }``
+
+This workflow relies on two helpers used at each stage. Add `postPrompt` and `finalizePromptCard` to `lib/slack.ts`:
+
+`export async function postPrompt( threadId: string, title: string, webhookUrl: string, ): Promise<string> { "use step"; const thread = bot.thread(threadId); const sent = await thread.post( <Card title={title}> <Actions> <Button id="approve" style="primary" callbackUrl={webhookUrl}> Approve </Button> <Button id="deny" style="danger" callbackUrl={webhookUrl}> Deny </Button> </Actions> </Card>, ); return sent.id; } export async function finalizePromptCard( threadId: string, messageId: string, title: string, outcome: string, ) { "use step"; const thread = bot.thread(threadId); await thread.adapter.editMessage( thread.id, messageId, <Card title={title}> <CardText>{outcome}</CardText> </Card>, ); }`
+
+Each `using` declaration scopes the webhook to its block, so cleanup happens as soon as the workflow moves past that approval. `finalizePromptCard` strips the buttons once a decision lands, so every stage shows its final state without leaving stale buttons in the thread. The workflow itself can suspend at any point, without you tracking which webhook is which, since the runtime handles that.
+
+## Adding a timeout
+
+A workflow that suspends on a webhook indefinitely is fine until someone forgets to click. Race the webhook against a durable `sleep` to bound the wait:
+
+``import { createWebhook, sleep } from "workflow"; export async function approvalWithTimeout(opts: { threadId: string }) { "use workflow"; using webhook = createWebhook(); const title = "Proceed with the change?"; const messageId = await postPrompt(opts.threadId, title, webhook.url); const result = await Promise.race([ webhook.then(async (req) => ({ kind: "clicked" as const, body: await req.json() })), sleep("24h").then(() => ({ kind: "timeout" as const })), ]); if (result.kind === "timeout") { await finalizePromptCard(opts.threadId, messageId, title, "Timed out after 24h — no decision recorded."); return; } await finalizePromptCard( opts.threadId, messageId, title, `${result.body.actionId === "approve" ? "Approved" : "Denied"} by <@${result.body.user.id}>.`, ); if (result.body.actionId === "approve") { await proceed(); } }``
+
+`sleep` is itself a durable suspension, so the 24-hour wait costs nothing while it's pending and survives deploys. When the timeout wins the race, the workflow continues without resuming the webhook, and the `using` cleanup releases the URL. The card is finalized in both branches, so the timeout is visible in the thread rather than silently leaving a stale set of buttons.
+
+## Validating the approver
+
+The callback URL is authenticated only by its token, which means anyone who can intercept the URL can resume the workflow. For sensitive operations, validate the user in the payload before continuing:
+
+``const APPROVERS = new Set(["U_ALICE", "U_BOB"]); const request = await webhook; const payload = await request.json(); if (!APPROVERS.has(payload.user.id)) { await thread.post( `<@${payload.user.id}> isn't authorized to approve this deploy.`, ); return; }``
+
+For stronger guarantees, switch to [`createHook()`](https://workflow-sdk.dev/docs/api-reference/workflow/create-hook) and resume the workflow from your own authenticated route with `resumeHook()`. That pattern keeps the resume URL private and gives you full control over the authorization check, at the cost of writing a route handler.
+
+## Troubleshooting
+
+### The workflow never resumes after a click
+
+Confirm the button's `callbackUrl` matches `webhook.url` exactly. The URL contains a token that's bound to the suspension, so a stale or hand-edited URL won't resolve. Check the Workflow SDK CLI to see whether the workflow is still suspended on the webhook:
+
+`npx workflow inspect runs --web`
+
+If the click reached the URL but the workflow didn't move, look for an error in the workflow logs. The `using` declaration disposes the webhook on the next throw, so an uncaught error in the workflow body can release the URL before the click arrives.
+
+### `ValidationError` when posting the card on Discord or Telegram
+
+Discord's `custom_id` has a 100-character limit; Telegram's `callback_data` has a 64-byte limit. The encoded button data is the action ID plus the callback token, which can exceed those caps. Shorten the action ID (`"a"` instead of `"approve-deploy-v1-2-3"`) and move long context into `value` or out of the card entirely. Slack and Teams don't have this limit.
+
+### The same approval card gets clicked twice
+
+The main flow above guards against this by calling `finalizeApprovalCard` immediately after the decision lands. The card is re-rendered without its `Actions` block, so there's nothing left to click. If you skip that step, Chat SDK won't dedupe clicks for you: once `await webhook` has resolved, a second click hits a webhook that no longer exists, and the user sees the platform's default error. Either edit the card to remove the buttons (the pattern shown above, via `thread.adapter.editMessage`), or accept that only the first click matters and ignore the rest.
+
+### A workflow run shows as suspended forever
+
+Workflows suspend until something resumes them. If your callback URL was lost (for example, a card was deleted before anyone could click), the run will stay suspended until its associated webhook is cleaned up. Use a timeout (see above) to bound every suspension, and use the Workflow SDK CLI to cancel runs that should no longer wait:
+
+`npx workflow inspect runs # find the run ID, then: npx workflow runs cancel <run-id>`
+
+## Related resources
+
+*   [Chat SDK Threads, Messages, and Channels](https://chat-sdk.dev/docs/threads-messages-channels)
+    
+*   [Chat SDK Actions](https://chat-sdk.dev/docs/actions)
+    
+*   [Workflow SDK](https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook) [`createWebhook`](https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook)
+    
+*   [Workflow SDK](https://workflow-sdk.dev/docs/api-reference/workflow/create-hook) [`createHook`](https://workflow-sdk.dev/docs/api-reference/workflow/create-hook)
+    
+*   [Workflow SDK Human-in-the-Loop example](https://workflow-sdk.dev/cookbook/agent-patterns/human-in-the-loop)
+    
+*   [How to build an AI agent for Slack with Chat SDK and AI SDK](https://vercel.com/kb/guide/how-to-build-an-ai-agent-for-slack-with-chat-sdk-and-ai-sdk)
+
+---
+
+[View full KB sitemap](/kb/sitemap.md)

package/resources/guides/liveblocks-chat-sdk-ai-sdk.md

@@ -0,0 +1,165 @@
+# How to build an agent for Liveblocks with Chat SDK and AI SDK
+
+**Author:** Chris Nicholas, Ben Sabic
+
+---
+
+You can build an AI-powered bot that reads and responds to Liveblocks comment threads using [Chat SDK](https://chat-sdk.dev), [AI SDK](https://ai-sdk.dev/docs/reference/ai-sdk-core/tool-loop-agent)'s `ToolLoopAgent`, and the [Liveblocks Chat SDK adapter](https://chat-sdk.dev/adapters/vendor-official/liveblocks). Chat SDK handles webhook verification, message routing, and the Liveblocks API. `ToolLoopAgent` wraps your language model with tools and runs an autonomous reasoning loop, calling tools and feeding results back until it has a complete answer. Redis tracks thread subscriptions and manages distributed locking for concurrent message handling, giving you a production-ready AI bot without managing infrastructure.
+
+This guide walks you through wiring up a Next.js app directory project that responds to @-mentions in Liveblocks threads with streamed AI replies and tool calling.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+*   Node.js 18+
+    
+*   A Next.js app that uses [Liveblocks Comments](https://liveblocks.io/docs/get-started/comments)
+    
+*   A Liveblocks account and the [dashboard](https://liveblocks.io/dashboard) open
+    
+*   A Redis instance (local or hosted, such as [Upstash](https://vercel.com/marketplace/upstash))
+    
+*   A [Vercel account](https://vercel.com/signup) with AI Gateway access
+    
+
+## How it works
+
+[Liveblocks Comments](https://liveblocks.io/comments) is a fully featured React commenting system you can embed in any application, giving users threaded discussions, @-mentions, emoji reactions, and notifications out of the box. Threads are attached to specific rooms in your app, making them ideal for contextual conversations around documents, designs, or any shared content.
+
+The `@liveblocks/chat-sdk-adapter` connects Chat SDK to Liveblocks' webhook system. You register event handlers (like `onNewMention` and `onReaction`) and the adapter routes incoming webhook payloads to them. It handles signature verification, parses comment and reaction events, and exposes a consistent thread API for posting replies or adding emoji reactions.
+
+AI SDK's `ToolLoopAgent` wraps a language model with tools and runs an autonomous loop: the model generates text or calls a tool, the SDK executes the tool, feeds the result back, and repeats until the model finishes. When you pass a model string like `"anthropic/claude-sonnet-4-6"` and host your application on Vercel, the AI SDK routes the request through the [Vercel AI Gateway](https://vercel.com/ai-gateway) automatically. Chat SDK accepts any `AsyncIterable<string>` as a message, so you can pass the agent's `fullStream` directly to `thread.post()` for real-time streaming in Liveblocks threads.
+
+The [Redis state adapter](https://chat-sdk.dev/adapters/official/redis) tracks which threads the bot has subscribed to, so follow-up messages in the same thread are handled automatically after the first mention.
+
+## Steps
+
+### 1\. Have your Comments app ready
+
+Before continuing, make sure you have a React app with Liveblocks Comments up and running. If you haven't set that up yet, follow the [quickstart guide](https://liveblocks.io/docs/get-started/comments) first.
+
+### 2\. Install Liveblocks, Chat SDK, and AI SDK
+
+Install the Liveblocks adapter, Chat SDK, AI SDK, and other related packages:
+
+`npm install @liveblocks/chat-sdk-adapter @liveblocks/node chat @chat-adapter/state-redis ai zod`
+
+The `chat` package is the Chat SDK core. `@liveblocks/chat-sdk-adapter` is the Liveblocks platform adapter. `ai` is the AI SDK, which includes `ToolLoopAgent`. `zod` is used to define tool input schemas. `@chat-adapter/state-redis` is the [Redis state adapter,](https://chat-sdk.dev/adapters/official/redis) which handles thread subscriptions and distributed locking.
+
+### 3\. Create a Liveblocks project
+
+Head to the [Liveblocks dashboard](https://liveblocks.io/dashboard), open the project you'd like to use, and copy the **Secret Key** from the **API Keys** page.
+
+### 4\. Add your environment variables
+
+Create a `.env.local` file in your project root:
+
+`LIVEBLOCKS_SECRET_KEY="sk_..." LIVEBLOCKS_WEBHOOK_SECRET="whsec_..." REDIS_URL="redis://localhost:6379"`
+
+You'll create the webhook secret further on in the guide.
+
+Instead of an AI Gateway API key, this guide uses [Vercel OIDC tokens](https://vercel.com/docs/ai-gateway/authentication-and-byok/authentication#oidc-token) to authenticate to the AI Gateway. Link your app to a Vercel project and pull the token into your local environment:
+
+`vercel link vercel env pull`
+
+`vercel env pull` writes a `VERCEL_OIDC_TOKEN` into `.env.local` alongside any other project environment variables. The AI SDK's [gateway provider](https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway) reads this token automatically when no `AI_GATEWAY_API_KEY` is set, so no code changes are needed.
+
+OIDC tokens expire after 12 hours, so re-run `vercel env pull` during longer development sessions to refresh it. In production on Vercel, the token is generated and rotated for you automatically.
+
+### 5\. Set up user resolution
+
+Create `app/database.ts` to export your bot's user ID and a `getUser` function. Chat SDK calls `resolveUsers` to convert user IDs from @-mentions into display names when constructing messages.
+
+The function must return an object matching this shape:
+
+`type UserInfo = { name: string; avatar?: string; color?: string; };`
+
+In production, query your own user database or auth provider:
+
+`export const BOT_USER_ID = "__bot__"; export const BOT_USER_NAME = "My Bot"; export async function getUser(id: string): Promise<UserInfo | undefined> { const user = await db.users.findUnique({ where: { id } }); return user ? { name: user.displayName, avatar: user.avatarUrl } : undefined; }`
+
+### 6\. Define your agent's tools
+
+Create `app/tools.ts` with the tools your agent can call. Each tool has a `description` that tells the model when to use it, an `inputSchema` that the model fills in, and an `execute` function that runs when the tool is called:
+
+``import { tool } from "ai"; import { z } from "zod"; export const tools = { getWeather: tool({ description: "Get the current weather for a location", inputSchema: z.object({ location: z.string().describe("City name, e.g. San Francisco"), }), execute: async ({ location }) => { // Replace with a real weather API call const response = await fetch( `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${encodeURIComponent(location)}` ); const data = await response.json(); return { location, temperature: data.current.temp_f, condition: data.current.condition.text, }; }, }), searchDocs: tool({ description: "Search the company documentation for a topic", inputSchema: z.object({ query: z.string().describe("The search query"), }), execute: async ({ query }) => { // Replace with your actual search implementation return { results: [`Result for: ${query}`] }; }, }), };``
+
+### 7\. Create the agent and bot instance
+
+Create `app/bot.ts` with a `ToolLoopAgent` and a `Chat` instance. The agent is configured with a model, a system prompt, and your tools. The bot wires the Liveblocks adapter and Redis state to your event handlers:
+
+`import { Chat } from "chat"; import { createLiveblocksAdapter, LiveblocksAdapter, } from "@liveblocks/chat-sdk-adapter"; import { createRedisState } from "@chat-adapter/state-redis"; import { ToolLoopAgent } from "ai"; import { BOT_USER_ID, BOT_USER_NAME, getUser } from "./database"; import { tools } from "./tools"; const agent = new ToolLoopAgent({ model: "anthropic/claude-sonnet-4-6", instructions: "You are a helpful assistant in a Liveblocks comment thread. " + "Answer questions clearly and use your tools when you need " + "up-to-date information. Keep responses concise.", tools, }); export const bot = new Chat<{ liveblocks: LiveblocksAdapter }>({ userName: BOT_USER_NAME, adapters: { liveblocks: createLiveblocksAdapter({ apiKey: process.env.LIVEBLOCKS_SECRET_KEY!, webhookSecret: process.env.LIVEBLOCKS_WEBHOOK_SECRET!, botUserId: BOT_USER_ID, botUserName: BOT_USER_NAME, resolveUsers: ({ userIds }) => { return userIds.map((id) => getUser(id)); }, }), }, state: createRedisState(), });`
+
+### 8\. Handle mentions and reactions
+
+Add event handlers to `app/bot.ts` after the bot instance. When someone @-mentions the bot, `onNewMention` fires. The handler acknowledges the message with a reaction, then streams the agent's response directly into the thread. `fullStream` is preferred over `textStream` because it preserves paragraph breaks between tool-calling steps:
+
+``// Handle @-mentions of the bot bot.onNewMention(async (thread, message) => { await thread.adapter.addReaction(thread.id, message.id, "👀"); const result = await agent.stream({ prompt: message.text }); await thread.post(result.fullStream); }); // Handle reactions to messages bot.onReaction(async (event) => { if (!event.added) return; await event.adapter.postMessage( event.threadId, `${event.user.userName} reacted with "${event.emoji.name}"` ); });``
+
+### 9\. Create the webhook route
+
+Create the API route at `app/api/webhooks/liveblocks/route.ts`. This is the endpoint Liveblocks will POST webhook events to:
+
+`import { bot } from "@/app/bot"; export async function POST(request: Request) { return bot.webhooks.liveblocks(request, { waitUntil: (p) => void p, }); }`
+
+For production deployments on Vercel, use `waitUntil` from `@vercel/functions` so your handler finishes processing after the HTTP response has been sent. This is required on serverless platforms where the function would otherwise terminate early:
+
+`import { bot } from "@/app/bot"; import { waitUntil } from "@vercel/functions"; export async function POST(request: Request) { return bot.webhooks.liveblocks(request, { waitUntil }); }`
+
+### 10\. Set up Liveblocks webhooks
+
+1.  Expose your dev server with a tunnel, for example using [ngrok](https://ngrok.com):
+    
+    `npx ngrok http 3000`
+    
+2.  Go to the [Liveblocks dashboard](https://liveblocks.io/dashboard) and create a new webhook endpoint. Set the URL to your generated ngrok URL, add your webhook route’s pathname to the end, and enable these events in the project dashboard:
+    
+    *   `commentCreated`
+        
+    *   `commentReactionAdded`
+        
+    *   `commentReactionRemoved`
+        
+3.  Copy the **webhook secret** and add it to `.env.local` as `LIVEBLOCKS_WEBHOOK_SECRET`:
+    
+    `LIVEBLOCKS_WEBHOOK_SECRET="whsec_..."`
+    
+
+Now when users @-mention your bot in a Liveblocks thread, it will stream a response and call tools autonomously.
+
+## How to add Slack, Teams, or other platforms
+
+Chat SDK supports multiple platforms from a single codebase. The event handlers and agent logic you've already defined work identically across all of them, since the SDK normalizes messages, threads, and reactions into a consistent format.
+
+To add Slack or Teams, install the relevant adapter packages and register them alongside the Liveblocks adapter:
+
+`npm install @chat-adapter/slack @chat-adapter/teams`
+
+Then add them to your `Chat` instance in `app/bot.ts`:
+
+`import { createSlackAdapter } from "@chat-adapter/slack"; import { createTeamsAdapter } from "@chat-adapter/teams"; export const bot = new Chat({ userName: BOT_USER_NAME, adapters: { liveblocks: createLiveblocksAdapter({ ... }), slack: createSlackAdapter(), teams: createTeamsAdapter(), }, state: createRedisState(), });`
+
+The existing webhook route already uses a `[platform]` parameter, so each platform gets its own endpoint automatically: `/api/webhooks/slack` and `/api/webhooks/teams`. No additional routing code is needed.
+
+Streaming behavior varies by platform. Slack uses its native streaming API for smooth real-time updates, while Liveblocks and Teams fall back to a post-then-edit pattern that throttles updates to avoid rate limits. You can adjust the update interval with the `streamingUpdateIntervalMs` option when creating your `Chat` instance.
+
+See the [Chat SDK adapter directory](https://chat-sdk.dev/adapters) for the full list of supported platforms and their configuration options.
+
+## Related resources
+
+*   [Chat SDK documentation](https://chat-sdk.dev)
+    
+*   [Chat SDK adapter directory](https://chat-sdk.dev/adapters)
+    
+*   [AI SDK agent documentation](https://ai-sdk.dev/docs/agents/building-agents)
+    
+*   [`@liveblocks/chat-sdk-adapter`](https://liveblocks.io/docs/api-reference/liveblocks-chat-sdk-adapter) [API reference](https://liveblocks.io/docs/api-reference/liveblocks-chat-sdk-adapter)
+    
+*   [Next.js Chat SDK bot quickstart](https://liveblocks.io/docs/get-started/nextjs-chat-sdk-bot)
+    
+*   [How to test webhooks on localhost](https://liveblocks.io/docs/guides/how-to-test-webhooks-on-localhost)
+
+---
+
+[View full KB sitemap](/kb/sitemap.md)

package/resources/guides/run-and-track-deploys-from-slack.md

@@ -21,7 +21,7 @@ This guide walks you through a Slack bot that orchestrates the entire deploy lif
 
 For production deploys, the bot gates the workflow with an approval step, so the deploy proceeds only after an authorized team member approves it.
 
-The bot is built with [Chat SDK](https://chat-sdk.dev) and [Vercel Workflow](https://vercel.com/workflow). Chat SDK handles the Slack interaction layer (cards, buttons, modals, and slash commands), while Vercel Workflow handles stateful orchestration (pausing for approval, polling GitHub, and resuming when events arrive). You write the deploy pipeline as a single function that pauses and resumes over minutes or hours without a database or state machine.
+The bot is built with [Chat SDK](https://chat-sdk.dev) and [Vercel Workflows](https://vercel.com/workflow). Chat SDK handles the Slack interaction layer (cards, buttons, modals, and slash commands), while Vercel Workflow handles stateful orchestration (pausing for approval, polling GitHub, and resuming when events arrive). You write the deploy pipeline as a single function that pauses and resumes over minutes or hours without a database or state machine.
 
 Deploy the template now, or read on for a deeper look at how it all works.
 
@@ -29,11 +29,11 @@ Deploy the template now, or read on for a deeper look at how it all works.
 
 If you're working with an AI coding agent like Claude Code or Cursor, you can clone the template and hand off implementation with this prompt:
 
-`I want to build a deploy bot for Slack using Chat SDK and Vercel Workflow. Clone the template repo at https://github.com/vercel-labs/chat-sdk-deploy-bot, install dependencies with pnpm, and walk me through setting up the environment variables in .env.local. I need a Slack app, a GitHub fine-grained personal access token with Actions (read/write), Contents (read), Issues (write), and Pull requests (read) permissions, and Redis (Upstash) configured. After setup, help me deploy it to Vercel and test the /deploy slash command. When searching for information, check for applicable skill(s) first and review local documentation.`
+`I want to build a deploy bot for Slack using Chat SDK and Vercel Workflows. Clone the template repo at https://github.com/vercel-labs/chat-sdk-deploy-bot, install dependencies with pnpm, and walk me through setting up the environment variables in .env.local. I need a Slack app, a GitHub fine-grained personal access token with Actions (read/write), Contents (read), Issues (write), and Pull requests (read) permissions, and Redis (Upstash) configured. After setup, help me deploy it to Vercel and test the /deploy slash command. When searching for information, check for applicable skill(s) first and review local documentation.`
 
 ### Vercel Plugin
 
-Turn your agent into a Vercel expert with this [plugin](https://vercel.com/docs/agent-resources/vercel-plugin). The [Chat SDK](https://skills.sh/vercel/chat/chat-sdk) and [Workflow](https://skills.sh/vercel/workflow/workflow) skills are both included.
+Turn your agent into a Vercel expert with this [plugin](https://vercel.com/docs/agent-resources/vercel-plugin). The [Chat SDK](https://skills.sh/vercel/chat/chat-sdk) and [Workflow](https://skills.sh/vercel/workflow/workflow) skills are both included. This plugin is optional; it’s not required to use Chat SDK or for this guide.
 
 `npx plugins add vercel/vercel-plugin`
 
@@ -173,7 +173,7 @@ The bot has three interfaces: Slack for user interaction, GitHub for dispatching
 6.  The bot posts a final summary card to Slack with the environment, branch, commit, duration, linked issues, and a link to the workflow run
     
 
-[Vercel Workflow](https://vercel.com/workflow) makes this possible. A Vercel Workflow function can suspend itself mid-execution and resume later with full state preserved. The approval gate and the polling loop are both regular code. The function pauses while waiting for a button click, resumes when it arrives, then loops while polling GitHub. No cron jobs, no queues, no external state store.
+[Vercel Workflows](https://vercel.com/workflow) makes this possible. A Vercel Workflow function can suspend itself mid-execution and resume later with full state preserved. The approval gate and the polling loop are both regular code. The function pauses while waiting for a button click, resumes when it arrives, then loops while polling GitHub. No cron jobs, no queues, no external state store.
 
 ## Code walkthrough
 
@@ -261,7 +261,9 @@ See the [Chat SDK adapter directory](https://chat-sdk.dev/adapters) for the full
     
 *   [Chat SDK GitHub](https://github.com/vercel/chat)
     
-*   [Vercel Workflow documentation](https://vercel.com/docs/workflow)
+*   [The Complete Guide to Chat SDK](https://vercel.com/kb/guide/the-complete-guide-to-chat-sdk)
+    
+*   [Vercel Workflows documentation](https://vercel.com/docs/workflow)
     
 *   [Workflow SDK](https://useworkflow.dev/)
 

package/resources/guides/ship-a-github-code-review-bot-with-hono-and-redis.md

@@ -39,7 +39,7 @@ Create a new Hono app and add the Chat SDK, AI SDK, and adapter packages:
 
 Select the `vercel` template when prompted by `create-hono`. This sets up the project for Vercel deployment with the correct entry point.
 
-The `chat` package is the Chat SDK core. The `@chat-adapter/github` and `@chat-adapter/state-redis` packages are the [GitHub platform adapter](https://chat-sdk.dev/adapters/github) and [Redis state adapter](https://chat-sdk.dev/adapters/redis). `@vercel/sandbox` provides the ephemeral execution environment, and `bash-tool` wires it up as an AI SDK tool.
+The `chat` package is the Chat SDK core. The `@chat-adapter/github` and `@chat-adapter/state-redis` packages are the [GitHub platform adapter](https://chat-sdk.dev/adapters/official/github) and [Redis state adapter](https://chat-sdk.dev/adapters/official/redis). `@vercel/sandbox` provides the ephemeral execution environment, and `bash-tool` wires it up as an AI SDK tool.
 
 ### 2\. Configure a GitHub webhook
 
@@ -142,6 +142,10 @@ The sandbox has a 5-minute timeout and the agent stops after 20 steps. For large
 
 Verify that `REDIS_URL` is reachable from your deployment environment. The state adapter uses Redis for distributed locking, so the bot won't process messages without a working connection.
 
+* * *
+
+## Build with a template or read more.
+
 ---
 
 [View full KB sitemap](/kb/sitemap.md)