Agent Starter

这是一个基于 Cloudflare 构建 AI 聊天代理的入门模板，由 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 驱动的流式响应
• 图像输入 — 支持拖放、粘贴或点击上传图片，适配具备视觉能力的模型
• 三种工具模式 — 服务端自动执行、客户端（浏览器）执行以及需要人工确认的审批流
• 任务调度 — 支持一次性、延时和循环（cron）任务
• 推理展示 — 在流式传输时显示模型的思考过程，完成后自动折叠
• 调试模式 — 在头部开关，可检查每条消息的原始 JSON 数据
• Kumo UI — Cloudflare 的设计系统，支持深色/浅色模式
• 实时通信 — 基于 WebSocket，具备自动重连和消息持久化功能

自定义配置

命名项目

修改 package.json 和 wrangler.jsonc 中的名称。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，以便你的客户端可以直接调用。