Overview

AI utilities that ship with Chat SDK — agent tools, message conversion, and supporting types.

The chat/ai subpath is the home for AI utilities that ship with Chat SDK.

import { createChatTools, toAiMessages } from "chat/ai";

Add the optional peers if you don't already have them:

pnpm add ai zod

What's included

PageWhat it gives you
AI SDK ToolscreateChatTools and standalone tool factories that let an agent post messages, send DMs, react, edit, delete, and manage subscriptions across every adapter your Chat instance has registered. Built-in approval gates and presets keep writes safe.
toAiMessagesConvert Chat SDK Message[] into the { role, content }[] shape expected by AI SDK calls. Handles role mapping, attachments, links, sorting, and optional per-message transforms.
TypesReference for every type exported from chat/ai — agent message shapes, tool option contracts, presets, approval config, and the binding type that ties tools to your Chat instance.

Typical flow

A Chat SDK bot wired to a tool-calling agent usually looks like this:

lib/agent.ts
import { Chat } from "chat";
import { createChatTools, toAiMessages } from "chat/ai";
import { ToolLoopAgent } from "ai";

const chat = new Chat({ /* adapters, state, ... */ });

const agent = new ToolLoopAgent({
  model: "xai/grok-4.5",
  instructions: "You operate inside a chat workspace via Chat SDK tools.",
  tools: createChatTools({ chat, preset: "messenger", requireApproval: true }),
});

bot.onSubscribedMessage(async (thread) => {
  const { messages } = await thread.adapter.fetchMessages(thread.id, {
    limit: 20,
  });
  const history = await toAiMessages(messages);
  const result = await agent.stream({ prompt: history });
  await thread.post(result.fullStream);
});
  1. toAiMessages converts messages into an output compatible with AI SDK's ModelMessage[].
  2. createChatTools gives the agent pre-built and fully customizable AI SDK tools.
  3. The streamed response is rendered back into the thread via the standard thread.post(stream) flow.

Backwards compatibility

toAiMessages and the related Ai* types are still re-exported from the top-level chat package so older bots keep working. Those re-exports are now flagged with @deprecated JSDoc — your editor will surface a hint pointing at chat/ai. Migrating is a one-line import change:

- import { toAiMessages } from "chat";
+ import { toAiMessages } from "chat/ai";

Resources

  • Human-in-the-Loop with Chat SDK and Workflow SDK — Pause durable workflows on Slack approval cards using Chat SDK and Workflow SDK. Uses createWebhook to suspend workflows until a button click, with patterns for multi-stage approvals, timeouts via durable sleep, and approver validation.

See all guides and templates on the resources page.

Read more

AI SDK Tools

Give an AI agent the ability to operate inside your workspace. Post messages, send DMs, react, edit, delete; all with built-in approval gates.

toAiMessages

Convert Chat SDK messages to AI SDK conversation format.

Types

TypeScript types exported from the chat/ai subpath.

Overview

Overview of Chat SDK adapters and the static adapter catalog.

PreviousTestingNextAI SDK Tools