Agent Starter

这是一个在 Cloudflare 上构建 AI 聊天代理（Agent）的入门模板，由 Agents SDK 提供支持。

它使用了 Workers AI（无需 API key），并内置了天气查询、时区检测、带审批机制的计算工具、任务调度以及视觉（图像输入）功能。

快速开始

npx create-cloudflare@latest --template cloudflare/agents-starter
cd agents-starter
npm install
npm run dev

打开 http://localhost:5173 查看你的代理运行效果。

尝试以下提示词来体验各项功能：

• "What's the weather in Paris?" — 服务端工具（自动运行）
• "What timezone am I in?" — 客户端工具（浏览器提供答案）
• "Calculate 5000 * 3" — 审批工具（运行前会询问你）
• "Remind me in 5 minutes to take a break" — 任务调度
• 拖入一张图片并询问 "What's in this image?" — 视觉（图像理解）

项目结构

src/
  server.ts    # 包含工具和任务调度的聊天代理
  app.tsx      # 基于 Kumo 组件构建的聊天 UI
  client.tsx   # React 入口文件
  styles.css   # Tailwind + Kumo 样式

功能特性

• AI 聊天 — 通过 AIChatAgent 利用 Workers AI 实现流式响应
• 图像输入 — 支持拖拽、粘贴或点击上传图片，供具备视觉能力的模型使用
• 三种工具模式 — 服务端自动执行、客户端（浏览器）执行，以及人工介入审批
• 任务调度 — 支持单次、延迟和周期性（Cron）任务
• 推理展示 — 在流式传输时展示模型思考过程，结束后可折叠
• 调试模式 — 在头部开关，可检查每条消息的原始 JSON 数据
• Kumo UI — Cloudflare 设计系统，支持深色/浅色模式
• 实时通信 — 基于 WebSocket 连接，支持自动重连和消息持久化

自定义你的项目

重命名项目

修改 package.json 和 wrangler.jsonc 中的 name 字段 —— wrangler.jsonc 中的 name 将成为你部署后的 Worker URL（...workers.dev）。

修改系统提示词（System Prompt）

编辑 server.ts 中的 system 字符串，为你的代理设置不同的个性或专注领域。这是你能做出的最直接有效的影响点。

将演示工具替换为真实工具

该模板自带了一些演示工具（getWeather 返回随机数据，calculate 执行基础算术）。请将其替换为真实的实现：

// 在 server.ts 中，将演示工具替换为真实的 API 调用：
getWeather: tool({
  description: "Get the current weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async ({ city }) => {
    const res = await fetch(`https://api.weather.example/${city}`);
    return res.json();
  }
}),

添加自定义工具

在 server.ts 的 tools 对象中添加新工具。共有三种模式：

// 自动执行：在服务端运行，无需用户交互
myTool: tool({
  description: "...",
  inputSchema: z.object({ /* ... */ }),
  execute: async (input) => { /* 返回结果 */ }
}),

// 客户端执行：没有 execute 函数，由浏览器提供结果
// 在 app.tsx 中通过 onToolCall 回调进行处理
browserTool: tool({
  description: "...",
  inputSchema: z.object({ /* ... */ })
}),

// 审批模式：添加 needsApproval 来拦截执行
sensitiveTool: tool({
  description: "...",
  inputSchema: z.object({ /* ... */ }),
  needsApproval: async (input) => true, // 或逻辑判断
  execute: async (input) => { /* 审批后运行 */ }
}),

自定义定时任务行为

当定时任务触发时，executeTask 会在服务端运行。它完成工作后，会使用 this.broadcast() 通知已连接的客户端（在 UI 中显示为 Toast 通知）。你可以将其替换为自己的逻辑：

async executeTask(description: string, task: Schedule) {
  // 执行实际工作
  await sendEmail({ to: "user@example.com", subject: description });

  // 通知已连接的客户端
  this.broadcast(
    JSON.stringify({ type: "scheduled-task", description, timestamp: new Date().toISOString() })
  );
}

为什么使用 broadcast() 而不是 saveMessages()？ 注入到聊天记录中可能会导致 AI 将通知视为新的上下文，从而在循环中重复触发相同的任务。broadcast() 发送的是一次性事件，客户端会将其与对话内容分开显示。

移除任务调度

如果你不需要调度功能，请从 tools 对象中移除 scheduleTask、getScheduledTasks 和 cancelScheduledTask，同时移除 executeTask 方法以及与调度相关的导入（getSchedulePrompt、scheduleSchema、Schedule、generateId）。

添加聊天消息之外的状态

使用 this.setState() 和 this.state 来实现实时状态，并同步到所有已连接的客户端。详情参考 存储与同步状态 (Store and sync state)。

添加可调用方法

将代理方法公开为类型化的 RPC，以便你的客户端可以直接调用。