本文将逐行解读 Channels SDK 官方示例 minimal-channel，带你理解如何用不到 100 行代码，把一个 AI Agent 接入 Slack 等聊天平台，搭建出一个最小可行的 AI 频道。

Channels SDK 的定位是：把任何 AI Agent 带到任何聊天平台（Slack、Microsoft Teams、Discord、Telegram 等），并支持原生交互式 UI。minimal-channel就是这条理念的最小落地形态——一个常驻 Node 进程，完成「注册 Channel → 等待上线 → 收到 @提及后回复」的完整闭环。

一张图看懂架构：Agent、Channels 与聊天平台

在动手之前，先建立全局认知。Channels 充当「结构化交互层」，把 Agent（通过 AG-UI 协议通信）与各个聊天平台连接起来：

每一轮对话的路径都是：

1. 用户在 Slack 中 @机器人
2. CopilotKit Intelligence 收到平台事件，投递到你的 Channels 进程
3. Channels 通过 AG-UI 运行你的 Agent 并执行工具
4. Intelligence 把原生平台 UI 送回对话

示例文件结构：4 个文件各司其职

minimal-channel的 package.json 里只有 4 个核心依赖：@copilotkit/channels、@copilotkit/runtime、@ag-ui/client和dotenv。源码结构如下：

下面按执行顺序逐文件解读。

第一步：环境校验 lib/env.ts

lib/env.ts 只有 9 行，但体现了生产级代码的好习惯——快速失败（fail fast）：

export const required = (name: string) => { const value = process.env[name]; if (!value) throw new Error(`Missing ${name}`); return value; };

它从环境变量中读取值，一旦缺失就立刻抛出Missing ${name}错误，而不是让程序带着空配置悄悄跑飞。后续文件都会通过required("XXX")来取配置。

需要准备的.env变量包括：AGENT_URL（你的 AG-UI Agent 地址）、INTELLIGENCE_API_URL、INTELLIGENCE_GATEWAY_WS_URL和INTELLIGENCE_API_KEY。

第二步：创建 Channel 与消息处理 lib/channel.ts

lib/channel.ts 是示例的灵魂，核心代码不到 15 行：

const channel = createChannel({ name: "scratch", agent: new HttpAgent({ url: required("AGENT_URL") }), });

这里做了两件关键的事：

• createChannel：用name（频道名，需与 Intelligence 后台创建的 Channel 对应）和agent创建一个频道对象
• new HttpAgent({ url })：通过 AG-UI 的HttpAgent接入一个「通过 HTTP 可达的现成 Agent」。你的模型、工具、业务逻辑全部留在自己的基础设施里，Channels 只负责「传话」

然后是两个事件处理器：

channel.onMention(async ({ thread, message }) => { await thread.subscribe(); await thread.runAgent(); }); channel.onMessage(async ({ thread, message }) => { if (await thread.isSubscribed()) await thread.runAgent(); });

• onMention：当有人在频道中 @机器人 时触发，先subscribe()订阅这个对话线程，再runAgent()让 Agent 开始响应
• onMessage：线程内后续每条新消息都会触发；只有当线程「已订阅」时才运行 Agent——这意味着 Agent 会自动跟进对话上下文，而不必每次都被 @

这个「订阅制」设计正是最小示例的精髓：一次 @，整线程接管。

第三步：组装 Runtime lib/runtime.ts

lib/runtime.ts 把各部分串成一条流水线：

const intelligence = new CopilotKitIntelligence({ apiUrl: required("INTELLIGENCE_API_URL"), wsUrl: required("INTELLIGENCE_GATEWAY_WS_URL"), apiKey: required("INTELLIGENCE_API_KEY"), }); const runtime = new CopilotRuntime({ agents: {}, intelligence, identifyUser: () => ({ id: "scratch-user", name: "Scratch User" }), channels: [channel], }); export const listener = createCopilotNodeListener({ runtime, basePath: "/api/copilotkit", });

三层结构一目了然：

• CopilotKitIntelligence：负责平台连接（凭据、消息入站、断线重连），你不需要自己处理 Slack 的 webhook
• CopilotRuntime：运行时核心，挂载intelligence连接与channels列表，identifyUser决定以什么身份运行
• createCopilotNodeListener：把 runtime 包装成 Node HTTP 监听器，basePath: "/api/copilotkit"暴露生命周期控制端点

第四步：启动与优雅退出 server.ts

server.ts 只有 15 行，却覆盖了一个常驻服务的全部要点：

await listener.channels?.ready({ timeoutMs: 15_000 });

先等待channels.ready()再监听端口——这是很多教程会漏掉的关键一步。它确保 Channel 真正与 Intelligence 握手上线后，HTTP 服务才开始接流量。

const server = createServer(listener); server.listen(3000, () => { console.log("\nServer listening on port 3000..."); }); process.on("SIGINT", async () => { await listener.channels?.stop(); server.close(); });

收到SIGINT（Ctrl+C）时先channels.stop()断开频道连接、再关闭 HTTP 服务器，实现优雅退出，避免连接悬挂。

最快运行方法：3 条命令验证链路

按照 examples/minimal-channel/README.md 的步骤（需 Node.js 22+，并在 CopilotKit Intelligence 中创建好连接了 Slack 的 Channel）：

pnpm install cp .env.example .env # 填入 AGENT_URL 与 INTELLIGENCE_* 四个变量 pnpm dev

看到Server listening on port 3000...且 Intelligence 后台显示Online后，把应用拉进 Slack 频道并 @它——Agent 就会在对话线程中回复。链路打通后，只需把onMention里的逻辑换成带prompt的thread.runAgent()，就能让真正的模型参与对话。

从最小示例到生产级应用

minimal-channel的价值在于用最短路径验证「连接 → 订阅 → 响应」这条主干。当你需要文件感知、交互审批、多平台支持时，可以直接研读仓库内的完整应用 OpenTag——一个用 Python LangGraph Agent 构建的自托管 on-call 分诊助手，是 Channels SDK 组件如何组合成生产应用的参考样板，详见 examples/README.md。

一句话总结：Channels SDK 把「Agent 与聊天平台的通信」变成了一次createChannel的调用，而 minimal-channel 证明了这条链路只需要 4 个文件。