代理软件开发工具包
- 作者仓库星标 164,300
- 作者仓库 opencode
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @anomalyco · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Cloudflare Agents SDK
**STOP.** Your knowledge of the Agents SDK may be outdated. Prefer retrieval over pre-training for any Agents SDK task.
## Documentation
Fetch current docs from `https://github.com/cloudflare/agents/tree/main/docs` before implementing.
| Topic | Doc | Use for |
| ------------------- | ----------------------------- | ---------------------------------------------- |
| Getting started | `docs/getting-started.md` | First agent, project setup |
| State | `docs/state.md` | `setState`, `validateStateChange`, persistence |
| Routing | `docs/routing.md` | URL patterns, `routeAgentRequest`, `basePath` |
| Callable methods | `docs/callable-methods.md` | `@callable`, RPC, streaming, timeouts |
| Scheduling | `docs/scheduling.md` | `schedule()`, `scheduleEvery()`, cron |
| Workflows | `docs/workflows.md` | `AgentWorkflow`, durable multi-step tasks |
| HTTP/WebSockets | `docs/http-websockets.md` | Lifecycle hooks, hibernation |
| Email | `docs/email.md` | Email routing, secure reply resolver |
| MCP client | `docs/mcp-client.md` | Connecting to MCP servers |
| MCP server | `docs/mcp-servers.md` | Building MCP servers with `McpAgent` |
| Client SDK | `docs/client-sdk.md` | `useAgent`, `useAgentChat`, React hooks |
| Human-in-the-loop | `docs/human-in-the-loop.md` | Approval flows, pausing workflows |
| Resumable streaming | `docs/resumable-streaming.md` | Stream recovery on disconnect |
Cloudflare docs: https://developers.cloudflare.com/agents/
## Capabilities
The Agents SDK provides:
- **Persistent state** - SQLite-backed, auto-synced to clients
- **Callable RPC** - `@callable()` methods invoked over WebSocket
- **Scheduling** - One-time, recurring (`scheduleEvery`), and cron tasks
- **Workflows** - Durable multi-step background processing via `AgentWorkflow`
- **MCP integration** - Connect to MCP servers or build your own with `McpAgent`
- **Email handling** - Receive and reply to emails with secure routing
- **Streaming chat** - `AIChatAgent` with resumable streams
- **React hooks** - `useAgent`, `useAgentChat` for client apps
## FIRST: Verify Installation
```bash
npm ls agents # Should show agents package
```
If not installed:
```bash
npm install agents
```
## Wrangler Configuration
```jsonc
{
"durable_objects": {
"bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }],
}
```
## Agent Class
```typescript
import { Agent, routeAgentRequest, callable } from "agents"
type State = { count: number }
export class Counter extends Agent<Env, State> {
initialState = { count: 0 }
// Validation hook - runs before state persists (sync, throwing rejects the update)
validateStateChange(nextState: State, source: Connection | "server") {
if (nextState.count < 0) throw new Error("Count cannot be negative")
}
// Notification hook - runs after state persists (async, non-blocking)
onStateUpdate(state: State, source: Connection | "server") {
console.log("State updated:", state)
}
@callable()
increment() {
this.setState({ count: this.state.count + 1 })
return this.state.count
}
}
export default {
fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 }),
}
```
## Routing
Requests route to `/agents/{agent-name}/{instance-name}`:
| Class | URL |
| ---------- | -------------------------- |
| `Counter` | `/agents/counter/user-123` |
| `ChatRoom` | `/agents/chat-room/lobby` |
Client: `useAgent({ agent: "Counter", name: "user-123" })`
## Core APIs
| Task | API |
| ------------------- | ------------------------------------------------------ |
| Read state | `this.state.count` |
| Write state | `this.setState({ count: 1 })` |
| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |
| Schedule (delay) | `await this.schedule(60, "task", payload)` |
| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |
| Schedule (interval) | `await this.scheduleEvery(30, "poll")` |
| RPC method | `@callable() myMethod() { ... }` |
| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |
| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |
## React Client
```tsx
import { useAgent } from "agents/react"
function App() {
const [state, setLocalState] = useState({ count: 0 })
const agent = useAgent({
agent: "Counter",
name: "my-instance",
onStateUpdate: (newState) => setLocalState(newState),
onIdentity: (name, agentType) => console.log(`Connected to ${name}`),
})
return <button onClick={() => agent.setState({ count: state.count + 1 })}>Count: {state.count}</button>
}
```
## References
- **[references/workflows.md](references/workflows.md)** - Durable Workflows integration
- **[references/callable.md](references/callable.md)** - RPC methods, streaming, timeouts
- **[references/state-scheduling.md](references/state-scheduling.md)** - State persistence, scheduling
- **[references/streaming-chat.md](references/streaming-chat.md)** - AIChatAgent, resumable streams
- **[references/mcp.md](references/mcp.md)** - MCP server integration
- **[references/email.md](references/email.md)** - Email routing and handling
- **[references/codemode.md](references/codemode.md)** - Code Mode (experimental)
章节与文件索引
按说明文件中的顺序排列。
文档
能力
首先:验证安装
路由
核心API
文件/命令 -> https://github.com/cloudflare/agents/tree/main/docs · docs/getting-started.md · docs/state.md · setState · validateStateChange · docs/routing.md · routeAgentRequest · basePath
内容校验值 -> 8f55ee42060a
当前原文的自动摘译,尚未人工审校。
文档
在实施之前从
https://github.com/cloudflare/agents/tree/main/docs获取当前文档。主题·文档·用于入门·docs/getting-started.md·第一个代理,项目设置状态·docs/state.md·setState,validateStateChange,持久性路由·docs/routing.md·URL模式,routeAgentRequest,basePath能力
Agents SDK 提供: 持久状态 - SQLite 支持,自动同步到客户端 可调用 RPC - 通过 WebSocket 调用的
@callable()方法 调度 - 一次性、重复 (scheduleEvery) 和 cron 任务 工作流程 - 通过AgentWorkflow进行持久的多步骤后台处理首先:验证安装
如果没有安装:
路由
请求路由到
/agents/{agent-name}/{instance-name}:类 · URLCounter·/agents/counter/user-123ChatRoom·/agents/chat-room/lobby客户端:useAgent({ agent: "Counter", name: "user-123" })核心API
任务 · API 读取状态 ·
this.state.count写入状态 ·this.setState({ count: 1 })SQL 查询 ·this.sql`SELECT * FROM users WHERE id = ${id}`Schedule (delay) ·await this.schedule(60, "task", Payload)