企业官网建设流程全解析

构建流式聊天智能体：Cloudflare Skills Agents SDK中的AIChatAgent、React客户端与MCP集成实战

【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skills

想快速上手 Cloudflare Agents SDK 构建流式聊天智能体吗？本文基于Cloudflare Skills（skills14/skills）开源项目，手把手带你完成三件事：用AIChatAgent搭建支持断线恢复的流式聊天后端、用useAgentChat接入 React 客户端、再用 MCP 协议为智能体接上外部工具。全程配置说明+少量代码，新手也能跟着做完。

📦 这个项目是什么？

Cloudflare Skills 是一套Agent Skills（智能体技能）集合，帮助 AI 编程助手掌握在 Cloudflare 平台上构建应用的方法，涵盖 Workers、Agents SDK、Durable Objects 等。其中 skills/agents-sdk/SKILL.md 专门教你构建有状态 AI 智能体：状态持久化、RPC 调用、定时任务、MCP 集成和流式聊天。

核心能力一览：

🚀 一键安装步骤：准备好 Agents SDK

聊天智能体需要 4 个包：Agents SDK、AI Chat 扩展、AI SDK 核心和 React 客户端：

npm install agents @cloudflare/ai-chat ai @ai-sdk/react

装完后用npm ls agents确认版本。项目入口文件通过routeAgentRequest把请求路由到智能体（见 skills/agents-sdk/references/routing.md）：

import { routeAgentRequest } from "agents"; export default { fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 }) };

⚙️ 最快配置方法：wrangler.jsonc 关键四要素

wrangler.jsonc是整个智能体的"户口本"，缺一样都跑不起来（详见 skills/agents-sdk/references/configuration.md）：

{ "compatibility_flags": ["nodejs_compat"], "durable_objects": { "bindings": [{ "name": "ChatAgent", "class_name": "ChatAgent" }] }, "migrations": [{ "tag": "v1", "new_sqlite_classes": ["ChatAgent"] }], "ai": { "binding": "AI" } }

四要素口诀：① 每个智能体类一个 Durable Objects 绑定；② 一个new_sqlite_classes迁移条目；③ 启用nodejs_compat；④ 加"ai"绑定以调用 Workers AI 模型。

⚠️ 本地开发时，在.dev.vars中加"ai": { "binding": "AI", "remote": true }才能连上真实的 Workers AI。

前端项目建议用 Vite 的agents()插件自动处理构建（配置示例同样在 configuration.md 中）。

🤖 构建 AIChatAgent：流式聊天服务端

AIChatAgent是 Agents SDK 专为聊天设计的基类，它帮你搞定三件麻烦事：消息持久化、流式输出、断线后流恢复（可恢复流，resumable streaming）。你只需关注模型和系统提示词，工具调用在onChatMessage中自行接线——完整对照见 skills/agents-sdk/references/streaming-chat.md。

两个新手最容易踩的要点：

• 转发取消信号：把请求的abort信号传给模型调用，用户点"停止"时生成会真正中断；
• 区分两种恢复：客户端断线重连、Durable Object 被驱逐（eviction）是两种独立的恢复场景，需分别处理。

💡 进阶提示：如果不想自己写streamText循环和工具执行，可以试试实验性的高阶类@cloudflare/think，它自动处理消息循环、工具执行与持久化，对比表见 skills/agents-sdk/references/think.md。

💻 接入 React 客户端：useAgent + useAgentChat

客户端选型很简单（参考 skills/agents-sdk/references/client-sdk.md）：

智能体默认路由为/agents/{类名转kebab}/{实例名}，例如类ChatAgent对应/agents/chat-agent/session-1。React 端两行代码接入：

const agent = useAgent({ agent: "ChatAgent", name: "session-1" }); const { messages, input, handleInputChange, handleSubmit } = useAgentChat({ agent });

useAgentChat直接返回消息列表和流式更新，配合handleSubmit就能搭出一个完整的聊天界面——这是构建流式聊天智能体前端的最短路径。

🔌 MCP 集成：给智能体接上外部工具

MCP（Model Context Protocol）让智能体"长出双手"。Agents SDK 支持双向角色（详见 skills/agents-sdk/references/mcp.md）：

• 做 MCP 客户端：连接外部 MCP 服务器，直接使用对方提供的工具、资源，支持 OAuth 鉴权与重试；
• 做 MCP 服务器：用createMcpHandler把自己的智能体能力暴露为标准 MCP 服务（新版首选，McpAgent已弃用），支持 Streamable HTTP、SSE 等传输方式。

本项目本身就自带一个远程 MCP 服务器配置 mcp.json（streamable-http类型），安装 plugin.json 插件后，AI 编程助手即可通过它访问 Cloudflare API 与开发者文档——这正是"技能 + MCP"组合的实际用途。

🌐 附赠：流式 RPC 与服务端主动消息

• 流式 RPC：@callable({ streaming: true })可让任意方法逐块向客户端推送数据，非聊天场景的流式输出首选（见 skills/agents-sdk/references/callable.md）；
• 服务端主动消息：通过saveMessages持久化消息并触发模型新回合，实现定时、Webhook 或邮件驱动的"智能体主动开口"（见 skills/agents-sdk/references/server-driven-messages.md）。

⚠️ 新手避坑清单

1. 别开experimentalDecorators：tsconfig 中启用它会让@callable装饰器失效；
2. 旧迁移永不修改：新增智能体类时追加新 tag（如v2），而不是改v1；
3. URL 大小写敏感：类名MyAgent在 URL 里必须写成 kebab-casemy-agent；
4. 手动创建的AgentClient用完要 close：React 钩子会自动清理，裸用则需手动关闭。

📂 关键文件导航

• 技能入口：skills/agents-sdk/SKILL.md
• 流式聊天：skills/agents-sdk/references/streaming-chat.md
• React 客户端：skills/agents-sdk/references/client-sdk.md
• MCP 集成：skills/agents-sdk/references/mcp.md
• 配置指南：skills/agents-sdk/references/configuration.md
• 项目总览：README.md

写在最后

从npm install到聊天界面跑起来，Cloudflare Agents SDK 给出的路径相当短：一个 wrangler 配置、一个AIChatAgent子类、两个 React 钩子。加上 MCP 集成后，你的流式聊天智能体就能安全地调用外部工具与 API——这正是构建流式聊天智能体完整闭环的推荐姿势。动手试试吧！

【免费下载链接】skillsSkills for teaching agents how to build on Cloudflare.项目地址: https://gitcode.com/gh_mirrors/skills14/skills