agents 0.0.0-7ff0509 → 0.0.0-80a8fbd0

package/README.md

@@ -1,428 +1,548 @@
-### 🧠 `agents` - A Framework for Digital Intelligence
+# agents
 
-![agents-header](https://github.com/user-attachments/assets/f6d99eeb-1803-4495-9c5e-3cf07a37b402)
+![npm install agents](../../assets/npm-install-agents.svg)
 
-Welcome to a new chapter in software development, where AI agents persist, think, and act with purpose. The `agents` framework creates an environment where artificial intelligence can flourish - maintaining state, engaging in meaningful interactions, and evolving over time.
+**Build software that thinks and does.**
 
-_This project is in active development. Join us in shaping the future of intelligent agents._
+Persistent AI agents on Cloudflare's global network. They remember context, reason through problems, schedule their own work, and take action—all without you managing servers.
 
-#### The Nature of Agents
+```sh
+npm create cloudflare@latest -- --template cloudflare/agents-starter
+```
+
+Or add to an existing project:
+
+```sh
+npm install agents
+```
+
+---
 
-An AI agent transcends traditional software boundaries. It's an entity that:
+## Why Agents, Why Now
 
-- **Persistence**: Maintains its state and knowledge across time
-- **Agency**: Acts autonomously within its defined purpose
-- **Connection**: Communicates through multiple channels with both humans and other agents
-- **Growth**: Learns and adapts through its interactions
+LLMs can reason, plan, and use tools—but they need infrastructure that matches their capabilities. Traditional serverless is stateless and ephemeral. Agents are persistent and purposeful.
 
-Built on Cloudflare's global network, this framework provides agents with a reliable, distributed foundation where they can operate continuously and effectively.
+```
+From request handlers    →  to autonomous entities
+From stateless functions →  to persistent intelligence
+
+Traditional serverless:  Request → Response → Gone
+Agents:                  Thinking, remembering, acting — continuously
+```
 
-#### 💫 Core Principles
+**Pay only when active.** Agents hibernate between requests. You can have millions of agents—one per user, per session, per game room—each costs nothing when idle.
 
-1. **Stateful Existence**: Each agent maintains its own persistent reality
-2. **Long-lived Presence**: Agents can run for extended periods, resting when idle
-3. **Natural Communication**: Interact through HTTP, WebSockets, or direct calls
-4. **Global Distribution**: Leverage Cloudflare's network for worldwide presence
-5. **Resource Harmony**: Efficient hibernation and awakening as needed
+Built on Cloudflare Durable Objects, agents run globally, close to your users, with persistent state that survives restarts.
 
 ---
 
-### 🌱 Beginning the Journey
+## Quick Example
 
-Start with a complete environment:
+A counter agent with real-time state sync and callable methods:
 
-```sh
-# Create a new project
-npm create cloudflare@latest -- --template cloudflare/agents-starter
+```typescript
+// server.ts
+import { Agent, callable } from "agents";
 
-# Or enhance an existing one
-npm install agents
+type State = { count: number };
+
+export class CounterAgent extends Agent<Env, State> {
+  initialState: State = { 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;
+  }
+}
 ```
 
-### 📝 Your First Agent
+```tsx
+// client.tsx
+import { useAgent } from "agents/react";
+import { useState } from "react";
 
-Create an agent that bridges thought and action:
+function Counter() {
+  const [count, setCount] = useState(0);
 
-```ts
-import { Agent } from "agents";
+  const agent = useAgent<State>({
+    agent: "counter-agent",
+    name: "my-counter",
+    onStateUpdate: (state) => setCount(state.count)
+  });
 
-export class IntelligentAgent extends Agent {
-  async onRequest(request) {
-    // Transform intention into response
-    return new Response("Ready to assist.");
-  }
+  return (
+    <div>
+      <span>{count}</span>
+      <button onClick={() => agent.stub.increment()}>+</button>
+      <button onClick={() => agent.stub.decrement()}>-</button>
+    </div>
+  );
 }
 ```
 
-### 🎭 Patterns of Intelligence
+State changes sync to all connected clients automatically. Call methods like they're local functions.
 
-Agents can manifest various forms of understanding:
+---
 
-```ts
-import { Agent } from "agents";
-import { OpenAI } from "openai";
+## What You Can Build
 
-export class AIAgent extends Agent {
-  async onRequest(request) {
-    // Connect with AI capabilities
-    const ai = new OpenAI({
-      apiKey: this.env.OPENAI_API_KEY,
-    });
+| Use Case               | Why Agents                                            |
+| ---------------------- | ----------------------------------------------------- |
+| Multiplayer game rooms | Per-room state, real-time sync, hibernates when empty |
+| Customer support bots  | Remembers conversation history, escalates to humans   |
+| Collaborative editors  | Presence, cursors, document state                     |
+| Approval workflows     | Long-running, pauses for human input, durable         |
+| Personal AI assistants | Per-user memory, tool access via MCP                  |
+| Notification systems   | Scheduled delivery, user preferences, retry logic     |
 
-    // Process and understand
-    const response = await ai.chat.completions.create({
-      model: "gpt-4",
-      messages: [{ role: "user", content: await request.text() }],
-    });
+---
+
+## Features
+
+```
+Core         State sync · Routing · HTTP & WebSockets · @callable RPC · Sub-agents (facets)
+Clients      React hook · Vanilla JS · Real-time state sync
+Channels     WebSocket · HTTP · Email · (coming: SMS, Voice, Messengers)
+Background   Queue · Scheduling · Managed fibers · Workflows · Human-in-the-loop
+AI           Chat agents · Agent tools · Tool calling · MCP servers & clients
+Platform     Observability · Cross-domain auth · Resumable streams
+```
+
+### State Management
 
-    return new Response(response.choices[0].message.content);
+State persists across requests and syncs to all connected clients:
+
+```typescript
+export class MyAgent extends Agent<Env, { items: string[] }> {
+  initialState = { items: [] };
+
+  @callable()
+  addItem(item: string) {
+    this.setState({ items: [...this.state.items, item] });
   }
 
-  async processTask(task) {
-    await this.understand(task);
-    await this.act();
-    await this.reflect();
+  onStateChanged(state: State, source: Connection | "server") {
+    // Called after state is persisted and broadcast
   }
 }
 ```
 
-### 🏰 Creating Space
+### Callable Methods
 
-Define your agent's domain:
+Expose methods to clients with the `@callable()` decorator:
 
-```jsonc
-{
-  "durable_objects": {
-    "bindings": [
-      {
-        "name": "AIAgent",
-        "class_name": "AIAgent",
-      },
-    ],
-  },
-  "migrations": [
-    {
-      "tag": "v1",
-      // Mandatory for the Agent to store state
-      "new_sqlite_classes": ["AIAgent"],
-    },
-  ],
+```typescript
+@callable()
+async processOrder(orderId: string, items: Item[]) {
+  // Full type safety - clients call this like a local function
+  const result = await this.validateAndProcess(orderId, items);
+  return result;
 }
 ```
 
-### 🌐 Lifecycle
+```typescript
+// Client
+const result = await agent.stub.processOrder("order-123", items);
+```
 
-Bring your agent into being:
+### Scheduling
 
-```ts
-// Create a new instance
-const id = env.AIAgent.newUniqueId();
-const agent = env.AIAgent.get(id);
+Run tasks later, on intervals, or with cron expressions:
 
-// Initialize with purpose
-await agent.processTask({
-  type: "analysis",
-  context: "incoming_data",
-  parameters: initialConfig,
-});
+```typescript
+// In 60 seconds
+this.schedule(60, "sendReminder", { userId: "123" });
 
-// Or reconnect with an existing one
-const existingAgent = await getAgentByName(env.AIAgent, "data-analyzer");
-```
+// Every hour
+this.scheduleEvery(3600, "syncData");
 
-### 🔄 Paths of Communication
+// Daily at 9am UTC
+this.schedule("0 9 * * *", "dailyReport");
 
-#### HTTP Understanding
+// At a specific date
+this.schedule(new Date("2025-12-31"), "yearEndTask");
+```
 
-Process and respond to direct requests:
+### Background Tasks
 
-```ts
-export class APIAgent extends Agent {
-  async onRequest(request) {
-    const data = await request.json();
+Queue immediate background work:
 
-    return Response.json({
-      insight: await this.process(data),
-      moment: Date.now(),
-    });
-  }
-}
+```typescript
+await this.queue("processUpload", { fileId: "abc" });
+// Returns immediately, task runs in background
 ```
 
-#### Persistent Connections
+### Sub-agents
 
-Maintain ongoing dialogues through WebSocket:
+Spawn child Durable Objects (facets) from a parent agent. Each child has
+its own SQLite storage and runs in parallel, but is addressed under the
+parent's URL:
+
+```typescript
+export class Inbox extends Agent {
+  @callable()
+  async createChat() {
+    const id = crypto.randomUUID();
+    await this.subAgent(Chat, id);
+    return id;
+  }
 
-```ts
-export class DialogueAgent extends Agent {
-  async onConnect(connection) {
-    await this.initiate(connection);
+  override async onBeforeSubAgent(_req, { className, name }) {
+    if (!this.hasSubAgent(className, name)) {
+      return new Response("Not found", { status: 404 });
+    }
   }
+}
 
-  async onMessage(connection, message) {
-    const understanding = await this.comprehend(message);
-    await this.respond(connection, understanding);
+export class Chat extends Agent {
+  async writePreview(text: string) {
+    const inbox = await this.parentAgent(Inbox);
+    await inbox.savePreview(this.name, text);
   }
 }
 ```
 
-#### Client Communion
+Client-side, connect to a child with `useAgent({ sub: [...] })`:
 
-For direct connection to your agent:
+```tsx
+const inbox = useAgent({ agent: "Inbox", name: userId });
+const chat = useAgent({
+  agent: "Inbox",
+  name: userId,
+  sub: [{ agent: "Chat", name: chatId }]
+});
+```
 
-```ts
-import { AgentClient } from "agents/client";
+The routed URL becomes `/agents/inbox/{userId}/sub/chat/{chatId}`.
 
-const connection = new AgentClient({
-  agent: "dialogue-agent",
-  name: "insight-seeker",
-});
+Child WebSocket clients can use the same URL shape. The parent remains the
+public address, while child agents still receive `onConnect`, `onMessage`,
+`onClose`, `broadcast()`, and `getConnections()` calls scoped to their own
+clients. Parent broadcasts do not leak to child-targeted sockets, and child
+connection tags, readonly state, and protocol-message settings are preserved
+when a connection is resumed from hibernation.
 
-connection.addEventListener("message", (event) => {
-  console.log("Received:", event.data);
-});
+Nested sub-agent URLs are supported using repeated `/sub/{agent}/{name}`
+segments, subject to the platform's current facet nesting limits.
 
-connection.send(
-  JSON.stringify({
-    type: "inquiry",
-    content: "What patterns do you see?",
-  })
-);
+### Agent Tools
+
+Run chat-capable sub-agents as tools from a parent chat agent. Think agents and
+`AIChatAgent` subclasses are supported. The child keeps its own messages, tools,
+SQLite storage, and resumable stream, while the parent broadcasts
+`agent-tool-event` frames so the UI can render the child timeline inline.
+
+```typescript
+import { Think } from "@cloudflare/think";
+import { agentTool } from "agents/agent-tools";
+import { z } from "zod";
+
+export class Researcher extends Think<Env> {
+  getSystemPrompt() {
+    return "Research the requested topic and end with a concise summary.";
+  }
+}
+
+export class Assistant extends Think<Env> {
+  getTools() {
+    return {
+      research: agentTool(Researcher, {
+        description: "Research one topic in depth.",
+        inputSchema: z.object({ query: z.string().min(3) })
+      })
+    };
+  }
+}
 ```
 
-#### React Integration
+For deterministic fan-out, call `this.runAgentTool(Researcher, { input })`
+directly. Parent recovery reconciles stale child rows after restarts and marks
+unrecoverable runs `interrupted` instead of hanging. In React, use
+`useAgentToolEvents({ agent })` to render retained and replayed child timelines.
+AIChatAgent children run headlessly, so browser client tools require a separate
+bridge; server-side tools work normally. See the full
+[Agent Tools guide](../../docs/agents/agent-tools.md).
 
-For harmonious integration with React:
+### WebSocket Connections
 
-```tsx
-import { useAgent } from "agents/react";
+Handle real-time communication:
 
-function AgentInterface() {
-  const connection = useAgent({
-    agent: "dialogue-agent",
-    name: "insight-seeker",
-    onMessage: (message) => {
-      console.log("Understanding received:", message.data);
-    },
-    onOpen: () => console.log("Connection established"),
-    onClose: () => console.log("Connection closed"),
-  });
+```typescript
+async onConnect(connection: Connection) {
+  console.log(`Client ${connection.id} connected`);
+}
 
-  const inquire = () => {
-    connection.send(
-      JSON.stringify({
-        type: "inquiry",
-        content: "What insights have you gathered?",
-      })
-    );
-  };
+async onMessage(connection: Connection, message: unknown) {
+  // Handle incoming messages
+  connection.send(JSON.stringify({ received: true }));
+}
 
-  return (
-    <div className="agent-interface">
-      <button onClick={inquire}>Seek Understanding</button>
-    </div>
-  );
+async onClose(connection: Connection) {
+  console.log(`Client ${connection.id} disconnected`);
 }
 ```
 
-### 🌊 Flow of State
-
-Maintain and evolve your agent's understanding:
+### Email
 
-```ts
-export class ThinkingAgent extends Agent {
-  async evolve(newInsight) {
-    this.setState({
-      ...this.state,
-      insights: [...(this.state.insights || []), newInsight],
-      understanding: this.state.understanding + 1,
-    });
-  }
+Agents can receive and respond to emails:
 
-  onStateUpdate(state, source) {
-    console.log("Understanding deepened:", {
-      newState: state,
-      origin: source,
-    });
-  }
+```typescript
+async onEmail(email: EmailMessage) {
+  const from = email.from;
+  const subject = email.headers.get("subject");
+  // Process incoming email
 }
 ```
 
-Connect to your agent's state from React:
+---
+
+## Client SDK
+
+### React
 
 ```tsx
-import { useState } from "react";
 import { useAgent } from "agents/react";
+import { useState } from "react";
 
-function StateInterface() {
-  const [state, setState] = useState({ counter: 0 });
+function App() {
+  const [state, setState] = useState<MyState | null>(null);
 
-  const agent = useAgent({
-    agent: "thinking-agent",
-    onStateUpdate: (newState) => setState(newState),
+  const agent = useAgent<MyState>({
+    agent: "my-agent",
+    name: "instance-name",
+    onStateUpdate: (newState) => setState(newState)
   });
 
-  const increment = () => {
-    agent.setState({ counter: state.counter + 1 });
-  };
-
   return (
     <div>
-      <div>Count: {state.counter}</div>
-      <button onClick={increment}>Increment</button>
+      <pre>{JSON.stringify(state, null, 2)}</pre>
+      <button onClick={() => agent.stub.doSomething()}>Call Agent</button>
     </div>
   );
 }
 ```
 
-This creates a synchronized state that automatically updates across all connected clients.
+### Vanilla JavaScript
 
-### ⏳ Temporal Patterns
+```typescript
+import { AgentClient } from "agents/client";
 
-Schedule moments of action and reflection:
+const client = new AgentClient({
+  agent: "my-agent",
+  name: "instance-name",
+  onStateUpdate: (state) => console.log("State:", state)
+});
 
-```ts
-export class TimeAwareAgent extends Agent {
-  async initialize() {
-    // Quick reflection
-    this.schedule(10, "quickInsight", { focus: "patterns" });
+// Call methods
+const result = await client.call("processData", [payload]);
 
-    // Daily synthesis
-    this.schedule("0 0 * * *", "dailySynthesis", {
-      depth: "comprehensive",
-    });
+// Or use the stub
+const result = await client.stub.processData(payload);
+```
 
-    // Milestone review
-    this.schedule(new Date("2024-12-31"), "yearlyAnalysis");
-  }
+---
 
-  async quickInsight(data) {
-    await this.analyze(data.focus);
-  }
+## Workflows Integration
 
-  async dailySynthesis(data) {
-    await this.synthesize(data.depth);
-  }
+For durable, multi-step tasks that survive failures and can pause for human approval, integrate with [Cloudflare Workflows](https://developers.cloudflare.com/workflows/):
+
+```typescript
+import { AgentWorkflow } from "agents";
+
+export class OrderWorkflow extends AgentWorkflow<OrderAgent, OrderParams> {
+  async run(event, step) {
+    // Step 1: Validate (retries automatically on failure)
+    const validated = await step.do("validate", async () => {
+      return validateOrder(event.payload);
+    });
+
+    // Step 2: Wait for human approval
+    await this.reportProgress({ step: "approval", status: "pending" });
+    const approval = await this.waitForApproval(step, { timeout: "7 days" });
 
-  async yearlyAnalysis() {
-    await this.analyze();
+    // Step 3: Process the approved order
+    await step.do("process", async () => {
+      return processOrder(validated, approval);
+    });
   }
 }
 ```
 
-### 💬 AI Dialogue
+Workflows provide:
+
+- **Durable execution** — steps retry automatically, state persists across failures
+- **Human-in-the-loop** — pause for approval with `waitForApproval()`
+- **Long-running tasks** — run for days or weeks
+- **Progress tracking** — report status back to the agent
+
+See [Workflows](../../docs/agents/workflows.md) and [Human in the Loop](../../docs/agents/human-in-the-loop.md).
+
+---
+
+## AI Chat Integration
 
-Create meaningful conversations with intelligence:
+For AI-powered chat experiences with persistent conversations, streaming responses, and tool support, see [`@cloudflare/ai-chat`](../ai-chat/README.md).
 
-```ts
-import { AIChatAgent } from "agents/ai-chat-agent";
-import { openai } from "@ai-sdk/openai";
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
 
-export class DialogueAgent extends AIChatAgent {
+export class ChatAgent extends AIChatAgent<Env> {
   async onChatMessage(onFinish) {
-    return createDataStreamResponse({
-      execute: async (dataStream) => {
-        const stream = streamText({
-          model: openai("gpt-4o"),
-          messages: this.messages,
-          onFinish, // call onFinish so that messages get saved
-        });
-
-        stream.mergeIntoDataStream(dataStream);
-      },
+    return streamText({
+      model: openai("gpt-4o"),
+      messages: this.messages,
+      tools: this.tools,
+      onFinish
     });
   }
 }
 ```
 
-#### Creating the Interface
+```tsx
+// Client
+import { useAgentChat } from "@cloudflare/ai-chat/react";
 
-Connect with your agent through a React interface:
+const { messages, input, handleSubmit } = useAgentChat({
+  agent: useAgent({ agent: "chat-agent" })
+});
+```
 
-```tsx
-import { useAgent } from "agents/react";
-import { useAgentChat } from "agents/ai-react";
+Features:
 
-function ChatInterface() {
-  // Connect to the agent
-  const agent = useAgent({
-    agent: "dialogue-agent",
-  });
+- Automatic message persistence
+- Resumable streaming (survives disconnections)
+- Server and client-side tool execution
+- Human-in-the-loop approval for sensitive tools
 
-  // Set up the chat interaction
-  const { messages, input, handleInputChange, handleSubmit, clearHistory } =
-    useAgentChat({
-      agent,
-      maxSteps: 5,
-    });
+---
 
-  return (
-    <div className="chat-interface">
-      {/* Message History */}
-      <div className="message-flow">
-        {messages.map((message) => (
-          <div key={message.id} className="message">
-            <div className="role">{message.role}</div>
-            <div className="content">{message.content}</div>
-          </div>
-        ))}
-      </div>
-
-      {/* Input Area */}
-      <form onSubmit={handleSubmit} className="input-area">
-        <input
-          value={input}
-          onChange={handleInputChange}
-          placeholder="Type your message..."
-          className="message-input"
-        />
-      </form>
-
-      <button onClick={clearHistory} className="clear-button">
-        Clear Chat
-      </button>
-    </div>
-  );
+## MCP (Model Context Protocol)
+
+Agents integrate with MCP to act as servers (providing tools to AI assistants) or clients (using tools from other services).
+
+### Creating an MCP Server
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpAgent } from "agents/mcp";
+
+export class MyMCP extends McpAgent<Env, State, {}> {
+  server = new McpServer({ name: "my-tools", version: "1.0.0" });
+
+  async init() {
+    this.server.registerTool(
+      "lookup",
+      { description: "Look up data", inputSchema: { query: z.string() } },
+      async ({ query }) => {
+        const result = await this.search(query);
+        return { content: [{ type: "text", text: result }] };
+      }
+    );
+  }
+}
+
+export default MyMCP.serve("/mcp", { binding: "MyMCP" });
+```
+
+### Using MCP Tools
+
+```typescript
+// Connect to external MCP servers
+await this.addMcpServer(
+  "weather-service",
+  "https://weather-mcp.example.com/mcp",
+  {
+    transport: { type: "streamable-http" }
+  }
+);
+
+// Use with AI SDK
+const result = await generateText({
+  model: openai("gpt-4o"),
+  tools: this.mcp.getTools(),
+  prompt: "What's the weather in Tokyo?"
+});
+```
+
+---
+
+## Configuration
+
+Add your agent to `wrangler.jsonc`:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
 }
 ```
 
-This creates:
+Route requests to your agent:
 
-- Real-time message streaming
-- Simple message history
-- Intuitive input handling
-- Easy conversation reset
+```typescript
+import { routeAgentRequest } from "agents";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    return (
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 })
+    );
+  }
+};
+```
 
-### 💬 The Path Forward
+---
 
-We're developing new dimensions of agent capability:
+## Coming Soon
 
-#### Enhanced Understanding
+- **Browse the Web** — Headless browser for web scraping and automation
+- **Cloudflare Sandboxes** — Isolated environments for code execution
+- **SMS, Voice, Messengers** — Multi-channel communication
 
-- **WebRTC Perception**: Audio and video communication channels
-- **Email Discourse**: Automated email interaction and response
-- **Deep Memory**: Long-term context and relationship understanding
+---
 
-#### Development Insights
+## Learn More
 
-- **Evaluation Framework**: Understanding agent effectiveness
-- **Clear Sight**: Deep visibility into agent processes
-- **Private Realms**: Complete self-hosting guide
+The published package includes the complete documentation tree at
+`docs/index.md`.
 
-These capabilities will expand your agents' potential while maintaining their reliability and purpose.
+[Getting Started](../../docs/agents/getting-started.md) ·
+[State Management](../../docs/agents/state.md) ·
+[Scheduling](../../docs/agents/scheduling.md) ·
+[Callable Methods](../../docs/agents/callable-methods.md) ·
+[MCP Integration](../../docs/agents/mcp-client.md) ·
+[Full Documentation](../../docs/agents/index.md)
 
-Welcome to the future of intelligent agents. Create something meaningful. 🌟
+---
 
-### Contributing
+## Contributing
 
-Contributions are welcome, but are especially welcome when:
+Contributions are welcome, especially when:
 
-- You have opened an issue as a Request for Comment (RFC) to discuss your proposal, show your thinking, and iterate together.
-- Is not "AI slop": LLMs are powerful tools, but contributions entirely authored by vibe coding are unlikely to meet the quality bar, and will be rejected.
-- You're willing to accept feedback and make sure the changes fit the goals of the `agents` sdk. Not everything will, and that's OK.
+- You've opened an issue as an RFC to discuss your proposal
+- The contribution isn't "AI slop" — LLMs are tools, but vibe-coded PRs won't meet the quality bar
+- You're open to feedback to ensure changes fit the SDK's goals
 
 Small fixes, type bugs, and documentation improvements can be raised directly as PRs.
 
-### License
+---
+
+## License
+
+MIT licensed. See the [LICENSE](../../LICENSE) file for details.
+
+---
 
-MIT licensed. See the LICENSE file at the root of this repository for details.
+<p align="center">
+  <i>Build something that thinks. Ship something that does.</i>
+</p>