agents 0.16.2 → 0.17.0

package/docs/get-current-agent.md

@@ -0,0 +1,204 @@
+# `getCurrentAgent()`
+
+## Automatic context for custom methods
+
+The framework detects and wraps custom Agent methods during initialization so `getCurrentAgent()` can resolve the active agent inside them and the functions they call.
+
+## How It Works
+
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
+
+export class MyAgent extends AIChatAgent {
+  async customMethod() {
+    const { agent } = getCurrentAgent<MyAgent>();
+    // ✅ agent is automatically available!
+    console.log(agent.name);
+  }
+
+  async anotherMethod() {
+    // ✅ This works too - no setup needed!
+    const { agent } = getCurrentAgent<MyAgent>();
+    return agent.state;
+  }
+}
+```
+
+**Zero configuration required!** The framework automatically:
+
+1. Scans your agent class for custom methods
+2. Wraps them with agent context during initialization
+3. Ensures `getCurrentAgent()` works in all external functions called from your methods
+
+## Real-World Example
+
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+// External utility function that needs agent context
+async function processWithAI(prompt: string) {
+  const { agent } = getCurrentAgent<MyAgent>();
+  // ✅ External functions can access the current agent!
+
+  return await generateText({
+    model: openai("gpt-4"),
+    prompt: `Agent ${agent?.name}: ${prompt}`
+  });
+}
+
+export class MyAgent extends AIChatAgent {
+  async customMethod(message: string) {
+    // Use this.* to access agent properties directly
+    console.log("Agent name:", this.name);
+    console.log("Agent state:", this.state);
+
+    // External functions automatically work!
+    const result = await processWithAI(message);
+    return result.text;
+  }
+}
+```
+
+### Built-in vs Custom Methods
+
+- **Built-in methods** (onRequest, onEmail, onStateChanged): Already have context
+- **Custom methods** (your methods): Automatically wrapped during initialization
+- **External functions**: Access context through `getCurrentAgent()`
+
+### The Context Flow
+
+```typescript
+// When you call a custom method:
+agent.customMethod()
+  → automatically wrapped with agentContext.run()
+  → your method executes with full context
+  → external functions can use getCurrentAgent()
+```
+
+## Common Use Cases
+
+### Working with AI SDK Tools
+
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+
+export class MyAgent extends AIChatAgent {
+  async generateResponse(prompt: string) {
+    // AI SDK tools automatically work
+    const response = await generateText({
+      model: openai("gpt-4"),
+      prompt,
+      tools: {
+        // Tools that use getCurrentAgent() work perfectly
+      }
+    });
+
+    return response.text;
+  }
+}
+```
+
+### Calling External Libraries
+
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
+
+async function saveToDatabase(data: any) {
+  const { agent } = getCurrentAgent<MyAgent>();
+  // Can access agent info for logging, context, etc.
+  console.log(`Saving data for agent: ${agent?.name}`);
+}
+
+export class MyAgent extends AIChatAgent {
+  async processData(data: any) {
+    // External functions automatically have context
+    await saveToDatabase(data);
+  }
+}
+```
+
+## When context is lost
+
+The agent context only propagates along the call tree of the original
+invocation. Code reached outside that call tree starts with an empty context,
+so `getCurrentAgent()` returns an object whose fields are `undefined`. Common
+cases include:
+
+- a host callback invoked through RPC from a Worker Loader child isolate, such
+  as sandboxed Codemode execution;
+- a service binding or Durable Object RPC entrypoint;
+- a queue consumer or another entrypoint that retains an agent reference.
+
+Route the callback through a public method on the agent. Custom methods are
+wrapped automatically, so calling `agent.someMethod()` re-enters that agent's
+context:
+
+```typescript
+import { RpcTarget } from "cloudflare:workers";
+
+class HostCallbackBridge extends RpcTarget {
+  constructor(private agent: MyMcpAgent) {
+    super();
+  }
+
+  // Invoked through RPC from a Worker Loader child isolate. There is no context
+  // ancestry. Calling a public agent method restores it automatically.
+  async invoke() {
+    return this.agent.handleSandboxCallback();
+  }
+}
+
+export class MyMcpAgent extends McpAgent {
+  async handleSandboxCallback() {
+    const { agent } = getCurrentAgent<MyMcpAgent>();
+    // `agent` is available again.
+  }
+}
+```
+
+Context restored this way has `connection`, `request`, and `email` unset. It
+is not tied to live client I/O.
+
+Server-initiated MCP requests (`elicitInput`, `createMessage`, and `listRoots`)
+on `McpAgent` do not require this indirection because the MCP transport retains
+its owning agent.
+
+## API reference
+
+The agents package exports one main function for context management:
+
+### `getCurrentAgent<T>()`
+
+Gets the current agent from any context where it's available.
+
+**Returns:**
+
+```typescript
+{
+  agent: T | undefined,
+  connection: Connection | undefined,
+  request: Request | undefined
+}
+```
+
+**Usage:**
+
+```typescript
+import { AIChatAgent } from "@cloudflare/ai-chat";
+import { getCurrentAgent } from "agents";
+
+export class MyAgent extends AIChatAgent {
+  async customMethod() {
+    const { agent, connection, request } = getCurrentAgent<MyAgent>();
+    // agent is properly typed as MyAgent
+    // connection and request available if called from a request handler
+  }
+}
+```

package/docs/getting-started.md

@@ -0,0 +1,305 @@
+# Getting Started
+
+Build AI agents that persist, think, and act. Agents run on Cloudflare's global network, maintain state across requests, and connect to clients in real-time via WebSockets.
+
+**What you'll build:** A counter agent with persistent state that syncs to a React frontend in real-time.
+
+**Time:** ~10 minutes
+
+---
+
+## Create a New Project
+
+```bash
+npm create cloudflare@latest -- --template cloudflare/agents-starter
+cd my-agent
+npm install
+```
+
+This creates a project with:
+
+- `src/server.ts` - Your agent code
+- `src/client.tsx` - React frontend
+- `wrangler.jsonc` - Cloudflare configuration
+- `tsconfig.json` - Extends `agents/tsconfig` for correct decorator and module settings
+- `vite.config.ts` - Includes the `agents/vite` plugin for decorator support
+
+The starter template includes two SDK integrations that are required for `@callable()` decorators. If you are setting up a project manually, add both:
+
+**tsconfig.json** — extends `agents/tsconfig`, which sets `target: "ES2021"` and other recommended options:
+
+```json
+{
+  "extends": "agents/tsconfig"
+}
+```
+
+**vite.config.ts** — includes the `agents()` plugin, which handles TC39 decorator transforms (required because Vite 8's Oxc transpiler does not support them yet):
+
+```typescript
+import { cloudflare } from "@cloudflare/vite-plugin";
+import react from "@vitejs/plugin-react";
+import agents from "agents/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [agents(), react(), cloudflare()]
+});
+```
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) to see your agent in action.
+
+---
+
+## Your First Agent
+
+Let's build a simple counter agent from scratch. Replace `src/server.ts`:
+
+```typescript
+import { Agent, routeAgentRequest, callable } from "agents";
+
+// Define the state shape
+type CounterState = {
+  count: number;
+};
+
+// Create the agent
+export class Counter extends Agent<Env, CounterState> {
+  // Initial state for new instances
+  initialState: CounterState = { count: 0 };
+
+  // Methods marked with @callable can be called from the client
+  @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;
+  }
+
+  @callable()
+  reset() {
+    this.setState({ count: 0 });
+  }
+}
+
+// Route requests to agents
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    return (
+      (await routeAgentRequest(request, env)) ??
+      new Response("Not found", { status: 404 })
+    );
+  }
+};
+```
+
+Update `wrangler.jsonc` to register the agent:
+
+```jsonc
+{
+  "name": "my-agent",
+  "main": "src/server.ts",
+  "compatibility_date": "2025-01-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "Counter",
+        "class_name": "Counter"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["Counter"]
+    }
+  ]
+}
+```
+
+---
+
+## Connect from React
+
+Replace `src/client.tsx`:
+
+```tsx
+import { useAgent } from "agents/react";
+
+// Match your agent's state type
+type CounterState = {
+  count: number;
+};
+
+export default function App() {
+  // Connect to the Counter agent
+  const agent = useAgent<CounterState>({
+    agent: "Counter"
+  });
+
+  return (
+    <div style={{ padding: "2rem", fontFamily: "system-ui" }}>
+      <h1>Counter Agent</h1>
+      <p style={{ fontSize: "3rem" }}>{agent.state?.count ?? 0}</p>
+      <div style={{ display: "flex", gap: "1rem" }}>
+        <button onClick={() => agent.stub.decrement()}>-</button>
+        <button onClick={() => agent.stub.reset()}>Reset</button>
+        <button onClick={() => agent.stub.increment()}>+</button>
+      </div>
+    </div>
+  );
+}
+```
+
+Key points:
+
+- **`useAgent`** connects to your agent via WebSocket
+- **`agent.state`** is reactive — the component re-renders when state changes
+- **`agent.stub.methodName()`** calls methods marked with `@callable()` on your agent
+
+---
+
+## What Just Happened?
+
+When you clicked the button:
+
+1. **Client** called `agent.stub.increment()` over WebSocket
+2. **Agent** ran `increment()`, updated state with `setState()`
+3. **State** persisted to SQLite automatically
+4. **Broadcast** sent to all connected clients
+5. **React** re-rendered with updated `agent.state`
+
+```
+┌─────────────┐         ┌─────────────┐
+│   Browser   │◄───────►│    Agent    │
+│  (React)    │   WS    │  (Counter)  │
+└─────────────┘         └──────┬──────┘
+                               │
+                        ┌──────▼──────┐
+                        │   SQLite    │
+                        │  (State)    │
+                        └─────────────┘
+```
+
+### Key Concepts
+
+| Concept              | What it means                                                                               |
+| -------------------- | ------------------------------------------------------------------------------------------- |
+| **Agent instance**   | Each unique name gets its own agent. `Counter:user-123` is separate from `Counter:user-456` |
+| **Persistent state** | State survives restarts, deploys, and hibernation. It's stored in SQLite                    |
+| **Real-time sync**   | All clients connected to the same agent receive state updates instantly                     |
+| **Hibernation**      | When no clients are connected, the agent hibernates (no cost). It wakes on the next request |
+
+---
+
+## Connect from Vanilla JS
+
+If you're not using React:
+
+```typescript
+import { AgentClient } from "agents/client";
+
+const agent = new AgentClient({
+  agent: "Counter",
+  name: "my-counter", // optional, defaults to "default"
+  host: window.location.host
+});
+
+await agent.ready;
+
+// Call methods
+await agent.call("increment");
+console.log("Current count:", agent.state?.count);
+
+await agent.call("reset");
+```
+
+---
+
+## Deploy to Cloudflare
+
+```bash
+npm run deploy
+```
+
+Your agent is now live on Cloudflare's global network, running close to your users.
+
+---
+
+## Next Steps
+
+Now that you have a working agent, explore these topics:
+
+- **[State Management](./state.md)** - Deep dive into `setState()`, `initialState`, and `onStateChanged()`
+- **[Client SDK](./client-sdk.md)** - Full `useAgent` and `AgentClient` API reference
+- **[Scheduling](./scheduling.md)** - Run tasks on a delay, schedule, or cron
+- **[Agent Class](./agent-class.md)** - Lifecycle methods, HTTP handlers, and WebSocket events
+
+### Common Patterns
+
+| I want to...             | Read...                                  |
+| ------------------------ | ---------------------------------------- |
+| Add AI/LLM capabilities  | [Chat Agents](./chat-agents.md)          |
+| Expose tools via MCP     | [Creating MCP Servers](./mcp-servers.md) |
+| Run background tasks     | [Scheduling](./scheduling.md)            |
+| Handle emails            | [Email Service](./email.md)              |
+| Use Cloudflare Workflows | [Workflows](./workflows.md)              |
+
+---
+
+## Troubleshooting
+
+### "Agent not found" / 404 errors
+
+Make sure:
+
+1. Agent class is exported from your server file
+2. `wrangler.jsonc` has the binding and migration
+3. Agent name in client matches the class name (case-insensitive)
+
+### State not syncing
+
+Check that:
+
+1. You're calling `this.setState()`, not mutating `this.state` directly
+2. Your agent has `initialState` defined (state is only sent on connect if the agent has state)
+3. WebSocket connection is established (check browser dev tools)
+
+### "Method X is not callable" errors
+
+Make sure your methods are decorated with `@callable()`:
+
+```typescript
+import { callable } from "agents";
+
+@callable()
+increment() {
+  // ...
+}
+```
+
+### Type errors with `agent.stub`
+
+Add the agent type parameter:
+
+```typescript
+const agent = useAgent<Counter, CounterState>({
+  agent: "Counter",
+  onStateUpdate: (state) => setCount(state.count)
+});
+
+// Now agent.stub is fully typed
+agent.stub.increment(); // ✓ TypeScript knows this method exists
+```