DOCSEARCHbyAlgolia
Submit Docs

Cloudflare Agents

repository·main·Indexed 26 days ago

https://github.com/cloudflare/agents

A framework for building persistent, stateful AI agents using Cloudflare Durable Objects. It provides built-in support for real-time communication, tool execution, scheduling, and long-running workflows. Key features include durable execution via Agent.runFiber(), automatic chat recovery for LLM streaming, and sub-agent patterns for isolated storage and multi-room conversation management.

Tokens
231.9K
Snippets
456
Records
1K
Agent score
89%

What's inside cloudflare-agents

  1. Overview of the Chat Shared Layer

    main
    The Chat Shared Layer provides the foundational streaming, persistence, and protocol primitives for the cf_agent_chat_* WebSocket protocol. It is designed to be consumed by both @cloudflare/ai-chat (the stable chat agent) and @cloudflare/think (the opinionated assistant base class). By centralizing these concerns in packages/agents/src/chat/, the project avoids logic duplication and protocol drift between different agent implementations.

  2. Overview of the Think Agent base class

    main
    Think (@cloudflare/think, v0.1.2) is an opinionated base class for building AI assistants. It provides a standardized implementation of the chat lifecycle, including message persistence, agentic loops, streaming, and client tools. It is designed to be backed by Durable Object SQLite to ensure state survives hibernation and can handle complex interactions like resumable streams and error recovery.

  3. Overview of the Multi-player Chess ChatGPT App

    main
    The Multi-player Chess ChatGPT App is a real-time multiplayer chess game designed to run on ChatGPT. It demonstrates how to use McpAgent to build a ChatGPT app and an Agent to serve as a remote game engine. The application also features an integration where users can call ChatGPT from within the app (e.g., via an 'Ask for help' button) to receive strategic advice during gameplay.

  5. Overview of @cloudflare/shell

    main

    The @cloudflare/shell package provides a sandboxed JavaScript execution and filesystem runtime designed for Cloudflare Workers agents. It is not a bash interpreter; instead of parsing shell syntax, it executes JavaScript and exposes a typed state object to interact with a filesystem backend.

    Key components include:

    • StateBackend: A runtime-neutral interface for filesystem/state operations.
    • FileSystem: Includes InMemoryFs (ephemeral) and WorkspaceFileSystem (durable).
    • Workspace: Durable file storage backed by SQLite and optional R2.
    • ToolProviders: stateTools(workspace) and gitTools(workspace) for use with @cloudflare/codemode to expose filesystem and git capabilities to sandboxed executions.

  6. Overview of Think (Experimental)

    main

    @cloudflare/think is an opinionated chat agent base class for Cloudflare Workers designed for agents whose work must outlive a single request. It manages the full chat lifecycle, including:

    • Agentic Loop & Persistence: Handles the loop and uses Durable Object SQLite for message persistence.
    • Durable Turns: In-flight turns survive Durable Object eviction and resume automatically.
    • Recovery-aware Delivery: Replies are snapshotted as accepted, streaming, or completed to prevent duplicate partial messages during restarts.
    • Durable Submissions: Supports webhooks and RPC callers using idempotency keys.
    • Advanced Sessions: Provides tree-structured history with branching, compaction, and full-text search.
    • Human-in-the-loop & Client Tools: Allows turns to pause for human approval or browser-side tools without holding a request open.
    • Built-in Tools: Includes a read tool for text (with line numbers) and multimodal support for images/PDFs.

    Think can function as a top-level agent (WebSocket chat to browsers via useAgentChat) or a sub-agent (RPC streaming from a parent agent via chat()).

  7. Explore Cloudflare Agents SDK Documentation by Package

    main

    The Cloudflare Agents SDK documentation is organized by core packages. Depending on your use case, you should refer to the specific documentation directory for the package you are using:

    • agents: For working with Durable Object agents, state management, routing, scheduling, sessions, Model Context Protocol (MCP), and shared primitives.
    • @cloudflare/think: For using the opinionated agent harness built on top of agents, codemode, and shell.
    • @cloudflare/codemode: For sandboxed code execution, tool providers, connectors, approvals, and snippets.
    • @cloudflare/shell: For managing durable workspaces and filesystem tools.
    • @cloudflare/voice: For implementing voice agents, clients, audio pipelines, and provider contracts.

  8. Compare Agents SDK with other Voice Frameworks

    main
    The Agents SDK is designed for JavaScript/TypeScript developers using WebSockets for transport. Unlike competitors like Pipecat (Python) or LiveKit (WebRTC), the Agents SDK leverages Durable Objects for state persistence (SQLite + bidirectional sync) and built-in MCP support, allowing for easy deployment via wrangler deploy.

  9. Understand Chat Recovery Engine Architecture

    main

    The Cloudflare Agents chat recovery engine is designed as a message-agnostic recovery kernel for the Agents-SDK fiber and DO-alarm substrate. It is not a general-purpose durable-recovery library, but rather a specialized engine for handling interrupted AI streaming sessions.

    Key Architectural Constraints:

    • Trigger: The engine is entered via handleChatFiberRecovery(ctx: FiberRecoveryContext, ...). It relies on Agents-SDK fiber-recovery mechanisms (e.g., cf_agents_runs, _runFiberWithStashWrapper).
    • Scheduler: Uses chatRecoverySchedulePolicy which implements DO-alarm semantics. It is not compatible with standard Node/Postgres schedulers due to its reliance on alarm() behavior.
    • Persistence: Uses ResumableStream (built on DO-SQLite via this.sql) and adapter-specific storage via ctx.storage.
    • Lease Layer: Assumes a single-DO actor and idempotent schedule() calls. It sits below multi-owner execution stores (like Flue's lease/queue system).

  10. Understand the relationship between Durable Streams and the Agents SDK

    main

    The Agents SDK and Durable Streams serve different layers of the agent architecture.

    • Durable Streams is a data/transport primitive. It provides durable, offset-addressed, append-only byte streams over HTTP. It is responsible for storing and replaying streams but does not provide compute.
    • Agents SDK is a stateful compute runtime. It manages the agent loop, including state, tools, scheduling, and client connections. It includes its own streaming layer for managing conversation history and recovery.

    In short: Durable Streams handles the transport of bytes, while the Agents SDK handles the execution of the agent logic.

  11. Agent Patterns Overview

    main

    The demo implements five fundamental AI agent patterns based on Anthropic research, each running within a Cloudflare Durable Object for persistence and real-time updates:

    1. Prompt Chaining: Sequential processing where each step builds on the previous.
    2. Routing: Intelligent classification and routing of tasks.
    3. Parallelization: Concurrent execution of multiple subtasks.
    4. Orchestrator-Workers: Dynamic task breakdown and delegation.
    5. Evaluator-Optimizer: Iterative improvement through feedback loops.

  12. Explore Experimental Cloudflare Agents Patterns

    main

    The experimental/ directory contains prototypes and future-facing work using unstable Cloudflare APIs such as Durable Object Facets, Worker Loaders, and ctx.exports. These patterns are intended for exploration and prototyping and should not be used in production.

    Key experimental areas include:

    • Gadgets: Exploration of facets, isolation, and structural safety (e.g., Gatekeeper/ApprovalQueue patterns, Worker Loader sandboxing, and sub-agent facets).
    • WebMCP: An adapter bridging McpAgent tools into Chrome's native navigator.modelContext API.
    • Forever (Durable Execution): Long-running execution patterns using keepAlive, runFiber (checkpointing/eviction recovery), and AIChatAgent chat recovery via onChatRecovery.
    • Session Memory: Conversation history management using the Session API with automatic micro-compaction and LLM-based summarization.