pi-cloudflare 0.1.0

package/skills/agents-sdk/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: agents-sdk
+description: Build AI agents on Cloudflare Workers using the Agents SDK. Load when creating stateful agents, durable workflows, real-time WebSocket apps, scheduled tasks, MCP servers, chat applications, voice agents, or browser automation. Covers Agent class, state management, callable RPC, Workflows, durable execution, queues, retries, observability, and React hooks. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
+---
+
+# Cloudflare Agents SDK
+
+Your knowledge of the Agents SDK may be outdated. **Prefer retrieval over pre-training** for any Agents SDK task.
+
+## Retrieval Sources
+
+Cloudflare docs: https://developers.cloudflare.com/agents/
+
+| Topic | Docs URL | Use for |
+|-------|----------|---------|
+| Getting started | [Quick start](https://developers.cloudflare.com/agents/getting-started/quick-start/) | First agent, project setup |
+| Adding to existing project | [Add to existing project](https://developers.cloudflare.com/agents/getting-started/add-to-existing-project/) | Install into existing Workers app |
+| Configuration | [Configuration](https://developers.cloudflare.com/agents/api-reference/configuration/) | `wrangler.jsonc`, bindings, assets, deployment |
+| Agent class | [Agents API](https://developers.cloudflare.com/agents/api-reference/agents-api/) | Agent lifecycle, patterns, pitfalls |
+| State | [Store and sync state](https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/) | `setState`, `validateStateChange`, persistence |
+| Routing | [Routing](https://developers.cloudflare.com/agents/api-reference/routing/) | URL patterns, `routeAgentRequest` |
+| Callable methods | [Callable methods](https://developers.cloudflare.com/agents/api-reference/callable-methods/) | `@callable`, RPC, streaming, timeouts |
+| Scheduling | [Schedule tasks](https://developers.cloudflare.com/agents/api-reference/schedule-tasks/) | `schedule()`, `scheduleEvery()`, cron |
+| Workflows | [Run workflows](https://developers.cloudflare.com/agents/api-reference/run-workflows/) | `AgentWorkflow`, durable multi-step tasks |
+| HTTP/WebSockets | [WebSockets](https://developers.cloudflare.com/agents/api-reference/websockets/) | Lifecycle hooks, hibernation |
+| Chat agents | [Chat agents](https://developers.cloudflare.com/agents/api-reference/chat-agents/) | `AIChatAgent`, streaming, tools, persistence |
+| Client SDK | [Client SDK](https://developers.cloudflare.com/agents/api-reference/client-sdk/) | `useAgent`, `useAgentChat`, React hooks |
+| Client tools | [Client tools](https://developers.cloudflare.com/agents/api-reference/client-tools/) | Client-side tools, `autoContinueAfterToolResult` |
+| Server-driven messages | [Trigger patterns](https://developers.cloudflare.com/agents/api-reference/trigger-patterns/) | `saveMessages`, `waitUntilStable`, server-initiated turns |
+| Resumable streaming | [Resumable streaming](https://developers.cloudflare.com/agents/api-reference/resumable-streaming/) | Stream recovery on disconnect |
+| Email | [Email](https://developers.cloudflare.com/agents/api-reference/email/) | Email routing, secure reply resolver |
+| MCP client | [MCP client](https://developers.cloudflare.com/agents/api-reference/mcp-client-api/) | Connecting to MCP servers |
+| MCP server | [MCP server](https://developers.cloudflare.com/agents/api-reference/mcp-agent-api/) | Building MCP servers with `McpAgent` |
+| MCP transports | [MCP transports](https://developers.cloudflare.com/agents/api-reference/mcp-transports/) | Streamable HTTP, SSE, RPC transport options |
+| Securing MCP servers | [Securing MCP](https://developers.cloudflare.com/agents/api-reference/securing-mcp-servers/) | OAuth, proxy MCP, hardening |
+| Human-in-the-loop | [Human-in-the-loop](https://developers.cloudflare.com/agents/concepts/human-in-the-loop/) | Approval flows, `needsApproval`, workflows |
+| Durable execution | [Durable execution](https://developers.cloudflare.com/agents/api-reference/durable-execution/) | `runFiber()`, `stash()`, surviving DO eviction |
+| Queue | [Queue](https://developers.cloudflare.com/agents/api-reference/queue-tasks/) | Built-in FIFO queue, `queue()` |
+| Retries | [Retries](https://developers.cloudflare.com/agents/api-reference/retries/) | `this.retry()`, backoff/jitter |
+| Observability | [Observability](https://developers.cloudflare.com/agents/api-reference/observability/) | Diagnostics-channel events |
+| Push notifications | [Push notifications](https://developers.cloudflare.com/agents/api-reference/push-notifications/) | Web Push + VAPID from agents |
+| Webhooks | [Webhooks](https://developers.cloudflare.com/agents/api-reference/webhooks/) | Receiving external webhooks |
+| Cross-domain auth | [Cross-domain auth](https://developers.cloudflare.com/agents/api-reference/cross-domain-authentication/) | WebSocket auth, tokens, CORS |
+| Readonly connections | [Readonly](https://developers.cloudflare.com/agents/api-reference/readonly-connections/) | `shouldConnectionBeReadonly` |
+| Voice | [Voice](https://developers.cloudflare.com/agents/api-reference/voice/) | Experimental STT/TTS, `withVoice` |
+| Browse the web | [Browser tools](https://developers.cloudflare.com/agents/api-reference/browse-the-web/) | Experimental CDP browser automation |
+| Think | [Think](https://developers.cloudflare.com/agents/api-reference/think/) | Experimental higher-level chat agent class |
+| Migrations | [AI SDK v5](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v5/), [AI SDK v6](https://developers.cloudflare.com/agents/guides/migration-to-ai-sdk-v6/) | Upgrading `@cloudflare/ai-chat` |
+
+## Capabilities
+
+The Agents SDK provides:
+
+- **Persistent state** — SQLite-backed, auto-synced to clients via `setState`
+- **Callable RPC** — `@callable()` methods invoked over WebSocket
+- **Scheduling** — One-time, recurring (`scheduleEvery`), and cron tasks
+- **Workflows** — Durable multi-step background processing via `AgentWorkflow`
+- **Durable execution** — `runFiber()` / `stash()` for work that survives DO eviction
+- **Queue** — Built-in FIFO queue with retries via `queue()`
+- **Retries** — `this.retry()` with exponential backoff and jitter
+- **MCP integration** — Connect to MCP servers or build your own with `McpAgent`
+- **Email handling** — Receive and reply to emails with secure routing
+- **Streaming chat** — `AIChatAgent` with resumable streams, message persistence, tools
+- **Server-driven messages** — `saveMessages`, `waitUntilStable` for proactive agent turns
+- **React hooks** — `useAgent`, `useAgentChat` for client apps
+- **Observability** — `diagnostics_channel` events for state, RPC, schedule, lifecycle
+- **Push notifications** — Web Push + VAPID delivery from agents
+- **Webhooks** — Receive and verify external webhooks
+- **Voice** (experimental) — STT/TTS via `@cloudflare/voice`
+- **Browser tools** (experimental) — CDP-powered browsing via `agents/browser`
+- **Think** (experimental) — Higher-level chat agent via `@cloudflare/think`
+
+## FIRST: Verify Installation
+
+```bash
+npm ls agents  # Should show agents package
+```
+
+If not installed:
+```bash
+npm install agents
+```
+
+For chat agents:
+```bash
+npm install agents @cloudflare/ai-chat ai @ai-sdk/react
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }]
+  },
+  "migrations": [{ "tag": "v1", "new_sqlite_classes": ["MyAgent"] }]
+}
+```
+
+**Gotchas:**
+- Do NOT enable `experimentalDecorators` in tsconfig (breaks `@callable`)
+- Never edit old migrations — always add new tags
+- Each agent class needs its own DO binding + migration entry
+- Add `"ai": { "binding": "AI" }` for Workers AI
+
+## Agent Class
+
+```typescript
+import { Agent, routeAgentRequest, callable } from "agents";
+
+type State = { count: number };
+
+export class Counter extends Agent<Env, State> {
+  initialState = { count: 0 };
+
+  validateStateChange(nextState: State, source: Connection | "server") {
+    if (nextState.count < 0) throw new Error("Count cannot be negative");
+  }
+
+  onStateUpdate(state: State, source: Connection | "server") {
+    console.log("State updated:", state);
+  }
+
+  @callable()
+  increment() {
+    this.setState({ count: this.state.count + 1 });
+    return this.state.count;
+  }
+}
+
+export default {
+  fetch: (req, env) => routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
+};
+```
+
+## Routing
+
+Requests route to `/agents/{agent-name}/{instance-name}`:
+
+| Class | URL |
+|-------|-----|
+| `Counter` | `/agents/counter/user-123` |
+| `ChatRoom` | `/agents/chat-room/lobby` |
+
+Client: `useAgent({ agent: "Counter", name: "user-123" })`
+
+Custom routing: use `getAgentByName(env.MyAgent, "instance-id")` then `agent.fetch(request)`.
+
+## Core APIs
+
+| Task | API |
+|------|-----|
+| Read state | `this.state.count` |
+| Write state | `this.setState({ count: 1 })` |
+| SQL query | `` this.sql`SELECT * FROM users WHERE id = ${id}` `` |
+| Schedule (delay) | `await this.schedule(60, "task", payload)` |
+| Schedule (cron) | `await this.schedule("0 * * * *", "task", payload)` |
+| Schedule (interval) | `await this.scheduleEvery(30, "poll")` |
+| RPC method | `@callable() myMethod() { ... }` |
+| Streaming RPC | `@callable({ streaming: true }) stream(res) { ... }` |
+| Start workflow | `await this.runWorkflow("ProcessingWorkflow", params)` |
+| Durable fiber | `await this.runFiber("name", async (ctx) => { ... })` |
+| Enqueue work | `this.queue("handler", payload)` |
+| Retry with backoff | `await this.retry(fn, { maxAttempts: 5 })` |
+| Broadcast to clients | `this.broadcast(message)` |
+| Get connections | `this.getConnections(tag?)` |
+
+## React Client
+
+```tsx
+import { useAgent } from "agents/react";
+
+function App() {
+  const [state, setLocalState] = useState({ count: 0 });
+
+  const agent = useAgent({
+    agent: "Counter",
+    name: "my-instance",
+    onStateUpdate: (newState) => setLocalState(newState),
+    onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
+  });
+
+  return (
+    <button onClick={() => agent.setState({ count: state.count + 1 })}>
+      Count: {state.count}
+    </button>
+  );
+}
+```
+
+## References
+
+### Core
+- **[references/state-scheduling.md](references/state-scheduling.md)** — State persistence, scheduling, SQL
+- **[references/callable.md](references/callable.md)** — RPC methods, streaming, timeouts
+- **[references/routing.md](references/routing.md)** — URL patterns, custom routing, `getAgentByName`
+- **[references/configuration.md](references/configuration.md)** — Wrangler config, bindings, Vite setup
+
+### Chat & Streaming
+- **[references/streaming-chat.md](references/streaming-chat.md)** — AIChatAgent, resumable streams, tools
+- **[references/client-sdk.md](references/client-sdk.md)** — `useAgent`, `useAgentChat`, `AgentClient`
+- **[references/server-driven-messages.md](references/server-driven-messages.md)** — Trigger patterns, `saveMessages`
+- **[references/human-in-the-loop.md](references/human-in-the-loop.md)** — Approval flows, `needsApproval`
+
+### Background Processing
+- **[references/workflows.md](references/workflows.md)** — Durable Workflows integration
+- **[references/durable-execution.md](references/durable-execution.md)** — `runFiber`, `stash`, surviving eviction
+- **[references/queue-retries.md](references/queue-retries.md)** — Built-in queue, retry with backoff
+
+### Integrations
+- **[references/mcp.md](references/mcp.md)** — MCP client and server, transports, securing
+- **[references/email.md](references/email.md)** — Email routing and handling
+- **[references/webhooks-push.md](references/webhooks-push.md)** — Webhooks, push notifications
+- **[references/observability.md](references/observability.md)** — Diagnostics-channel events
+
+### Experimental
+- **[references/think.md](references/think.md)** — `@cloudflare/think` higher-level chat agent
+- **[references/voice.md](references/voice.md)** — `@cloudflare/voice` STT/TTS
+- **[references/codemode.md](references/codemode.md)** — Code Mode for tool orchestration
+- **[references/browse-the-web.md](references/browse-the-web.md)** — CDP browser tools

package/skills/agents-sdk/references/browse-the-web.md

@@ -0,0 +1,63 @@
+# Browse the Web (Experimental)
+
+Fetch https://developers.cloudflare.com/agents/api-reference/browse-the-web/ for complete documentation.
+
+CDP-powered browser tools that let agents scrape, screenshot, and interact with web pages.
+
+## Setup
+
+```jsonc
+// wrangler.jsonc
+{
+  "browser": { "binding": "BROWSER" },
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+## Usage with AI SDK
+
+```typescript
+import { createBrowserTools } from "agents/browser/ai";
+
+export class MyAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    const browserTools = createBrowserTools({
+      browser: this.env.BROWSER,
+      loader: this.env.LOADER
+    });
+
+    const result = streamText({
+      model: openai("gpt-4o"),
+      messages: await convertToModelMessages(this.messages),
+      tools: { ...myTools, ...browserTools },
+      onFinish
+    });
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `browser_search` | Search the web and return results |
+| `browser_execute` | Navigate to URL, execute JS, return results |
+
+The LLM writes async JavaScript IIFEs that run in a fresh browser session.
+
+## When to Use
+
+- Need a real browser (JS rendering, screenshots, interaction) → browser tools
+- Just need HTML/API data → use `fetch()` instead (faster, cheaper)
+
+## Low-Level API
+
+```typescript
+import { connectBrowser, CdpSession } from "agents/browser";
+
+const browser = await connectBrowser(this.env.BROWSER);
+const cdp = new CdpSession(browser);
+await cdp.send("Page.navigate", { url: "https://example.com" });
+```

package/skills/agents-sdk/references/callable.md

@@ -0,0 +1,92 @@
+# Callable Methods
+
+Fetch https://developers.cloudflare.com/agents/api-reference/callable-methods/ for complete documentation.
+
+## Overview
+
+`@callable()` exposes agent methods to clients via WebSocket RPC.
+
+```typescript
+import { Agent, callable } from "agents";
+
+export class MyAgent extends Agent<Env, State> {
+  @callable()
+  async greet(name: string): Promise<string> {
+    return `Hello, ${name}!`;
+  }
+
+  @callable()
+  async processData(data: unknown): Promise<Result> {
+    // Long-running work
+    return result;
+  }
+}
+```
+
+## Client Usage
+
+```typescript
+// Basic call
+const greeting = await agent.call("greet", ["World"]);
+
+// With timeout
+const result = await agent.call("processData", [data], {
+  timeout: 5000  // 5 second timeout
+});
+```
+
+## Streaming Responses
+
+```typescript
+import { Agent, callable, StreamingResponse } from "agents";
+
+export class MyAgent extends Agent<Env, State> {
+  @callable({ streaming: true })
+  async streamResults(stream: StreamingResponse, query: string) {
+    for await (const item of fetchResults(query)) {
+      stream.send(JSON.stringify(item));
+    }
+    stream.close();
+  }
+
+  @callable({ streaming: true })
+  async streamWithError(stream: StreamingResponse) {
+    try {
+      // ... work
+    } catch (error) {
+      stream.error(error.message);  // Signal error to client
+      return;
+    }
+    stream.close();
+  }
+}
+```
+
+Client with streaming:
+
+```typescript
+await agent.call("streamResults", ["search term"], {
+  stream: {
+    onChunk: (data) => console.log("Chunk:", data),
+    onDone: () => console.log("Complete"),
+    onError: (error) => console.error("Error:", error)
+  }
+});
+```
+
+## Introspection
+
+```typescript
+// Get list of callable methods on an agent
+const methods = await agent.call("getCallableMethods", []);
+// Returns: ["greet", "processData", "streamResults", ...]
+```
+
+## When to Use
+
+| Scenario | Use |
+|----------|-----|
+| Browser/mobile calling agent | `@callable()` |
+| External service calling agent | `@callable()` |
+| Worker calling agent (same codebase) | DO RPC directly |
+| Agent calling another agent | `getAgentByName()` + DO RPC |

package/skills/agents-sdk/references/client-sdk.md

@@ -0,0 +1,110 @@
+# Client SDK
+
+Fetch https://developers.cloudflare.com/agents/api-reference/client-sdk/ for complete documentation.
+
+## React: `useAgent`
+
+```tsx
+import { useAgent } from "agents/react";
+
+function App() {
+  const [state, setState] = useState({ count: 0 });
+
+  const agent = useAgent({
+    agent: "Counter",
+    name: "my-instance",
+    onStateUpdate: (newState) => setState(newState),
+    onIdentity: (name, agentType) => console.log(`Connected to ${name}`)
+  });
+
+  return <button onClick={() => agent.setState({ count: state.count + 1 })}>
+    {state.count}
+  </button>;
+}
+```
+
+### Typed RPC via `stub`
+
+```tsx
+const agent = useAgent<typeof MyAgent>({
+  agent: "MyAgent",
+  name: "default"
+});
+
+const result = await agent.stub.myMethod(arg1, arg2);
+```
+
+### Auth via Query Params
+
+```tsx
+useAgent({
+  agent: "MyAgent",
+  name: "default",
+  query: async () => `token=${await getToken()}`,
+  queryDeps: [tokenVersion]
+});
+```
+
+## React: `useAgentChat`
+
+```tsx
+import { useAgent } from "agents/react";
+import { useAgentChat } from "@cloudflare/ai-chat/react";
+
+function Chat() {
+  const agent = useAgent({ agent: "ChatAgent", name: "session-1" });
+
+  const { messages, input, handleInputChange, handleSubmit, status } =
+    useAgentChat({ agent });
+
+  return (
+    <div>
+      {messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} />
+      </form>
+    </div>
+  );
+}
+```
+
+## Vanilla JS: `AgentClient`
+
+```typescript
+import { AgentClient } from "agents/client";
+
+const client = new AgentClient({
+  agent: "MyAgent",
+  name: "default",
+  host: "https://my-worker.workers.dev"
+});
+
+client.addEventListener("stateUpdate", (e) => console.log(e.state));
+const result = await client.call("myMethod", [arg]);
+client.close();
+```
+
+## `agentFetch` for HTTP-only
+
+```typescript
+import { agentFetch } from "agents/client";
+
+const response = await agentFetch({
+  agent: "MyAgent",
+  name: "default",
+  host: "https://my-worker.workers.dev",
+  path: "/api/data"
+});
+```
+
+## Streaming RPC
+
+```typescript
+await agent.call("streamResults", ["query"], {
+  stream: {
+    onChunk: (data) => console.log(data),
+    onDone: () => console.log("done"),
+    onError: (err) => console.error(err)
+  }
+});
+```

package/skills/agents-sdk/references/codemode.md

@@ -0,0 +1,110 @@
+# Codemode (Experimental)
+
+Fetch https://developers.cloudflare.com/agents/api-reference/codemode/ for complete documentation.
+
+Codemode lets LLMs write and execute code that orchestrates your tools, instead of calling them one at a time. The LLM gets a single "write code" tool; generated JavaScript runs in an isolated Worker sandbox.
+
+## When to Use
+
+| Scenario | Use Codemode? |
+|----------|---------------|
+| Single tool call | No — standard tool calling is simpler |
+| Chained tool calls with logic | Yes |
+| Conditional logic across tools | Yes |
+| MCP multi-server workflows | Yes |
+| Simple Q&A chat | No |
+
+## Setup
+
+### Wrangler Config
+
+```jsonc
+{
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "compatibility_flags": ["nodejs_compat"]
+}
+```
+
+### Install
+
+```bash
+npm install @cloudflare/codemode ai zod
+```
+
+## Usage
+
+```typescript
+import { createCodeTool } from "@cloudflare/codemode/ai";
+import { DynamicWorkerExecutor } from "@cloudflare/codemode";
+import { streamText, tool, convertToModelMessages } from "ai";
+import { z } from "zod";
+
+const tools = {
+  getWeather: tool({
+    description: "Get weather for a location",
+    inputSchema: z.object({ location: z.string() }),
+    execute: async ({ location }) => `Weather: ${location} 72°F`
+  }),
+  sendEmail: tool({
+    description: "Send an email",
+    inputSchema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+    execute: async ({ to, subject, body }) => `Email sent to ${to}`
+  })
+};
+
+export class MyAgent extends Agent<Env, State> {
+  async onChatMessage() {
+    const executor = new DynamicWorkerExecutor({
+      loader: this.env.LOADER
+    });
+
+    const codemode = createCodeTool({ tools, executor });
+
+    const result = streamText({
+      model,
+      system: "You are a helpful assistant.",
+      messages: await convertToModelMessages(this.messages),
+      tools: { codemode }
+    });
+
+    return result.toUIMessageStreamResponse();
+  }
+}
+```
+
+## With MCP Tools
+
+```typescript
+const codemode = createCodeTool({
+  tools: {
+    ...myTools,
+    ...this.mcp.getAITools()
+  },
+  executor
+});
+```
+
+## How It Works
+
+1. `createCodeTool` generates TypeScript type definitions from your tools
+2. The LLM writes an async arrow function calling `codemode.toolName(args)`
+3. Code runs in an isolated Worker sandbox via `DynamicWorkerExecutor`
+4. Tool calls route back to the host via Workers RPC
+5. External `fetch()` is blocked by default — sandbox can only call your tools
+
+## Network Isolation
+
+```typescript
+const executor = new DynamicWorkerExecutor({
+  loader: env.LOADER,
+  globalOutbound: null           // default — fully isolated
+  // globalOutbound: env.MY_SERVICE  // route through a Fetcher
+});
+```
+
+## Limitations
+
+- Experimental — API may change
+- `needsApproval` tools execute immediately in sandbox (no approval pause yet)
+- JavaScript execution only
+- Requires `worker_loaders` binding

package/skills/agents-sdk/references/configuration.md

@@ -0,0 +1,72 @@
+# Configuration
+
+Fetch https://developers.cloudflare.com/agents/api-reference/configuration/ for complete documentation.
+
+## Wrangler Config (`wrangler.jsonc`)
+
+```jsonc
+{
+  "name": "my-agent",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-28",
+  "compatibility_flags": ["nodejs_compat"],
+  "durable_objects": {
+    "bindings": [
+      { "name": "MyAgent", "class_name": "MyAgent" },
+      { "name": "ChatAgent", "class_name": "ChatAgent" }
+    ]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["MyAgent", "ChatAgent"] }
+  ],
+  "ai": { "binding": "AI" },
+  "assets": {
+    "directory": "./dist/client",
+    "binding": "ASSETS",
+    "not_found_handling": "single-page-application",
+    "run_worker_first": true
+  }
+}
+```
+
+## Key Rules
+
+- Every agent class needs a DO binding AND a `new_sqlite_classes` migration entry
+- `nodejs_compat` is required
+- Never edit old migrations — add a new tag (e.g. `v2`) for new classes
+- Do NOT enable `experimentalDecorators` in tsconfig — it breaks `@callable`
+- For Workers AI locally, set `"ai": { "binding": "AI", "remote": true }` in `.dev.vars` or config
+- Use `wrangler secret put` for secrets, never hardcode them
+
+## Vite Setup
+
+```typescript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { agents } from "agents/vite";
+
+export default defineConfig({
+  plugins: [react(), cloudflare(), agents()]
+});
+```
+
+## Type Generation
+
+```bash
+npx wrangler types
+```
+
+This generates `env.d.ts` with typed bindings. Regenerate after changing `wrangler.jsonc`.
+
+## tsconfig
+
+Extend the agents tsconfig for correct settings:
+
+```jsonc
+{
+  "extends": ["agents/tsconfig"],
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "compilerOptions": { "paths": { "~/*": ["./src/*"] } }
+}
+```