agents 0.16.1 → 0.17.0

package/docs/index.md

@@ -0,0 +1,151 @@
+# Agents Documentation
+
+Build stateful AI agents on Cloudflare Workers. Every agent is a Durable Object — an addressable, hibernatable actor with its own SQLite database, WebSockets, and scheduling — so you can afford one durable agent per user, account, task, or conversation, with near-zero cost while idle.
+
+## Related package documentation
+
+- `@cloudflare/codemode/docs/index.md` — the sandbox runtime used by Agents Codemode integrations
+- `@cloudflare/ai-chat/README.md` — React chat clients, resumable streams, client tools, approvals, and storage controls
+
+## Choose your path
+
+Pick the base class that matches what you are building. They share the same Durable Object foundation, so you can start small and move up without re-platforming.
+
+| You are building...                                            | Use                                                                                | Why                                                                                                                    |
+| -------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Stateful backend logic, real-time sync, custom protocols       | [`Agent`](./agent-class.md)                                                        | The core class: state, WebSockets, scheduling, SQL, and sub-agents. No opinions about chat or LLMs.                    |
+| A chat UI where you own the loop, the stream, and the response | [`AIChatAgent`](./chat-agents.md)                                                  | A thin chat-protocol adapter for `useAgentChat`. Bring your own agentic loop and custom streaming.                     |
+| A durable, general-purpose reasoning agent                     | [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md)      | Opinionated runtime: agentic loop, sessions, tools, memory, compaction, recovery, and multi-channel delivery built in. |
+| A voice agent (speech in, speech out)                          | [Voice mixins](https://github.com/cloudflare/agents/blob/main/docs/voice/index.md) | `withVoice` adds real-time STT/TTS, interruption and barge-in, and conversation persistence to an agent.               |
+| Durable multi-step processes (not chat)                        | [Workflows](./workflows.md)                                                        | Long-running, retryable step orchestration with Cloudflare Workflows.                                                  |
+
+Not sure? Start with [`Agent`](./agent-class.md) for raw building blocks, or [`Think`](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) if you want a chat or reasoning agent that already handles the hard parts.
+
+## What makes these production-grade
+
+The differentiator is not "we have durable state" — it is what happens when a turn is interrupted. Agents built on this SDK keep their promises across Durable Object eviction, deploys, client disconnects, and human waits:
+
+- **Turn recovery** — an in-flight LLM turn survives Durable Object eviction and resumes instead of silently dying. See [Chat & Fiber Recovery](./chat-agents.md#stream-recovery) and [Durable Execution](./durable-execution.md).
+- **Resumable streams** — a disconnected client rejoins the same stream rather than losing the response. See [Resumable Streaming](./resumable-streaming.md).
+- **Recovery-aware delivery** — Think snapshots channel delivery as `accepted`, `streaming`, or `completed`, so a restart replays a not-yet-streamed answer but posts a safe interruption notice rather than risking a duplicate partial reply. See [Messengers — Delivery and Recovery](https://github.com/cloudflare/agents/blob/main/docs/think/messengers.md#delivery-and-recovery).
+- **Durable submissions** — webhooks and RPC callers submit a turn with an idempotency key and check status later, instead of holding a request open. See [Programmatic Submissions](https://github.com/cloudflare/agents/blob/main/docs/think/programmatic-submissions.md).
+- **Human-in-the-loop without hangs** — a turn can pause for approval and resume later. A human wait is a first-class state, not a stuck request. See [Human in the Loop](./human-in-the-loop.md).
+
+## Getting Started
+
+- [Getting Started](./getting-started.md) - Quick start guide for new users
+- [Adding to an Existing Project](./adding-to-existing-project.md) - Integrate agents into your app
+- [Understanding the Agent Class](./agent-class.md) - Deep dive into the Agent class architecture
+
+## Core Concepts
+
+- [State Management](./state.md) - Managing agent state with `setState()`, `initialState`, and `onStateChanged()`
+- [Routing](./routing.md) - How `routeAgentRequest()` and agent naming works
+- [Sub-agents](./sub-agents.md) - Parent/child DO composition via facets, nested routing, and direct child connections
+- [HTTP & WebSockets](./http-websockets.md) - Request handling and real-time connections
+- [Callable Methods](./callable-methods.md) - The `@callable` decorator and client-server method calls
+- [Readonly Connections](./readonly-connections.md) - Restricting which connections can modify state
+- [getCurrentAgent()](./get-current-agent.md) - Accessing agent context across async calls
+
+## Client SDK
+
+- [Client SDK](./client-sdk.md) - Connecting from React (`useAgent`) and vanilla JS (`AgentClient`), state sync, and RPC calls
+
+## Communication Channels
+
+- [Email Service](./email.md) - Sending, receiving, and replying to emails
+- [Webhooks](./webhooks.md) - Receiving and sending webhook events
+- [Push Notifications](./push-notifications.md) - Browser push notifications via Web Push API and scheduled delivery
+- TODO: [SMS](./sms.md) - Text message integration (Twilio, etc.)
+- [Voice Agents](https://github.com/cloudflare/agents/blob/main/docs/voice/index.md) - Build voice agents with real-time speech-to-text, text-to-speech, and conversation persistence
+- [Chat SDK State](./chat-sdk.md) - Store Chat SDK subscriptions, locks, queues, and history in Agents sub-agents
+- TODO: [Messengers](./messengers.md) - Slack, Discord, Telegram, and other chat platforms
+
+## Background Processing
+
+- [Queue](./queue.md) - Immediate background task execution
+- [Scheduling](./scheduling.md) - Delayed, scheduled, and cron-based tasks
+- [Retries](./retries.md) - Automatic retries with exponential backoff and jitter
+- [Durable Execution](./durable-execution.md) - `runFiber()`, `startFiber()`, `stash()`, and crash recovery for long tasks
+- [Workflows](./workflows.md) - Durable multi-step processing with Cloudflare Workflows
+- [Human in the Loop](./human-in-the-loop.md) - Approval flows and manual intervention
+
+## AI Integration
+
+- TODO: [AI SDK Integration](./ai-sdk.md) - Using Vercel AI SDK with agents
+- TODO: [TanStack Integration](./tanstack.md) - Using TanStack AI with agents
+- [Chat Agents](./chat-agents.md) - `AIChatAgent` class and `useAgentChat` React hook
+- [Chat & Fiber Recovery](./chat-agents.md#stream-recovery) - Recover LLM turns after Durable Object eviction
+- [Agent Tools](./agent-tools.md) - Run chat-capable sub-agents as tools with streaming child timelines
+- [Server-Driven Messages](./server-driven-messages.md) - Autonomous agent workflows: scheduled follow-ups, queue processing, webhooks, chained reasoning
+- TODO: [Using AI Models](./using-ai-models.md) - OpenAI, Anthropic, Workers AI, and other providers
+- TODO: [RAG (Retrieval Augmented Generation)](./rag.md) - Vector search with Vectorize
+- [Sessions (Experimental)](./sessions.md) - Persistent conversation storage with tree-structured messages, context blocks, compaction, and search
+- [Workspace (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/shell/index.md) - Durable virtual filesystem backed by SQLite + R2
+- [Codemode (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/agents/codemode.md) - LLM-generated executable code for tool orchestration
+- [Client Tools Continuation](./client-tools-continuation.md) - Handling tool calls across client/server
+- [Resumable Streaming](./resumable-streaming.md) - Automatic stream resumption on client disconnect
+
+## Think (Experimental)
+
+- [Overview](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) - Opinionated chat agent with built-in memory, tools, and streaming
+- [Getting Started](https://github.com/cloudflare/agents/blob/main/docs/think/getting-started.md) - Build your first Think agent step by step
+- [Lifecycle Hooks](https://github.com/cloudflare/agents/blob/main/docs/think/lifecycle-hooks.md) - `beforeTurn`, `onStepFinish`, `onChunk`, `onChatResponse`, and more
+- [Tools](https://github.com/cloudflare/agents/blob/main/docs/think/tools.md) - Workspace tools, code execution, extensions
+- [Actions](https://github.com/cloudflare/agents/blob/main/docs/think/actions.md) - Server actions with idempotency, approvals, authorization, and reply attachments
+- [Channels](https://github.com/cloudflare/agents/blob/main/docs/think/channels.md) - Per-channel policy, channel selection, and out-of-band notices
+- [Messengers](https://github.com/cloudflare/agents/blob/main/docs/think/messengers.md) - Receive and reply to Chat SDK messenger webhooks from Think
+- [Client Tools](https://github.com/cloudflare/agents/blob/main/docs/think/client-tools.md) - Browser-side tools, approvals, and concurrency
+- [Sub-agents and Programmatic Turns](https://github.com/cloudflare/agents/blob/main/docs/think/sub-agents.md) - RPC streaming, `saveMessages`, recovery
+- [Programmatic Submissions](https://github.com/cloudflare/agents/blob/main/docs/think/programmatic-submissions.md) - Durable Think turn admission for webhooks and RPC callers
+
+## MCP (Model Context Protocol)
+
+- [Creating MCP Servers](./mcp-servers.md) - Build MCP servers with `McpAgent`
+- [Securing MCP Servers](./securing-mcp-servers.md) - OAuth and authentication for MCP
+- [Connecting to MCP Servers](./mcp-client.md) - `addMcpServer()` and consuming external MCP tools
+- [MCP Transports](./mcp-transports.md) - Transport options: Streamable HTTP, SSE, and RPC
+
+## Authentication & Security
+
+- TODO: [Securing your Agents](./securing-agents.md) - Authentication, authorization, and access control
+- [Cross-Domain Authentication](./cross-domain-authentication.md) - Auth across different domains
+
+## Observability & Debugging
+
+- [Observability](./observability.md) - Monitoring and tracing agent activity
+- TODO: [Testing](./testing.md) - Unit tests, integration tests, mocking agents
+- TODO: [Evals](./evals.md) - Evaluating AI agent quality and behavior
+
+## Agent Studio
+
+- TODO: [Agent Studio](./agent-studio.md) - Local dev tool for inspecting and interacting with agent instances
+
+## Compute Environments
+
+- [Browse the Web (Experimental)](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
+- TODO: [Cloudflare Sandboxes](./sandboxes.md) - Isolated environments for coding agents, ffmpeg, and heavy compute
+
+## Advanced Topics
+
+- [Long-Running Agents](./long-running-agents.md) - Building agents that persist for weeks or months: lifecycle, recovery, async operations, and planning
+- TODO: [SQL API](./sql.md) - Using `this.sql` for direct database queries
+- TODO: [Memory & Persistence](./memory.md) - Long-term storage patterns
+- [Configuration](./configuration.md) - wrangler.jsonc setup, types, secrets, and deployment
+
+## Migration Guides
+
+- [Migration to AI SDK v5](./migration-to-ai-sdk-v5.md)
+- [Migration to AI SDK v6](./migration-to-ai-sdk-v6.md)
+
+## Reference
+
+- TODO: [API Reference](./api-reference.md) - Complete API documentation
+- TODO: [FAQ / How is this different from Durable Objects?](./faq.md)
+- TODO: [Resources & Further Reading](./resources.md)
+
+---
+
+## Contributing
+
+Found something missing? Documentation contributions are welcome!