# Agents

Build AI-powered agents to perform tasks, persist state, browse the web, and communicate in real-time

> Links below point directly to Markdown versions of each page. Any page can also be retrieved as Markdown by sending an `Accept: text/markdown` header to the page's URL without the `index.md` suffix (for example, `curl -H "Accept: text/markdown" https://cloudflaredoc.ubitools.com/agents/`).
>
> For other Cloudflare products, see the [Cloudflare documentation directory](https://cloudflaredoc.ubitools.com/llms.txt).

## Overview

- [在 Cloudflare 上构建 Agents](https://cloudflaredoc.ubitools.com/agents/index.md): 使用 Cloudflare Agents SDK 创建具有持久化内存、实时 WebSocket 连接和调度任务的有状态 AI Agent。

## Harness（控制循环）

- [Harness（控制循环）](https://cloudflaredoc.ubitools.com/agents/harnesses/index.md): 了解 Agent harness——控制规划、工具使用和响应流程的循环。
- [Think](https://cloudflaredoc.ubitools.com/agents/harnesses/think/index.md): 内置工具、持久化记忆、生命周期钩子、流式传输、messenger、调度任务、Workflow 与子 Agent RPC 的约定式聊天 Agent 框架。
- [操作（Actions）](https://cloudflaredoc.ubitools.com/agents/harnesses/think/actions/index.md): 带幂等性、人工审批、授权与回复附件的服务端 Think 工具。
- [渠道](https://cloudflaredoc.ubitools.com/agents/harnesses/think/channels/index.md): 为 web、messenger、voice 与自定义界面应用按渠道策略、在轮次上选择渠道并投递带外通知。
- [客户端工具](https://cloudflaredoc.ubitools.com/agents/harnesses/think/client-tools/index.md): Think Agent 的浏览器端工具、审批流程、自动续传、消息并发与多标签广播。
- [配置](https://cloudflaredoc.ubitools.com/agents/harnesses/think/configuration/index.md): Think 聊天 Agent 框架的配置覆盖、动态运行时配置、Session 集成与包导出。
- [快速入门](https://cloudflaredoc.ubitools.com/agents/harnesses/think/getting-started/index.md): 分步构建带持久内存、内置文件工具、自定义工具与流式传输的 Think 聊天 Agent。
- [生命周期钩子](https://cloudflaredoc.ubitools.com/agents/harnesses/think/lifecycle-hooks/index.md): Think 聊天轮次各阶段的钩子 — `beforeTurn`、`beforeStep`、`beforeToolCall`、`afterToolCall`、`onStepFinish`、`onChunk`、`onChatResponse` 与 `onChatError`。
- [Messenger](https://cloudflaredoc.ubitools.com/agents/harnesses/think/messengers/index.md): 从 Think agent 直接接收并回复 Chat SDK messenger webhook，含 Telegram 设置、路由、对话目标与恢复。
- [编程式提交](https://cloudflaredoc.ubitools.com/agents/harnesses/think/programmatic-submissions/index.md): 使用 submitMessages() 持久接受 Think 轮次，适用于 webhook 与 RPC 调用方，支持幂等重试、状态检查与取消。
- [持久化恢复](https://cloudflaredoc.ubitools.com/agents/harnesses/think/recovery/index.md): Think Agent 的有界聊天恢复、流式停滞看门狗、修复中断的工具调用与稳定性检测。
- [调度任务](https://cloudflaredoc.ubitools.com/agents/harnesses/think/scheduled-tasks/index.md): 使用 getScheduledTasks() 和带类型的调度 DSL 声明循环、时区感知的 Think 轮次和确定性处理程序。
- [子 agent RPC 与编程式轮次](https://cloudflaredoc.ubitools.com/agents/harnesses/think/sub-agents/index.md): 通过 chat() 经子 Agent 流式传输 Think 轮次，并用 saveMessages()、continueLastTurn() 与中止编程触发轮次。
- [工具](https://cloudflaredoc.ubitools.com/agents/harnesses/think/tools/index.md): Think agent 的内置工作区工具（含 bash）、自定义工具、审批、MCP 工具、代码执行、浏览器工具与扩展。
- [Workflow](https://cloudflaredoc.ubitools.com/agents/harnesses/think/workflows/index.md): 在 Cloudflare Workflow 内用 ThinkWorkflow 与 step.prompt() 运行持久的模型驱动推理步骤，含结构化输出与超时。

## Model Context Protocol（MCP）概览

- [Model Context Protocol（MCP）概览](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/index.md): 了解 MCP 协议、Cloudflare 集成与 Agents SDK API。
- [McpAgent](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/apis/agent-api/index.md): 通过扩展 McpAgent 类构建 stateful MCP server，具备持久化存储与 Agent 能力。
- [McpClient](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/apis/client-api/index.md): 将 Agent 连接到外部 MCP server，通过 Model Context Protocol 使用其 tool、resource 与 prompt。
- [createMcpHandler 参考](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/apis/handler-api/index.md): 使用 createMcpHandler 与 streamable HTTP 传输为普通 Worker 创建无状态 MCP 服务器 fetch 处理程序。
- [MCP 服务器门户](https://cloudflaredoc.ubitools.com/cloudflare-one/access-controls/ai-controls/mcp-portals/index.md): 将多个 MCP 服务器集中到单一端点，并自定义用户可用的工具、prompt 和资源。
- [Cloudflare 自有 MCP 服务器](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/index.md): 连接到 Cloudflare 托管的远程 MCP 服务器，读取配置、管理服务并跨账户自动化操作。
- [Cloudflare Community MCP 服务器指南](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/community-mcp-server/index.md): 了解如何使用 Cloudflare Community MCP server 搜索主题、阅读帖子并筛选内容。
- [Code Mode MCP 服务器模式](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/codemode/index.md): 了解通过 MCP 暴露工具与大型 API 的单代码工具与搜索并执行模式。
- [构建单工具 Code Mode MCP server](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/build-codemode-mcp-server/index.md): 在 Cloudflare Workers 上用单个沙箱 Code Mode 工具替换 MCP server 的各个独立工具。
- [构建搜索并执行 MCP 服务器](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/build-codemode-openapi-mcp-server/index.md): 从 OpenAPI 文档创建 Code Mode 搜索并执行 MCP 工具，同时将凭证保留在宿主 Worker 中。
- [连接到 MCP 服务器](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/connect-mcp-client/index.md): 创建一个连接到外部 MCP 服务器并使用其 tool 的 Cloudflare Agent。
- [处理 MCP 服务器的 OAuth](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/oauth-mcp-client/index.md): 在 Cloudflare Agents 中实现 OAuth 认证流程以连接到受保护的 MCP 服务器。
- [构建远程 MCP server](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/remote-mcp-server/index.md): 在 Cloudflare 上部署远程 MCP server，可选使用 Streamable HTTP 传输进行身份验证。
- [保护 MCP 服务器](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/securing-mcp-server/index.md): 在 Cloudflare 上使用 OAuth 2.1、token 验证与基于 scope 的访问控制保护 MCP 服务器。
- [测试远程 MCP 服务器](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/guides/test-remote-mcp-server/index.md): 使用 MCP Inspector 与兼容的 MCP 客户端测试 remote MCP server。
- [授权](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/protocol/authorization/index.md): 使用 Cloudflare Access、第三方提供商或自有身份系统为 MCP server 添加 OAuth 2.1 授权。
- [MCP 治理](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/protocol/governance/index.md): 控制组织使用的 MCP 服务器，并通过 Cloudflare Access 强制执行访问策略。
- [工具](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/protocol/tools/index.md): 定义、注册与管理 MCP tool，向 AI Agent 暴露可调用的服务端函数。
- [传输](https://cloudflaredoc.ubitools.com/agents/model-context-protocol/protocol/transport/index.md): 为使用 Agents SDK 构建的远程 MCP 服务器配置 Streamable HTTP 传输。

## communication-channels

- [自主响应](https://cloudflaredoc.ubitools.com/agents/communication-channels/chat/autonomous-responses/index.md): 从 Cloudflare Agents 发送服务端发起的消息并触发 LLM 响应，无需用户操作。
- [聊天 Agent](https://cloudflaredoc.ubitools.com/agents/communication-channels/chat/chat-agents/index.md): 使用 AIChatAgent 与 useAgentChat 构建 AI 聊天界面，含消息持久化、流式传输与 tool 支持。
- [客户端 SDK](https://cloudflaredoc.ubitools.com/agents/communication-channels/chat/client-sdk/index.md): 使用 useAgent、AgentClient 与 agentFetch 从 browser 或服务端 runtime 连接 Cloudflare Agent。
- [邮件](https://cloudflaredoc.ubitools.com/agents/communication-channels/email/index.md): 将 Agent 连接到邮件，使其能够发送出站消息、处理入站邮件并处理后续回复。
- [Slack 集成](https://cloudflaredoc.ubitools.com/agents/communication-channels/slack/index.md): 将 Agent 连接到 Slack 工作区，使其能够响应私信、提及和线程对话。
- [语音](https://cloudflaredoc.ubitools.com/agents/communication-channels/voice/index.md): 使用语音转文本、文本转语音和 WebSocket 上的对话持久化构建实时语音 Agent。
- [Webhook](https://cloudflaredoc.ubitools.com/agents/communication-channels/webhooks/index.md): 接收来自外部服务的 webhook 事件并将其路由到专用 Cloudflare Agent 实例。
- [推送通知](https://cloudflaredoc.ubitools.com/agents/communication-channels/webhooks/push-notifications/index.md): 从 Cloudflare Agent 发送浏览器推送通知，即使用户已关闭标签页。

## concepts

- [Agentic 模式](https://cloudflaredoc.ubitools.com/agents/concepts/agentic-patterns/index.md): 在 Cloudflare 上实现常见的 AI Agent 模式，如提示链、路由、并行化与编排者-工作者。
- [人机协同模式](https://cloudflaredoc.ubitools.com/agents/concepts/agentic-patterns/human-in-the-loop/index.md): 使用 Workflow 审批、持久 Code Mode 审批与 MCP elicitation 实现人机协同。
- [长期运行 Agent](https://cloudflaredoc.ubitools.com/agents/concepts/agentic-patterns/long-running-agents/index.md): 构建可持续数天、数周或数月的 Agent——在重启后存活、按需唤醒，并管理远超单次请求时长的任务。
- [调用 LLM](https://cloudflaredoc.ubitools.com/agents/concepts/calling-llms/index.md): 在有状态的 Cloudflare Agent 内调用大语言模型，具备持久化上下文与自主调度能力。
- [对话状态与内存](https://cloudflaredoc.ubitools.com/agents/concepts/conversation-state-and-memory/index.md): Agent 如何存储与回忆信息，包括只读上下文、可写短期内存、可搜索知识与按需技能。
- [工具](https://cloudflaredoc.ubitools.com/agents/concepts/tools/index.md): 了解工具如何暴露给模型、工具在何处执行，以及 MCP 如何将外部工具连接到 Cloudflare Agents。
- [什么是 Agent？](https://cloudflaredoc.ubitools.com/agents/concepts/what-are-agents/index.md): 了解 Agent 是什么、它与 Workflow 和 co-pilot 有何不同，以及何时应使用 Agent。
- [将 Agent 与 Workflow 配合使用](https://cloudflaredoc.ubitools.com/agents/concepts/workflows/index.md): 将 Cloudflare Workflow 与 Agent 集成，实现带自动重试的持久化多步后台处理。

## examples

- [Browser Agent 示例](https://cloudflaredoc.ubitools.com/agents/examples/browser-agent/index.md): 构建使用 Browser Run tool 检查页面、截取屏幕截图、抓取渲染内容并调试前端问题的 Agent。
- [聊天 Agent 示例](https://cloudflaredoc.ubitools.com/agents/examples/chat-agent/index.md): 使用 Workers AI 构建带 tool 的流式 AI 聊天 Agent — 无需 API 密钥。
- [Email Agent 示例](https://cloudflaredoc.ubitools.com/agents/examples/email-agent/index.md): 使用 Cloudflare Email Service 与 Agents SDK 构建可发送、接收、路由和回复邮件的 Agent。
- [Slack Agent 示例](https://cloudflaredoc.ubitools.com/agents/examples/slack-agent/index.md): 使用 Agents SDK 在 Cloudflare Workers 上构建并部署 AI 驱动的 Slack bot。
- [Voice Agent 示例](https://cloudflaredoc.ubitools.com/agents/examples/voice-agent/index.md): 在 Cloudflare Workers 上构建具备 speech-to-text、LLM 处理与 text-to-speech 的实时 voice agent。

## getting-started

- [添加到现有项目](https://cloudflaredoc.ubitools.com/agents/getting-started/add-to-existing-project/index.md): 向现有 Cloudflare Workers 项目添加 Agents SDK，实现状态管理和实时连接。
- [快速入门](https://cloudflaredoc.ubitools.com/agents/getting-started/quick-start/index.md): 10 分钟内构建你的第一个 Agent——一个将状态持久化并实时同步到 React 前端的计数器。
- [测试 Agent](https://cloudflaredoc.ubitools.com/agents/getting-started/testing-your-agent/index.md): 使用 Vitest 和 Workers 测试池编写并运行 Cloudflare Agents 测试。

## platform

- [限制](https://cloudflaredoc.ubitools.com/agents/platform/limits/index.md): 了解适用于 Cloudflare Agents 的并发、存储和计算时间限制。

## runtime

- [Agents API 参考](https://cloudflaredoc.ubitools.com/agents/runtime/agents-api/index.md): Agents SDK 中 Agent 基类、生命周期钩子、SQL 存储与错误处理的参考。
- [聊天 SDK](https://cloudflaredoc.ubitools.com/agents/runtime/communication/chat-sdk/index.md): 将 Chat SDK 与 Agent 集成，包括订阅、锁、队列与消息历史的持久状态。
- [HTTP 与 Server-Sent Events](https://cloudflaredoc.ubitools.com/agents/runtime/communication/http-sse/index.md): 从 Cloudflare Agent 处理 HTTP 请求并使用 Server-Sent Events (SSE) 流式返回响应。
- [协议消息](https://cloudflaredoc.ubitools.com/agents/runtime/communication/protocol-messages/index.md): 控制 Agent 连接时向 WebSocket 客户端发送的身份、state 与 MCP 协议消息。
- [只读连接](https://cloudflaredoc.ubitools.com/agents/runtime/communication/readonly-connections/index.md): 将 WebSocket 客户端限制为只读访问，使其接收 state 更新而不修改 Agent state。
- [路由](https://cloudflaredoc.ubitools.com/agents/runtime/communication/routing/index.md): 使用 routeAgentRequest() 与 getAgentByName() 将 HTTP 与 WebSocket 请求路由到 Agents SDK 实例。
- [WebSocket](https://cloudflaredoc.ubitools.com/agents/runtime/communication/websockets/index.md): 在 Agents SDK 中处理实时 WebSocket 连接、消息、广播与生命周期钩子。
- [Agent Skills 参考](https://cloudflaredoc.ubitools.com/agents/runtime/execution/agent-skills/index.md): 使用 agents/skills 为 Agent 提供按需指令、资源与脚本目录，仅在任务匹配时由模型激活。
- [Agent 作为工具](https://cloudflaredoc.ubitools.com/agents/runtime/execution/agent-tools/index.md): 从父 Agent 将 Think 与 AIChatAgent 子 Agent 作为可保留、可流式传输的工具运行。
- [使用 fiber 的持久执行](https://cloudflaredoc.ubitools.com/agents/runtime/execution/durable-execution/index.md): 使用 runFiber()、startFiber()、keepAlive() 和崩溃恢复运行可在 Durable Object 驱逐后存活的工作。
- [队列任务](https://cloudflaredoc.ubitools.com/agents/runtime/execution/queue-tasks/index.md): 向 Cloudflare Agents 内置 FIFO 队列添加后台任务以异步处理。
- [重试](https://cloudflaredoc.ubitools.com/agents/runtime/execution/retries/index.md): 使用 Agents SDK 内置重试系统，以指数退避与 jitter 重试失败操作。
- [运行 Workflows](https://cloudflaredoc.ubitools.com/agents/runtime/execution/run-workflows/index.md): 将 Cloudflare Workflows 与 Agent 集成，实现持久的多步骤后台处理与故障恢复。
- [调度任务](https://cloudflaredoc.ubitools.com/agents/runtime/execution/schedule-tasks/index.md): 在 Agent 上调度延迟、指定日期、cron 与间隔任务，由 SQLite 持久化执行。
- [子 Agent](https://cloudflaredoc.ubitools.com/agents/runtime/execution/sub-agents/index.md): 使用 subAgent()、abortSubAgent() 与 deleteSubAgent() 生成具有隔离存储与带类型 RPC 的子 Agent。
- [Agent 类内部机制](https://cloudflaredoc.ubitools.com/agents/runtime/lifecycle/agent-class/index.md): 了解 Agent 类如何扩展 Durable Objects 以提供状态、WebSocket、调度和 RPC。
- [可调用方法](https://cloudflaredoc.ubitools.com/agents/runtime/lifecycle/callable-methods/index.md): 使用 @callable() 装饰器通过 WebSocket RPC 向外部客户端暴露 Agent 方法。
- [获取当前 Agent](https://cloudflaredoc.ubitools.com/agents/runtime/lifecycle/get-current-agent/index.md): 使用 Agents SDK 中的 getCurrentAgent() 从外部工具函数访问当前 Agent 上下文。
- [会话](https://cloudflaredoc.ubitools.com/agents/runtime/lifecycle/sessions/index.md): 持久化对话存储，支持树形消息、上下文块、压缩、全文搜索与 AI 可控工具。
- [存储与同步状态](https://cloudflaredoc.ubitools.com/agents/runtime/lifecycle/state/index.md): 使用 setState、SQL 存储和双向更新在客户端间持久化并同步 Agent 状态。
- [配置](https://cloudflaredoc.ubitools.com/agents/runtime/operations/configuration/index.md): 为使用 Agents SDK 的项目配置 Wrangler 绑定、环境变量和类型生成。
- [跨域身份验证](https://cloudflaredoc.ubitools.com/agents/runtime/operations/cross-domain-authentication/index.md): 使用签名 token 对跨域 WebSocket 连接到 Cloudflare Agents 进行身份验证。
- [可观测性](https://cloudflaredoc.ubitools.com/agents/runtime/operations/observability/index.md): 通过 diagnostics channel 订阅结构化 Agent 事件，包括 RPC 调用、状态变更、调度、Workflows 和 MCP 连接。
- [使用 AI 模型](https://cloudflaredoc.ubitools.com/agents/runtime/operations/using-ai-models/index.md): 在 Cloudflare Agents 中调用 Workers AI、OpenAI、Anthropic、Google Gemini 或任意提供商的 AI 模型。

## tools

- [AI Search 概览](https://cloudflaredoc.ubitools.com/agents/tools/ai-search/index.md): 为 Agent 提供 Cloudflare AI Search 检索能力。
- [浏览器 Tool](https://cloudflaredoc.ubitools.com/agents/tools/browser/index.md): 为 Agent 提供完整的 Chrome DevTools Protocol 访问，用于检查页面、抓取数据和截取屏幕截图（Browser Run）。
- [Code Mode（代码模式）](https://cloudflaredoc.ubitools.com/agents/tools/codemode/index.md): 使用 Code Mode 让模型通过编写代码作为紧凑、可执行的计划来发现并编排工具。
- [AI SDK 集成](https://cloudflaredoc.ubitools.com/agents/tools/codemode/ai-sdk/index.md): 通过 createCodeTool()、命名空间提供方或 ToolSetConnector 将 AI SDK 工具与 Code Mode 一起用于持久执行。
- [Code Mode API 参考](https://cloudflaredoc.ubitools.com/agents/tools/codemode/api-reference/index.md): Code Mode 导出的公共类、函数、选项、运行时方法、连接器钩子与结果类型的参考。
- [浏览器集成](https://cloudflaredoc.ubitools.com/agents/tools/codemode/browser/index.md): 使用 Code Mode iframe executor 与 Agent 聊天 UI，对 browser 自有 tool 运行模型生成的代码。
- [创建持久 Code Mode 运行时](https://cloudflaredoc.ubitools.com/agents/tools/codemode/durable-runtime/index.md): 创建带连接器、直接宿主 API、持久审批、回滚、执行历史与可复用代码片段的 Code Mode 运行时。
- [Code Mode 工作原理](https://cloudflaredoc.ubitools.com/agents/tools/codemode/how-it-works/index.md): 了解 Code Mode 如何隔离生成的代码，并使审批、重放、回滚与复用具备持久性。
- [将 MCP tool 与 Code Mode 一起使用](https://cloudflaredoc.ubitools.com/agents/tools/codemode/mcp/index.md): 通过持久 Code Mode 运行时将现有 MCP 连接中的工具暴露给模型。
- [将 OpenAPI 服务与 Code Mode 结合使用](https://cloudflaredoc.ubitools.com/agents/tools/codemode/openapi/index.md): 将 OpenAPI 操作转为带类型的 Code Mode 连接器方法，同时把身份验证保留在宿主 Worker。
- [将 Code Mode 与 TanStack AI 结合使用](https://cloudflaredoc.ubitools.com/agents/tools/codemode/tanstack-ai/index.md): 使用 `@cloudflare/codemode/tanstack-ai` 通过 `chat()` 暴露带命名空间的 TanStack AI 服务端工具。
- [MCP 工具](https://cloudflaredoc.ubitools.com/agents/tools/mcp/index.md): 将 Agent 连接到外部 Model Context Protocol 服务器，并在模型调用中使用其工具。
- [Agentic 支付](https://cloudflaredoc.ubitools.com/agents/tools/payments/index.md): 使用 MPP 和 x402 等支付协议，让 AI Agent 通过 Cloudflare Agents SDK 以编程方式支付服务。
- [Machine Payments Protocol（MPP）概览](https://cloudflaredoc.ubitools.com/agents/tools/payments/mpp/index.md): 使用 MPP 让 Agent 以编程方式发起和接收机器对机器支付。
- [对 HTTP 内容收费](https://cloudflaredoc.ubitools.com/agents/tools/payments/mpp-charge-for-http-content/index.md): 在 Cloudflare Workers 上使用 mpp-proxy 模板，通过 MPP 支付为 HTTP 端点设门禁。
- [x402 支付协议](https://cloudflaredoc.ubitools.com/agents/tools/payments/x402/index.md): 在 Cloudflare Workers 和 Agents SDK 上使用 x402 HTTP 支付协议接受和发起机器对机器支付。
- [对 HTTP 内容收费](https://cloudflaredoc.ubitools.com/agents/tools/payments/x402/charge-for-http-content/index.md): 使用 Cloudflare Worker 代理，通过 x402 支付为 HTTP 端点设门禁。
- [对 MCP 工具收费](https://cloudflaredoc.ubitools.com/agents/tools/payments/x402/charge-for-mcp-tools/index.md): 在 MCP 服务器中使用 paidTool 按工具调用收费。
- [从 Agents SDK 支付](https://cloudflaredoc.ubitools.com/agents/tools/payments/x402/pay-from-agents-sdk/index.md): 使用 withX402Client 从 Cloudflare Agent 支付资源费用。
- [从编码工具支付](https://cloudflaredoc.ubitools.com/agents/tools/payments/x402/pay-with-tool-plugins/index.md): 为 OpenCode 与 Claude Code 添加 x402 支付处理。
- [沙箱](https://cloudflaredoc.ubitools.com/agents/tools/sandbox/index.md): 为 Agent 提供隔离的 Linux 环境，用于运行代码、管理文件和执行命令。