agents-starter

基于 Cloudflare 边缘，几分钟搭出带状态和工具的 AI Agent

agents-starter 是 Cloudflare 官方推出的 AI Agent 开发脚手架，基于 TypeScript 编写，核心思路是把每个 Agent 建模为一个 Durable Object，从而天然获得持久化状态、WebSocket 长连接和按需伸缩能力。它解决的是开发者从零搭建 Agent 时反复处理会话状态、消息路由、工具调用和部署的问题：项目内置了对话循环、工具（函数）调用、状态存储、流式响应等基础能力，并可直接部署到 Cloudflare Workers 边缘网络。开发者只需在模板上定义自己的工具函数和系统提示词，就能快速得到一个可对外服务的 Agent，无需自建服务器或数据库。它适合希望低成本、低延迟上线 AI Agent 的个人开发者和小团队，也是理解 Durable Objects 与 Agent 结合方式的参考实现。

开源 free 开发框架

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 1334

维护状态较活跃

是否开源是

定价模式 free

项目数据

分类开发框架

开发团队cloudflare

所属国家

官网地址https://github.com/cloudflare/agents

GitHubhttps://github.com/cloudflare/agents-starter

定价模式free

价格说明开源免费，基于 Cloudflare Workers 部署

访问状态

是否开源是

开源协议MIT

主要语言TypeScript

技术栈/模型agents,ai,cloudflare,durable-objects

GitHub 星标★ 1334

30天Star增速

HF 下载量

上线时间2025-02-21 00:00:00

最近更新2026-09-14 00:00:00

维护状态较活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-09-12

浏览次数3

使用教程

难度：入门约 10 分钟部署方式：云服务 7 步

环境要求

Node.js 环境（需使用 npx 执行 create-cloudflare）
Cloudflare 账号，并在交互式终端执行一次 wrangler login 完成认证
无需 OpenAI/Anthropic 等第三方 API Key（使用 Workers AI）
本地开发会通过远程代理访问 Cloudflare，需保持网络可访问 Cloudflare

安装与启动步骤

1创建项目模板

用 Cloudflare 官方脚手架拉取 agents-starter 模板并初始化项目，按提示选择目录与配置。
```
npx create-cloudflare@latest --template cloudflare/agents-starter
```
2进入项目目录

切换到脚手架生成的目录，后续命令都在该目录下执行。
```
cd agents-starter
```
3安装依赖

安装模板所需的 npm 依赖，包括 Agents SDK 与构建工具。
```
npm install
```
4登录 Cloudflare

README 要求本地运行前必须完成 Cloudflare 认证，可在交互式终端执行一次登录；也可改用 CLOUDFLARE_API_TOKEN。
```
wrangler login
```
5启动本地开发

启动开发服务器，会打开一个指向 Cloudflare 的远程代理会话，因此必须已认证。
```
npm run dev
```
6在浏览器验证

打开本地地址，用天气、时区、计算、定时提醒、图片理解等提示词测试各类工具能力。
7部署到 Cloudflare

运行部署命令，Agent 会上线到 Cloudflare 全球网络，消息持久化到 SQLite。
```
npm run deploy
```

关键配置

配置项	必填	说明	示例
`CLOUDFLARE_API_TOKEN`	否	非交互环境下替代 wrangler login 的认证方式，可写入 .env 文件	`your-cloudflare-api-token`
`ai.remote`	是	wrangler.jsonc 中 Workers AI 的配置，设为 true 表示走远程调用	`"ai": { "remote": true }`

如何确认成功

本地 npm run dev 启动后打开 http://localhost:5173 能看到聊天界面，并可用示例提示词得到回答，即表示运行成功。

常见问题

Q：不登录 Cloudflare 能本地运行吗？

A：不能。模板在 wrangler.jsonc 中把 Workers AI 设为 remote，且 Workers AI 没有本地模拟器，npm run dev 会建立远程代理会话，必须完成 wrangler login 或配置 CLOUDFLARE_API_TOKEN。

Q：需要准备 OpenAI 或 Anthropic 的 API Key 吗？

A：不需要。项目使用 Workers AI，README 明确说明无需第三方密钥，但需要 Cloudflare 登录。

Q：本地开发页面地址是什么？

A：默认是 http://localhost:5173，npm run dev 启动后直接在浏览器打开即可。

Q：如何验证工具调用、审批、定时、视觉等功能？

A：依次尝试 “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?”。

注意事项

本地运行依赖 Cloudflare 远程代理，断网或未认证时会启动失败。
API Token 属于敏感信息，建议放在 .env 中，不要提交到代码仓库。
部署后消息持久化在 SQLite 中，断线可恢复流式响应，空闲时 Agent 会自动休眠。

核心亮点

用 Durable Object 承载 Agent，会话状态、WebSocket 连接和持久化开箱即用，不用自己搭数据库
内置工具调用与流式响应循环，改几个工具函数和提示词即可跑通完整 Agent
部署在 Cloudflare Workers 边缘网络，冷启动低、全球就近响应，按用量计费成本可控

不足之处

强绑定 Cloudflare 平台与 Durable Objects，迁移到其他云或自托管成本高
作为 starter 功能偏基础，缺少现成的 RAG、多 Agent 编排、评测等进阶模块
社区规模和第三方示例相对有限，遇到边缘场景问题可参考的资料不多

适用场景

快速搭建一个带多轮记忆和工具调用的客服/助手 Agent 并上线
在 Cloudflare 生态内做低延迟、全球分布的 AI 聊天机器人
学习 Durable Objects 如何与 LLM 结合，作为 Agent 架构的教学与原型起点

替代项目

LangChain、Mastra、Vercel AI SDK

项目介绍

agents-starter 是一个开发框架领域的开源项目，官方简介：A starter kit for building ai agents on Cloudflare。项目使用 TypeScript 开发，在 GitHub 上获得 1331 星标。

上一篇：connectonion

下一篇：coding-tools-mcp