Agents SDK 说明文档

# Cloudflare 智能体 SDK Cloudflare 智能体 SDK 能够基于 Durable Objects 构建 AI 驱动的智能体，支持状态、WebSocket、SQL、调度和 AI 集成。 ## 核心价值 构建具有持久化内存、实时连接、定时任务和异步工作流的全球分布式有状态 AI 智能体。 ## 何时使用 - 需要持久化状态 + 内存 - 实时 WebSocket 连接 - 长时间运行的工作流 (分钟/小时) - 带有 AI 模型的聊天界面 - 带有状态的定时/循环任务 - 带有智能体状态的数据库查询 ## 智能体类型 | 用例 | 类 | 关键特性 | |----------|-------|--------------| | AI 聊天界面 | `AIChatAgent` | 自动流式传输、工具、消息历史、可恢复 | | MCP 工具提供者 | `Agent` + MCP | 向 AI 系统暴露工具 | | 自定义逻辑/路由 | `Agent` | 完全控制、WebSocket、电子邮件、SQL | | 实时协作 | `Agent` | WebSocket 状态、广播 | | 电子邮件处理 | `Agent` | `onEmail()` 处理程序 | ## 快速入门 **AI 聊天智能体：** typescript import { AIChatAgent } from "agents"; import { openai } from "@ai-sdk/openai"; export class ChatAgent extends AIChatAgent { async onChatMessage(onFinish) { return this.streamText({ model: openai("gpt-4"), messages: this.messages, onFinish, }); } } **基础智能体：** typescript import { Agent } from "agents"; export class MyAgent extends Agent { onStart() { this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY)`; } async onRequest(request: Request) { return Response.json({ state: this.state }); } } ## 阅读顺序 | 任务 | 阅读文件 | |------|---------------| | 快速入门 | 仅 README | | 构建聊天智能体 | README → api.md (AIChatAgent) → patterns.md | | 设置项目 | README → configuration.md | | 添加 React 前端 | README → api.md (Client Hooks) → patterns.md | | 构建 MCP 服务器 | api.md (MCP) → patterns.md | | 后台任务 | api.md (Scheduling, Task Queue) → patterns.md | | 调试问题 | gotchas.md | ## 包入口点 | 导入 | 用途 | |--------|---------| | `agents` | 服务端智能体类、生命周期 | | `agents/react` | 用于 WebSocket 连接的 `useAgent()` 钩子 | | `agents/ai-react` | 用于 AI 聊天 UI 的 `useAgentChat()` 钩子 | ## 本参考资料内容 - [configuration.md](./configuration.md) - SDK 设置, wrangler 配置, 路由 - [api.md](./api.md) - 智能体类, 生命周期, 客户端钩子 - [patterns.md](./patterns.md) - 通用模式