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 zodWhat's included
| Page | What it gives you |
|---|---|
| AI SDK Tools | createChatTools 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. |
toAiMessages | Convert Chat SDK Message[] into the { role, content }[] shape expected by AI SDK calls. Handles role mapping, attachments, links, sorting, and optional per-message transforms. |
| Types | Reference 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:
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: "anthropic/claude-sonnet-4.6",
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);
});toAiMessagesconverts messages into an output compatible with AI SDK'sModelMessage[].createChatToolsgives the agent pre-built and fully customizable AI SDK tools.- 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";