# 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://developers.cloudflare.com/agents/`).
>
> For other Cloudflare products, see the [Cloudflare documentation directory](https://developers.cloudflare.com/llms.txt).

## Overview

- [Build Agents on Cloudflare](https://developers.cloudflare.com/agents/index.md): Build and host AI agents on Cloudflare. Start with the Pi harness, which runs a durable model loop with tools in a Durable Object, and add state, real-time connections, and scheduled tasks with the Agents SDK.

## Getting started

- [Add to existing project](https://developers.cloudflare.com/agents/getting-started/add-to-existing-project/index.md): Add the Agents SDK to an existing Cloudflare Workers project with state management and real-time connections.
- [Quick start](https://developers.cloudflare.com/agents/getting-started/quick-start/index.md): Build your first agent in 10 minutes — a counter with persistent state that syncs to a React frontend in real-time.
- [Testing your Agents](https://developers.cloudflare.com/agents/getting-started/testing-your-agent/index.md): Write and run tests for Cloudflare Agents using Vitest and the Workers test pool.

## Concepts

- [Agentic patterns](https://developers.cloudflare.com/agents/concepts/agentic-patterns/index.md): Implement common AI agent patterns like prompt chaining, routing, parallelization, and orchestrator-workers on Cloudflare.
- [Human-in-the-loop patterns](https://developers.cloudflare.com/agents/concepts/agentic-patterns/human-in-the-loop/index.md): Implement human-in-the-loop functionality using Workflow approvals, durable Code Mode approvals, and MCP elicitation.
- [Long-running agents](https://developers.cloudflare.com/agents/concepts/agentic-patterns/long-running-agents/index.md): Build agents that persist for days, weeks, or months — surviving restarts, waking on demand, and managing work that spans far longer than any single request.
- [Calling LLMs](https://developers.cloudflare.com/agents/concepts/calling-llms/index.md): Call large language models from within a stateful Cloudflare Agent with persistent context and autonomous scheduling.
- [Conversation state and memory](https://developers.cloudflare.com/agents/concepts/conversation-state-and-memory/index.md): How agents store and recall information, including read-only context, writable short-form memory, searchable knowledge, and on-demand skills.
- [Tools](https://developers.cloudflare.com/agents/concepts/tools/index.md): Understand how tools are exposed to models, where tools execute, and how MCP connects external tools to Cloudflare Agents.
- [What are agents?](https://developers.cloudflare.com/agents/concepts/what-are-agents/index.md): Understand what Agents are, how they differ from workflows and co-pilots, and when to use them.
- [Using Agents with Workflows](https://developers.cloudflare.com/agents/concepts/workflows/index.md): Integrate Cloudflare Workflows with Agents for durable, multi-step background processing with automatic retries.

## Communication channels

- [Autonomous responses](https://developers.cloudflare.com/agents/communication-channels/chat/autonomous-responses/index.md): Send server-initiated messages and trigger LLM responses from Cloudflare Agents without user action.
- [Chat agents](https://developers.cloudflare.com/agents/communication-channels/chat/chat-agents/index.md): Build AI chat interfaces with AIChatAgent and useAgentChat, including message persistence, streaming, and tool support.
- [Client SDK](https://developers.cloudflare.com/agents/communication-channels/chat/client-sdk/index.md): Connect to Cloudflare Agents from browsers or server runtimes using useAgent, AgentClient, and agentFetch.
- [Email](https://developers.cloudflare.com/agents/communication-channels/email/index.md): Connect agents to email so they can send outbound messages, process inbound mail, and handle follow-up replies.
- [Slack](https://developers.cloudflare.com/agents/communication-channels/slack/index.md): Connect agents to Slack workspaces so they can respond to direct messages, mentions, and threaded conversations.
- [Voice](https://developers.cloudflare.com/agents/communication-channels/voice/index.md): Build real-time voice agents with speech-to-text, text-to-speech, and conversation persistence over WebSocket.
- [Webhooks](https://developers.cloudflare.com/agents/communication-channels/webhooks/index.md): Receive and route webhook events from external services to dedicated Cloudflare Agent instances.
- [Push notifications](https://developers.cloudflare.com/agents/communication-channels/webhooks/push-notifications/index.md): Send browser push notifications from a Cloudflare Agent, even when the user has closed the tab.

## Tools

- [Tools](https://developers.cloudflare.com/agents/tools/index.md)
- [AI Search](https://developers.cloudflare.com/agents/tools/ai-search/index.md): Give agents retrieval capabilities with Cloudflare AI Search.
- [Browser](https://developers.cloudflare.com/agents/tools/browser/index.md): Give your agent a browser that remembers tabs, cookies, and logins between turns. Use it with Pi Durable, the AI SDK, or another harness.
- [Code Mode](https://developers.cloudflare.com/agents/tools/codemode/index.md): Use Code Mode to let models discover and compose tools by writing code as a compact, executable plan.
- [AI SDK integration](https://developers.cloudflare.com/agents/tools/codemode/ai-sdk/index.md): Use AI SDK tools with Code Mode through createCodeTool(), namespaced providers, or ToolSetConnector for durable execution.
- [Code Mode API reference](https://developers.cloudflare.com/agents/tools/codemode/api-reference/index.md): Reference the public classes, functions, options, runtime methods, connector hooks, and result types exported by Code Mode.
- [Browser integration](https://developers.cloudflare.com/agents/tools/codemode/browser/index.md): Run model-generated code against browser-owned tools with the Code Mode iframe executor and an Agent chat UI.
- [Create a durable Code Mode runtime](https://developers.cloudflare.com/agents/tools/codemode/durable-runtime/index.md): Create a Code Mode runtime with connectors, direct host APIs, durable approvals, rollback, execution history, and reusable snippets.
- [How Code Mode works](https://developers.cloudflare.com/agents/tools/codemode/how-it-works/index.md): Learn how Code Mode isolates generated code and makes approvals, replay, rollback, and reuse durable.
- [Use MCP tools with Code Mode](https://developers.cloudflare.com/agents/tools/codemode/mcp/index.md): Expose tools from an existing MCP connection to models through a durable Code Mode runtime.
- [Use an OpenAPI service with Code Mode](https://developers.cloudflare.com/agents/tools/codemode/openapi/index.md): Turn OpenAPI operations into typed Code Mode connector methods while keeping authentication in the host Worker.
- [Use Code Mode with TanStack AI](https://developers.cloudflare.com/agents/tools/codemode/tanstack-ai/index.md): Use @cloudflare/codemode/tanstack-ai to expose namespaced TanStack AI server tools through chat().
- [File system](https://developers.cloudflare.com/agents/tools/filesystem/index.md): Give an agent a virtual file system stored in its Durable Object, with file tools for the model and an optional JavaScript runtime.
- [MCP](https://developers.cloudflare.com/agents/tools/mcp/index.md): Connect agents to external Model Context Protocol servers and use their tools in model calls.
- [Agentic Payments](https://developers.cloudflare.com/agents/tools/payments/index.md): Let AI agents pay for services with x402 or Machine Payments Protocol (MPP) through Cloudflare's Agents SDK.
- [MPP (Machine Payments Protocol)](https://developers.cloudflare.com/agents/tools/payments/mpp/index.md): Accept and make payments using Machine Payments Protocol (MPP) with Cloudflare Workers and the Agents SDK.
- [Charge for HTTP content](https://developers.cloudflare.com/agents/tools/payments/mpp-charge-for-http-content/index.md): Gate HTTP endpoints with MPP payments using the mpp-proxy template on Cloudflare Workers.
- [Accept payments with MPP](https://developers.cloudflare.com/agents/tools/payments/mpp/accept-payments/index.md): Accept Machine Payments Protocol (MPP) payments from an origin, Cloudflare Worker route, or Model Context Protocol (MCP) tool.
- [Pay from the Agents SDK](https://developers.cloudflare.com/agents/tools/payments/mpp/pay-from-agents-sdk/index.md): Configure a Cloudflare Agent to pay HTTP services and Model Context Protocol (MCP) tools with Machine Payments Protocol (MPP).
- [x402](https://developers.cloudflare.com/agents/tools/payments/x402/index.md): Accept and make machine-to-machine payments using the x402 HTTP payment protocol on Cloudflare Workers and the Agents SDK.
- [Charge for HTTP content](https://developers.cloudflare.com/agents/tools/payments/x402/charge-for-http-content/index.md): Gate HTTP endpoints with x402 payments using a Cloudflare Worker proxy.
- [Charge for MCP tools](https://developers.cloudflare.com/agents/tools/payments/x402/charge-for-mcp-tools/index.md): Charge per tool call in an MCP server using paidTool.
- [Pay from Agents SDK](https://developers.cloudflare.com/agents/tools/payments/x402/pay-from-agents-sdk/index.md): Use withX402Client to pay for resources from a Cloudflare Agent.
- [Pay from coding tools](https://developers.cloudflare.com/agents/tools/payments/x402/pay-with-tool-plugins/index.md): Add x402 payment handling to OpenCode and Claude Code.
- [Sandbox](https://developers.cloudflare.com/agents/tools/sandbox/index.md): Give an agent a Linux sandbox to run shell commands, scripts, and tests.
- [Web fetch](https://developers.cloudflare.com/agents/tools/web-fetch/index.md): Give your agent a web fetch tool with document conversion, pagination, and request controls. Use Pi Durable, AI SDK, TanStack AI, or your own harness.
- [Web search](https://developers.cloudflare.com/agents/tools/web-search/index.md): Give your agent a web search tool backed by the Cloudflare Web Search API. Use Pi Durable, AI SDK, TanStack AI, or your own harness.

## Models

- [Models](https://developers.cloudflare.com/agents/models/index.md): Call Workers AI, AI Gateway catalog models, dynamic routes, and vendor models from the AI SDK or Pi AI with one createAI provider over the AI binding or an account id and API token.
- [AI SDK](https://developers.cloudflare.com/agents/models/ai-sdk/index.md): Use createAI from agents/models/ai-sdk to call Workers AI models, AI Gateway catalog models, dynamic routes, and vendor AI SDK models through the AI binding or an account id and API token.
- [Pi AI](https://developers.cloudflare.com/agents/models/pi-ai/index.md): Use createAI from agents/models/pi-ai to run Workers AI models, AI Gateway catalog models, dynamic routes, and Pi AI model objects through the AI binding or an account id and API token with Pi AI, Pi Durable, and the Pi harness.

## Harnesses

- [Harnesses](https://developers.cloudflare.com/agents/harnesses/index.md): Understand agent harnesses — the loop that controls planning, tool use, and response flow.
- [OpenCode](https://developers.cloudflare.com/agents/harnesses/opencode/index.md): Run OpenCode 2.0 in a plain Durable Object with the Agents SDK, Workers AI and AI Gateway models, bundled plugins, and durable sessions.
- [Pi](https://developers.cloudflare.com/agents/harnesses/pi/index.md): Run the Pi Durable harness on Cloudflare with the Agents SDK. PiHarness keeps your agent's work durable inside a Durable Object, even if it is interrupted mid-turn.
- [Extensions](https://developers.cloudflare.com/agents/harnesses/pi/extensions/index.md): Add tools, system prompt sections, and skills to a PiHarness with Pi Durable extensions.
- [Think](https://developers.cloudflare.com/agents/harnesses/think/index.md): Opinionated chat agent framework with built-in tools, persistent memory, lifecycle hooks, streaming, messengers, scheduled tasks, Workflows, and sub-agent RPC.
- [Actions](https://developers.cloudflare.com/agents/harnesses/think/actions/index.md): Server-side Think tools with idempotency, human approvals, authorization, and reply attachments.
- [Channels](https://developers.cloudflare.com/agents/harnesses/think/channels/index.md): Apply per-channel policy, select a channel on a turn, and deliver out-of-band notices across web, messenger, voice, and custom surfaces.
- [Client tools](https://developers.cloudflare.com/agents/harnesses/think/client-tools/index.md): Browser-side tools, approval flows, auto-continuation, message concurrency, and multi-tab broadcast for Think agents.
- [Configuration](https://developers.cloudflare.com/agents/harnesses/think/configuration/index.md): Configuration overrides, dynamic runtime configuration, Session integration, and package exports for the Think chat agent framework.
- [Getting started](https://developers.cloudflare.com/agents/harnesses/think/getting-started/index.md): Build a Think chat agent with persistent memory, built-in file tools, custom tools, and streaming, step by step.
- [Lifecycle hooks](https://developers.cloudflare.com/agents/harnesses/think/lifecycle-hooks/index.md): Hooks at each stage of a Think chat turn — beforeTurn, beforeStep, beforeToolCall, afterToolCall, onStepFinish, onChunk, onChatResponse, and onChatError.
- [Messengers](https://developers.cloudflare.com/agents/harnesses/think/messengers/index.md): Receive and reply to Chat SDK messenger webhooks directly from a Think agent, including Telegram setup, routing, conversation targets, and recovery.
- [Programmatic submissions](https://developers.cloudflare.com/agents/harnesses/think/programmatic-submissions/index.md): Durably accept a Think turn with submitMessages() for webhooks and RPC callers, with idempotent retry, status inspection, and cancellation.
- [Durable recovery](https://developers.cloudflare.com/agents/harnesses/think/recovery/index.md): Bounded chat recovery, the stream-stall watchdog, repairing interrupted tool calls, and stability detection for Think agents.
- [Scheduled tasks](https://developers.cloudflare.com/agents/harnesses/think/scheduled-tasks/index.md): Declare recurring, timezone-aware Think turns and deterministic handlers with getScheduledTasks() and a typed scheduling DSL.
- [Sub-agent RPC and programmatic turns](https://developers.cloudflare.com/agents/harnesses/think/sub-agents/index.md): Stream Think turns through a child agent with chat(), and trigger turns programmatically with saveMessages(), continueLastTurn(), and abort.
- [Tools](https://developers.cloudflare.com/agents/harnesses/think/tools/index.md): Built-in workspace tools, custom tools, approvals, MCP tools, code execution, browser tools, and extensions for Think agents.
- [Workflows](https://developers.cloudflare.com/agents/harnesses/think/workflows/index.md): Run a durable model-driven reasoning step inside a Cloudflare Workflow with ThinkWorkflow and step.prompt(), including structured output and timeouts.

## Runtime

- [Agents API](https://developers.cloudflare.com/agents/runtime/agents-api/index.md): Reference for the Agent base class, lifecycle hooks, SQL storage, and error handling in the Agents SDK.
- [Chat SDK](https://developers.cloudflare.com/agents/runtime/communication/chat-sdk/index.md): Integrate Chat SDK with Agents, including durable state for subscriptions, locks, queues, and message history.
- [HTTP and Server-Sent Events](https://developers.cloudflare.com/agents/runtime/communication/http-sse/index.md): Handle HTTP requests and stream responses with Server-Sent Events (SSE) from Cloudflare Agents.
- [Protocol messages](https://developers.cloudflare.com/agents/runtime/communication/protocol-messages/index.md): Control the identity, state, and MCP protocol messages sent to WebSocket clients on Agent connect.
- [Readonly connections](https://developers.cloudflare.com/agents/runtime/communication/readonly-connections/index.md): Restrict WebSocket clients to view-only access so they receive state updates without modifying Agent state.
- [Routing](https://developers.cloudflare.com/agents/runtime/communication/routing/index.md): Route HTTP and WebSocket requests to Agents SDK instances using routeAgentRequest() and getAgentByName().
- [WebSockets](https://developers.cloudflare.com/agents/runtime/communication/websockets/index.md): Handle real-time WebSocket connections, messages, broadcasts, and lifecycle hooks in the Agents SDK.
- [Agent Skills](https://developers.cloudflare.com/agents/runtime/execution/agent-skills/index.md): Give an agent a catalog of on-demand instructions, resources, and scripts with agents/skills, activated by the model only when a task matches.
- [Agents as tools](https://developers.cloudflare.com/agents/runtime/execution/agent-tools/index.md): Run Think and AIChatAgent sub-agents as retained, streaming tools from a parent agent.
- [Durable execution with fibers](https://developers.cloudflare.com/agents/runtime/execution/durable-execution/index.md): Run work that survives Durable Object eviction with runFiber(), startFiber(), keepAlive(), and crash recovery.
- [Queue tasks](https://developers.cloudflare.com/agents/runtime/execution/queue-tasks/index.md): Add background tasks to a built-in FIFO queue for asynchronous processing within Cloudflare Agents.
- [Retries](https://developers.cloudflare.com/agents/runtime/execution/retries/index.md): Retry failed operations with exponential backoff and jitter using the built-in retry system in the Agents SDK.
- [Run Workflows](https://developers.cloudflare.com/agents/runtime/execution/run-workflows/index.md): Integrate Cloudflare Workflows with Agents for durable, multi-step background processing and failure recovery.
- [Schedule tasks](https://developers.cloudflare.com/agents/runtime/execution/schedule-tasks/index.md): Schedule delayed, date-based, cron, and interval tasks on Agents with persistent SQLite-backed execution.
- [Sub-agents](https://developers.cloudflare.com/agents/runtime/execution/sub-agents/index.md): Spawn child agents with isolated storage and typed RPC using subAgent(), abortSubAgent(), and deleteSubAgent().
- [Agent class internals](https://developers.cloudflare.com/agents/runtime/lifecycle/agent-class/index.md): Explore how the Agent class extends Durable Objects to provide state, WebSockets, scheduling, and RPC.
- [Callable methods](https://developers.cloudflare.com/agents/runtime/lifecycle/callable-methods/index.md): Expose Agent methods to external clients over WebSocket RPC using the @callable() decorator.
- [getCurrentAgent()](https://developers.cloudflare.com/agents/runtime/lifecycle/get-current-agent/index.md): Access the current Agent context from external utility functions using getCurrentAgent() in the Agents SDK.
- [Sessions](https://developers.cloudflare.com/agents/runtime/lifecycle/sessions/index.md): Persistent conversation storage with tree-structured messages, context blocks, compaction, full-text search, and AI-controllable tools.
- [Store and sync state](https://developers.cloudflare.com/agents/runtime/lifecycle/state/index.md): Persist and sync Agent state across clients in real time using setState, SQL storage, and bidirectional updates.
- [Configuration](https://developers.cloudflare.com/agents/runtime/operations/configuration/index.md): Configure Wrangler bindings, environment variables, and type generation for a project using the Agents SDK.
- [Cross-domain authentication](https://developers.cloudflare.com/agents/runtime/operations/cross-domain-authentication/index.md): Authenticate WebSocket connections to Cloudflare Agents across domains using signed tokens.
- [Diagnostics channels](https://developers.cloudflare.com/agents/runtime/operations/observability/diagnostics-channels/index.md): Subscribe to structured agent events for RPC calls, state changes, schedules, workflows, and MCP connections.
- [Tracing](https://developers.cloudflare.com/agents/runtime/operations/observability/tracing/index.md): Trace model calls, tool runs, and approvals with Workers traces.
- [Using AI Models](https://developers.cloudflare.com/agents/runtime/operations/using-ai-models/index.md): Call AI models from Workers AI, OpenAI, Anthropic, Google Gemini, or any provider within Cloudflare Agents.

## Examples

- [Browser agent](https://developers.cloudflare.com/agents/examples/browser-agent/index.md): Build an agent that uses Browser Run tools to inspect pages, capture screenshots, scrape rendered content, and debug frontend issues.
- [Chat agent](https://developers.cloudflare.com/agents/examples/chat-agent/index.md): Build a streaming AI chat agent with tools using Workers AI — no API keys required.
- [Email agent](https://developers.cloudflare.com/agents/examples/email-agent/index.md): Build an agent that sends, receives, routes, and replies to email using Cloudflare Email Service and the Agents SDK.
- [Slack agent](https://developers.cloudflare.com/agents/examples/slack-agent/index.md): Build and deploy an AI-powered Slack bot on Cloudflare Workers using the Agents SDK.
- [Voice agent](https://developers.cloudflare.com/agents/examples/voice-agent/index.md): Build a real-time voice agent with speech-to-text, LLM processing, and text-to-speech on Cloudflare Workers.

## Model Context Protocol (MCP)

- [Model Context Protocol (MCP)](https://developers.cloudflare.com/agents/model-context-protocol/index.md): Build and deploy remote MCP servers on Cloudflare to connect AI agents with external tools and services.
- [McpAgent](https://developers.cloudflare.com/agents/model-context-protocol/apis/agent-api/index.md): Reference the deprecated, feature-frozen McpAgent class while migrating existing stateful MCP servers to stateless handlers.
- [McpClient](https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/index.md): Connect Agents to external MCP servers to use their tools, resources, and prompts over the Model Context Protocol.
- [MCP handler APIs](https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/index.md): Create stateless or legacy MCP server handlers for Cloudflare Workers with the Agents SDK.
- [MCP server portals](https://developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/mcp-portals/index.md): Centralize multiple MCP servers onto a single endpoint and customize the tools, prompts, and resources available to users.
- [Cloudflare's own MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/index.md): Connect to Cloudflare's managed remote MCP servers to read configurations, manage services, and automate actions across your account.
- [Cloudflare Community MCP Server](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/community-mcp-server/index.md): Learn how to use the Cloudflare Community MCP server to search topics, read posts, and filter content.
- [Code Mode MCP server patterns](https://developers.cloudflare.com/agents/model-context-protocol/codemode/index.md): Understand single-code-tool and search-and-execute patterns for exposing tools and large APIs through MCP.
- [Build a single-tool Code Mode MCP server](https://developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-mcp-server/index.md): Replace an MCP server's individual tools with one sandboxed Code Mode tool on Cloudflare Workers.
- [Build a search and execute MCP server](https://developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-openapi-mcp-server/index.md): Create Code Mode search and execute MCP tools from an OpenAPI document while keeping credentials in the host Worker.
- [Connect to an MCP server](https://developers.cloudflare.com/agents/model-context-protocol/guides/connect-mcp-client/index.md): Create a Cloudflare Agent that connects to an external MCP server and uses its tools.
- [Migrate to MCP SDK v2](https://developers.cloudflare.com/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/index.md): Migrate Agents SDK MCP servers and clients to the split MCP TypeScript SDK v2 packages while retaining legacy compatibility.
- [Handle OAuth with MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/guides/oauth-mcp-client/index.md): Implement OAuth authentication flows in Cloudflare Agents to connect to protected MCP servers.
- [Build a Remote MCP server](https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/index.md): Deploy a remote MCP server on Cloudflare with optional authentication using Streamable HTTP transport.
- [Securing MCP servers](https://developers.cloudflare.com/agents/model-context-protocol/guides/securing-mcp-server/index.md): Secure your MCP servers with OAuth 2.1, token validation, and scope-based access control on Cloudflare.
- [Test a Remote MCP Server](https://developers.cloudflare.com/agents/model-context-protocol/guides/test-remote-mcp-server/index.md): Test your remote MCP server using the MCP Inspector and compatible MCP clients.
- [Authorization](https://developers.cloudflare.com/agents/model-context-protocol/protocol/authorization/index.md): Add OAuth 2.1 authorization to your MCP server using Cloudflare Access, third-party providers, or your own identity system.
- [MCP governance](https://developers.cloudflare.com/agents/model-context-protocol/protocol/governance/index.md): Control which MCP servers your organization uses and enforce access policies with Cloudflare Access.
- [Tools](https://developers.cloudflare.com/agents/model-context-protocol/protocol/tools/index.md): Define, register, and manage MCP tools that expose server-side functions for AI agents to call.
- [Transport](https://developers.cloudflare.com/agents/model-context-protocol/protocol/transport/index.md): Configure Streamable HTTP transport for remote MCP servers built with the Agents SDK.

## Platform

- [Limits](https://developers.cloudflare.com/agents/platform/limits/index.md): Understand the concurrency, storage, and compute time limits that apply to Cloudflare Agents.