--- description: Reference for the Agent base class, lifecycle hooks, SQL storage, and error handling in the Agents SDK. title: Agents API image: https://developers.cloudflare.com/og-docs.png --- [Skip to content](#main-content) > Documentation Index > Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt > Use this file to discover all available pages before exploring further. # Agents API Last updated Aug 25, 2026|Copy as Markdown|[View as Markdown](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/agents-api/index.md)|[Agent setup](https://4f1c5cd2.previews.developers.cloudflare.com/agent-setup/) This page provides an overview of the Agents SDK. For detailed documentation on each feature, refer to the linked reference pages. ## Overview The Agents SDK provides two main APIs: | API | Description | | --------------------------- | -------------------------------------------------------------------------------- | | **Server-side** Agent class | Encapsulates agent logic: connections, state, methods, AI models, error handling | | **Client-side** SDK | AgentClient, useAgent, and useAgentChat for connecting from browsers | Note Agents require [Cloudflare Durable Objects](https://4f1c5cd2.previews.developers.cloudflare.com/durable-objects/). Refer to [Configuration](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/operations/configuration/) to learn how to add the required bindings. ## Agent class An Agent is a class that extends the base `Agent` class: ```ts import { Agent, routeAgentRequest } from "agents"; export class MyAgent extends Agent { // Your agent logic } export default { async fetch(request: Request, env: Env) { return ( (await routeAgentRequest(request, env)) || new Response("Not found", { status: 404 }) ); }, } satisfies ExportedHandler; ``` Each Agent can have millions of instances. Each instance is a separate micro-server that runs independently, allowing horizontal scaling. Instances are addressed by a unique identifier (user ID, email, ticket number, etc.). Note An instance of an Agent is globally unique: given the same name (or ID), you will always get the same instance of an agent. This allows you to avoid synchronizing state across requests: if an Agent instance represents a specific user, team, channel or other entity, you can use the Agent instance to store state for that entity. There is no need to set up a centralized session store. If the client disconnects, you can always route the client back to the exact same Agent and pick up where they left off. ## Lifecycle flowchart TD A["onStart
(instance wakes up)"] --> B["onRequest
(HTTP)"] A --> C["onConnect
(WebSocket)"] A --> D["onEmail"] C --> E["onMessage ↔ send()
onError (on failure)"] E --> F["onClose"] | Method | When it runs | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onStart(props?) | When the instance starts, or wakes from hibernation. Receives optional [initialization props](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/routing/#props) passed via getAgentByName or routeAgentRequest. | | onRequest(request) | For each HTTP request to the instance | | onConnect(connection, ctx) | When a WebSocket connection is established | | onMessage(connection, message) | For each WebSocket message received | | onError(connection, error) | When a WebSocket error occurs | | onClose(connection, code, reason, wasClean) | When a WebSocket connection closes | | onEmail(email) | When an email is routed to the instance | | onStateChanged(state, source) | When state changes (from server or client) | ## Core properties | Property | Type | Description | | ---------- | ---------------- | -------------------------------------- | | this.env | Env | Environment variables and bindings | | this.ctx | ExecutionContext | Execution context for the request | | this.state | State | Current persisted state | | this.sql | Function | Execute SQL queries on embedded SQLite | ## Server-side API reference | Feature | Methods | Documentation | | ------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | **State** | setState(), onStateChanged(), initialState | [Store and sync state](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/lifecycle/state/) | | **Callable methods** | @callable() decorator | [Callable methods](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/lifecycle/callable-methods/) | | **Scheduling** | schedule(), scheduleEvery(), getScheduleById(), listSchedules() | [Schedule tasks](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/schedule-tasks/) | | **Durable execution** | runFiber(), startFiber(), stash(), onFiberRecovered(), keepAlive(), keepAliveWhile() | [Durable execution](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/durable-execution/) | | **Queue** | queue(), dequeue(), dequeueAll(), getQueue() | [Queue tasks](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/queue-tasks/) | | **WebSockets** | onConnect(), onMessage(), onClose(), broadcast() | [WebSockets](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/websockets/) | | **HTTP/SSE** | onRequest() | [HTTP and SSE](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/http-sse/) | | **Email** | onEmail(), replyToEmail() | [Email routing](https://4f1c5cd2.previews.developers.cloudflare.com/agents/communication-channels/email/) | | **Workflows** | runWorkflow(), waitForApproval() | [Run Workflows](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/run-workflows/) | | **MCP Client** | addMcpServer(), removeMcpServer(), getMcpServers() | [MCP Client API](https://4f1c5cd2.previews.developers.cloudflare.com/agents/model-context-protocol/apis/client-api/) | | **AI Models** | Workers AI, OpenAI, Anthropic bindings | [Using AI models](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/operations/using-ai-models/) | | **Protocol messages** | shouldSendProtocolMessages(), isConnectionProtocolEnabled() | [Protocol messages](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/protocol-messages/) | | **Context** | getCurrentAgent() | [getCurrentAgent()](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/lifecycle/get-current-agent/) | | **Tracing** | wrapAISDK() | [Tracing](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/operations/observability/tracing/) | | **Diagnostics channels** | subscribe(), diagnostics channels | [Diagnostics channels](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/operations/observability/diagnostics-channels/) | | **Sub-agents** | subAgent(), abortSubAgent(), deleteSubAgent() | [Sub-agents](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/sub-agents/) | | **Agents as tools** | runAgentTool(), clearAgentToolRuns(), hasAgentToolRun() | [Agents as tools](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/agent-tools/) | | **Agent Skills** | skills registry, bundled skill sources, script runners | [Agent Skills](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/agent-skills/) | | **Sessions** | Session.create(), context blocks, compaction, search | [Sessions](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/lifecycle/sessions/) | | **Think** | Think base class, workspace tools, lifecycle hooks, extensions | [Think](https://4f1c5cd2.previews.developers.cloudflare.com/agents/harnesses/think/) | | **Chat SDK** | createChatSdkState(), ChatSdkStateAgent | [Chat SDK](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/chat-sdk/) | ## SQL API Each Agent instance has an embedded SQLite database accessed via `this.sql`: ```ts // Create tables this.sql`CREATE TABLE IF NOT EXISTS users (id TEXT PRIMARY KEY, name TEXT)`; // Insert data this.sql`INSERT INTO users (id, name) VALUES (${id}, ${name})`; // Query data const users = this.sql`SELECT * FROM users WHERE id = ${id}`; ``` For state that needs to sync with clients, use the [State API](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/lifecycle/state/) instead. ## Client-side API reference | Feature | Methods | Documentation | | --------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **WebSocket client** | AgentClient | [Client SDK](https://4f1c5cd2.previews.developers.cloudflare.com/agents/communication-channels/chat/client-sdk/) | | **HTTP client** | agentFetch() | [Client SDK](https://4f1c5cd2.previews.developers.cloudflare.com/agents/communication-channels/chat/client-sdk/#http-requests-with-agentfetch) | | **React hook** | useAgent() | [Client SDK](https://4f1c5cd2.previews.developers.cloudflare.com/agents/communication-channels/chat/client-sdk/#react) | | **Chat hook** | useAgentChat() | [Client SDK](https://4f1c5cd2.previews.developers.cloudflare.com/agents/communication-channels/chat/client-sdk/) | | **Agent tool events** | useAgentToolEvents() | [Agents as tools](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/execution/agent-tools/#render-child-timelines-in-react) | Module-level helper exports include `agentTool()` from `agents/agent-tools`, which converts a Think or `AIChatAgent` subclass into an AI SDK tool definition. ### Quick example ```ts import { useAgent } from "agents/react"; import type { MyAgent } from "./server"; function App() { const agent = useAgent({ agent: "my-agent", name: "user-123", }); // Call methods on the agent agent.stub.someMethod(); // Update state (syncs to server and all clients) agent.setState({ count: 1 }); } ``` ## Chat agents For AI chat applications, extend `AIChatAgent` instead of `Agent`: ```ts import { AIChatAgent } from "@cloudflare/ai-chat"; class ChatAgent extends AIChatAgent { async onChatMessage(onFinish) { // this.messages contains the conversation history // Return a streaming response } } ``` Features include: * Built-in message persistence * Automatic resumable streaming (reconnect mid-stream) * Works with `useAgentChat` React hook Refer to [Build a chat agent](https://4f1c5cd2.previews.developers.cloudflare.com/agents/examples/chat-agent/) for a complete tutorial. ## Routing Agents are accessed via URL patterns: ```txt https://your-worker.workers.dev/agents/:agent-name/:instance-name ``` Use `routeAgentRequest()` in your Worker to route requests: ```ts import { routeAgentRequest } from "agents"; export default { async fetch(request: Request, env: Env) { return ( routeAgentRequest(request, env) || new Response("Not found", { status: 404 }) ); }, } satisfies ExportedHandler; ``` Refer to [Routing](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/routing/) for custom paths, CORS, and instance naming patterns. ## Next steps ### [Quick start](https://4f1c5cd2.previews.developers.cloudflare.com/agents/getting-started/quick-start/) Build your first agent in about 10 minutes. ### [Configuration](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/operations/configuration/) Learn about wrangler.jsonc setup and deployment. ### [WebSockets](https://4f1c5cd2.previews.developers.cloudflare.com/agents/runtime/communication/websockets/) Real-time bidirectional communication with clients. ### [Build a chat agent](https://4f1c5cd2.previews.developers.cloudflare.com/agents/examples/chat-agent/) Build AI applications with AIChatAgent. Was this helpful? YesNo ## On this page [![](https://4f1c5cd2.previews.developers.cloudflare.com/_astro/logo.te5VL_aD.svg)Docs](https://4f1c5cd2.previews.developers.cloudflare.com/) ```json {"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/agents/runtime/agents-api/#page","headline":"Agents API · Cloudflare Agents docs","description":"Reference for the Agent base class, lifecycle hooks, SQL storage, and error handling in the Agents SDK.","url":"https://developers.cloudflare.com/agents/runtime/agents-api/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-25","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}} ```