Build a Durable AI Agent

Last updated Oct 12, 2026 In this guide, you will build an AI agent that researches GitHub repositories. Give it a task like "Compare open-source LLM projects" and it will:

1. Search GitHub for relevant repositories
2. Fetch details about each one (stars, forks, activity)
3. Analyze and compare them
4. Return a recommendation

Each LLM call and tool call becomes a step — a self-contained, individually retryable unit of work. If any step fails, Workflows retries it automatically. If the entire Workflow crashes mid-task, it resumes from the last successful step.

This guide uses the Agents SDK with Workflows for real-time progress updates and the Anthropic SDK for LLM calls. The same patterns apply to any LLM SDK (OpenAI, Google AI, Mistral, etc.).

Quick start

If you want to skip the steps and pull down the complete agent, utilizing AI Gateway, run the following command:

npm create cloudflare@latest -- --template cloudflare/docs-examples/workflows/durableAgent

Use this option if you are familiar with Cloudflare Workflows or want to explore the code first.

Follow the steps below to learn how to build a durable AI agent from scratch.

Prerequisites

1. Sign up for a Cloudflare account ↗︎.
2. Install Node.js ↗︎.

<details>

<summary>

Node.js version manager

</summary>

Use <a href="https://viteplus.dev/guide/env">Vite+ (<code>vp env</code>) ↗︎</a> to install and manage Node.js versions.

For supported Node.js versions, refer to the <a href="https://developers.cloudflare.com/workers/wrangler/install-and-update/#install-wrangler">Wrangler system requirements</a>.

</details>

You will also need an Anthropic API key ↗︎ for LLM calls. New accounts include free credits.

1. Create a new Worker project

1. Create a new Worker project by running the following command:npmyarnpnpm

   npm create cloudflare@latest -- durable-ai-agent
   ```

yarn create cloudflare durable-ai-agent ```

   pnpm create cloudflare@latest durable-ai-agent
   ```

For setup, select the following options:
   - For *What would you like to start with?*, choose `Hello World example`.
   - For *Which template would you like to use?*, choose `Worker only`.
   - For *Which language do you want to use?*, choose `TypeScript`.
   - For *Do you want to use git for version control?*, choose `Yes`.
   - For *Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?*, choose `Yes`.
   - For *Do you want to deploy your application?*, choose `No` (we will be making some changes before deploying).
2. Move into your project:

```sh
   cd durable-ai-agent
   ```

3. Install dependencies:

```sh
   npm install agents @anthropic-ai/sdk
   ```

## 2. Define your tools

Tools are functions the LLM can call to interact with external systems. You define the schema (what inputs the tool accepts) and the implementation (what it does). The LLM decides when to use each tool based on the task.

1. Create `src/tools.ts` with two complementary tools:

*src/tools.tsts*

```ts
   export interface SearchReposInput {
    query: string;
    limit?: number;
   }

export interface GetRepoInput {
    owner: string;
    repo: string;
   }

interface GitHubSearchResponse {
    items: Array<{ full_name: string; stargazers_count: number }>;
   }

interface GitHubRepoResponse {
    full_name: string;
    description: string;
    stargazers_count: number;
    forks_count: number;
    open_issues_count: number;
    language: string;
    license: { name: string } | null;
    updated_at: string;
   }

export const searchReposTool = {
    name: "search_repos" as const,
    description:
        "Search GitHub repositories by keyword. Returns top results. Use get_repo for details.",
    input_schema: {
        type: "object" as const,
        properties: {
            query: {
                type: "string",
                description: "Search query (e.g., 'typescript orm')",
            },
            limit: { type: "number", description: "Max results (default 5)" },
        },
        required: ["query"],
    },
    run: async (input: SearchReposInput): Promise<string> => {
        const response = await fetch(
            `https://api.github.com/search/repositories?q=${encodeURIComponent(input.query)}&sort=stars&per_page=${input.limit ?? 5}`,
            {
                headers: {
                    Accept: "application/vnd.github+json",
                    "User-Agent": "DurableAgent/1.0",
                },
            },
        );
        if (!response.ok) return `Search failed: ${response.status}`;
        const data = await response.json<GitHubSearchResponse>();
        return JSON.stringify(
            data.items.map((r) => ({
                name: r.full_name,
                stars: r.stargazers_count,
            })),
        );
    },
   };

export const getRepoTool = {
    name: "get_repo" as const,
    description:
        "Get detailed info about a GitHub repository including stars, forks, and description.",
    input_schema: {
        type: "object" as const,
        properties: {
            owner: {
                type: "string",
                description: "Repository owner (e.g., 'cloudflare')",
            },
            repo: {
                type: "string",
                description: "Repository name (e.g., 'workers-sdk')",
            },
        },
        required: ["owner", "repo"],
    },
    run: async (input: GetRepoInput): Promise<string> => {
        const response = await fetch(
            `https://api.github.com/repos/${input.owner}/${input.repo}`,
            {
                headers: {
                    Accept: "application/vnd.github+json",
                    "User-Agent": "DurableAgent/1.0",
                },
            },
        );
        if (!response.ok) return `Repo not found: ${input.owner}/${input.repo}`;
        const data = await response.json<GitHubRepoResponse>();
        return JSON.stringify({
            name: data.full_name,
            description: data.description,
            stars: data.stargazers_count,
            forks: data.forks_count,
            issues: data.open_issues_count,
            language: data.language,
            license: data.license?.name ?? "None",
            updated: data.updated_at,
        });
    },
   };

export const tools = [searchReposTool, getRepoTool];
   ```

These tools complement each other: `search_repos` finds repositories, and `get_repo` fetches details about specific ones.

## 3. Write your Workflow

The `AgentWorkflow` class from the Agents SDK extends Cloudflare Workflows with bidirectional Agent communication. Your Workflow can report progress, broadcast to WebSocket clients, and call Agent methods via RPC.

- The [`step`](https://developers.cloudflare.com/workflows/build/workers-api/#step) object provides methods to define durable steps.
- `step.do(name, callback)` executes code and persists the result. If the Workflow is interrupted, it resumes from the last successful step.
- `this.reportProgress()` sends progress updates to the Agent (non-durable).
- `this.broadcastToClients()` sends messages to all connected WebSocket clients (non-durable).

For a gentler introduction, refer to [Build your first Workflow](https://developers.cloudflare.com/workflows/get-started/guide/).

Create `src/workflow.ts`:

*src/workflow.tsts*

```ts
import { AgentWorkflow } from "agents/workflows";
import type { AgentWorkflowEvent, AgentWorkflowStep } from "agents/workflows";
import Anthropic from "@anthropic-ai/sdk";
import {
    tools,
    searchReposTool,
    getRepoTool,
    type SearchReposInput,
    type GetRepoInput,
} from "./tools";
import type { ResearchAgent } from "./agent";

type Params = { task: string };

export class ResearchWorkflow extends AgentWorkflow<ResearchAgent, Params> {
    async run(event: AgentWorkflowEvent<Params>, step: AgentWorkflowStep) {
        const client = new Anthropic({ apiKey: this.env.ANTHROPIC_API_KEY });

const messages: Anthropic.MessageParam[] = [
            { role: "user", content: event.payload.task },
        ];

const toolDefinitions = tools.map(({ run, ...rest }) => rest);

// Durable agent loop - each turn is checkpointed
        for (let turn = 0; turn < 10; turn++) {
            // Report progress to Agent and connected clients
            await this.reportProgress({
                step: `llm-turn-${turn}`,
                status: "running",
                percent: turn / 10,
                message: `Processing turn ${turn + 1}...`,
            });

const response = (await step.do(
                `llm-turn-${turn}`,
                { retries: { limit: 3, delay: "10 seconds", backoff: "exponential" } },
                async () => {
                    const msg = await client.messages.create({
                        model: "claude-sonnet-4-5-20250929",
                        max_tokens: 4096,
                        tools: toolDefinitions,
                        messages,
                    });
                    // Serialize for Workflow state
                    return JSON.parse(JSON.stringify(msg));
                },
            )) as Anthropic.Message;

if (!response || !response.content) continue;

messages.push({ role: "assistant", content: response.content });

if (response.stop_reason === "end_turn") {
                const textBlock = response.content.find(
                    (b): b is Anthropic.TextBlock => b.type === "text",
                );
                const result = {
                    status: "complete",
                    turns: turn + 1,
                    result: textBlock?.text ?? null,
                };

// Report completion (durable)
                await step.reportComplete(result);
                return result;
            }

const toolResults: Anthropic.ToolResultBlockParam[] = [];

for (const block of response.content) {
                if (block.type !== "tool_use") continue;

// Broadcast tool execution to clients
                this.broadcastToClients({
                    type: "tool_call",
                    tool: block.name,
                    turn,
                });

const result = await step.do(
                    `tool-${turn}-${block.id}`,
                    { retries: { limit: 2, delay: "5 seconds" } },
                    async () => {
                        switch (block.name) {
                            case "search_repos":
                                return searchReposTool.run(block.input as SearchReposInput);
                            case "get_repo":
                                return getRepoTool.run(block.input as GetRepoInput);
                            default:
                                return `Unknown tool: ${block.name}`;
                        }
                    },
                );

toolResults.push({
                    type: "tool_result",
                    tool_use_id: block.id,
                    content: result,
                });
            }

messages.push({ role: "user", content: toolResults });
        }

return { status: "max_turns_reached", turns: 10 };
    }
}

<details>

<summary>

Why separate steps for LLM and tools?

</summary>

Each <code>step.do()</code> creates a checkpoint. If your Workflow crashes or the Worker restarts:

• After LLM step: The response is persisted. On resume, it skips the LLM call and moves to tool execution.
• After tool step: The result is persisted. If a later tool fails, earlier tools do not re-run.