> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cloudflare/agents/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Cloudflare Agents

> Build AI agents that persist, think, and act on Cloudflare's global network

<img className="block" src="https://mintcdn.com/cloudflare-agents-18/NuQ3_fpUl5CHTraZ/images/hero-light.png?fit=max&auto=format&n=NuQ3_fpUl5CHTraZ&q=85&s=d54fb94a468a59b9a767ef614d90e5c3" alt="Cloudflare Agents Hero" width="2064" height="1104" data-path="images/hero-light.png" />

## What are Cloudflare Agents?

Agents are persistent, stateful execution environments for agentic workloads, powered by Cloudflare [Durable Objects](https://developers.cloudflare.com/durable-objects/). Each agent has its own state, storage, and lifecycle — with built-in support for real-time communication, scheduling, AI model calls, MCP, workflows, and more.

Agents hibernate when idle and wake on demand. You can run millions of them — one per user, per session, per game room — each costs nothing when inactive.

## Why use Agents?

<CardGroup cols={2}>
  <Card title="Persistent State" icon="database">
    State syncs to all connected clients automatically and survives restarts, deploys, and hibernation. Stored in SQLite.
  </Card>

  <Card title="Real-time Sync" icon="bolt">
    Built-in WebSocket support with real-time bidirectional communication and lifecycle hooks.
  </Card>

  <Card title="Global Network" icon="globe">
    Run on Cloudflare's edge network, close to your users, with sub-50ms latency worldwide.
  </Card>

  <Card title="Zero Cost When Idle" icon="moon">
    Agents hibernate when no clients are connected. Wake on demand. Pay only for what you use.
  </Card>
</CardGroup>

## Key Features

<AccordionGroup>
  <Accordion title="Callable Methods" icon="function">
    Type-safe RPC via the `@callable()` decorator. Call agent methods like they're local functions from your frontend.

    ```typescript theme={null}
    @callable()
    increment() {
      this.setState({ count: this.state.count + 1 });
      return this.state.count;
    }
    ```
  </Accordion>

  <Accordion title="AI Chat" icon="message-bot">
    Message persistence, resumable streaming, and server/client tool execution for building AI chat experiences.
  </Accordion>

  <Accordion title="Scheduling" icon="clock">
    One-time, recurring, and cron-based tasks. Run background jobs at scale.
  </Accordion>

  <Accordion title="MCP (Model Context Protocol)" icon="plug">
    Act as MCP servers or connect as MCP clients to expose tools and resources.
  </Accordion>

  <Accordion title="Workflows" icon="diagram-project">
    Durable multi-step tasks with human-in-the-loop approval.
  </Accordion>

  <Accordion title="Email" icon="envelope">
    Receive and respond to emails via Cloudflare Email Routing.
  </Accordion>

  <Accordion title="React Hooks" icon="react">
    `useAgent` and `useAgentChat` hooks for seamless frontend integration.
  </Accordion>
</AccordionGroup>

## Quick Example

A counter agent with persistent state, callable methods, and real-time sync:

<CodeGroup>
  ```typescript server.ts theme={null}
  import { Agent, routeAgentRequest, callable } from "agents";

  export type CounterState = { count: number };

  export class CounterAgent extends Agent<Env, CounterState> {
    initialState = { count: 0 };

    @callable()
    increment() {
      this.setState({ count: this.state.count + 1 });
      return this.state.count;
    }

    @callable()
    decrement() {
      this.setState({ count: this.state.count - 1 });
      return this.state.count;
    }
  }

  export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext) {
      return (
        (await routeAgentRequest(request, env)) ??
        new Response("Not found", { status: 404 })
      );
    }
  };
  ```

  ```tsx client.tsx theme={null}
  import { useAgent } from "agents/react";
  import { useState } from "react";
  import type { CounterAgent, CounterState } from "./server";

  function Counter() {
    const [count, setCount] = useState(0);

    const agent = useAgent<CounterAgent, CounterState>({
      agent: "CounterAgent",
      onStateUpdate: (state) => setCount(state.count)
    });

    return (
      <div>
        <span>{count}</span>
        <button onClick={() => agent.stub.increment()}>+</button>
        <button onClick={() => agent.stub.decrement()}>-</button>
      </div>
    );
  }
  ```
</CodeGroup>

<Note>
  State changes sync to all connected clients automatically. Call methods like they're local functions.
</Note>

## Get Started

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Build your first agent in 10 minutes with our step-by-step guide.
  </Card>

  <Card title="Add to Existing Project" icon="plus" href="/adding-to-existing-project">
    Integrate agents into your existing Cloudflare Workers application.
  </Card>
</CardGroup>

## Coming Soon

<CardGroup cols={3}>
  <Card title="Realtime Voice" icon="microphone">
    Voice agents with real-time audio processing
  </Card>

  <Card title="Web Browsing" icon="browser">
    Headless browser automation
  </Card>

  <Card title="Sandboxed Code" icon="shield-check">
    Safe execution of user-generated code
  </Card>
</CardGroup>