Add comprehensive Agents SDK documentation

Sync documentation from cloudflare/agents PR #812.

This update adds extensive documentation covering:
- Core concepts: scheduling, routing, state, callable methods, HTTP/WebSockets
- Client SDK: React hooks and vanilla JavaScript integration
- API reference: getCurrentAgent() context management
- Getting started: quickstart guide for building agents
- How-to guides: adding agents to existing projects

New features documented:
- scheduleEvery() for fixed-interval recurring tasks
- basePath routing for custom URL patterns
- Server-sent identity with onIdentity callbacks
- Callable improvements: timeouts, streaming, introspection
- MCP client options-based API

All documentation follows Cloudflare style guidelines with proper
component usage (WranglerConfig, TypeScriptExample, PackageManagers).

Source PR: cloudflare/agents#812

Author: Claude Code

src/content/docs/agents/api-reference/get-current-agent.mdx

@@ -0,0 +1,189 @@
+---
+title: getCurrentAgent()
+pcx_content_type: concept
+sidebar:
+  order: 14
+---
+
+import { TypeScriptExample } from "~/components";
+
+## Automatic Context for Custom Methods
+
+**All custom methods automatically have full agent context.** The framework automatically detects and wraps your custom methods during initialization, ensuring `getCurrentAgent()` works seamlessly everywhere.
+
+## How It Works
+
+<TypeScriptExample>
+
+```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;
+  }
+}
+```
+
+</TypeScriptExample>
+
+**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
+
+<TypeScriptExample>
+
+```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;
+  }
+}
+```
+
+</TypeScriptExample>
+
+### Built-in vs Custom Methods
+
+- **Built-in methods** (onRequest, onEmail, onStateUpdate): 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
+
+<TypeScriptExample>
+
+```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;
+  }
+}
+```
+
+</TypeScriptExample>
+
+### Calling External Libraries
+
+<TypeScriptExample>
+
+```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);
+  }
+}
+```
+
+</TypeScriptExample>
+
+## API Reference
+
+The agents package exports one main function for context management:
+
+### `getCurrentAgent<T>()`
+
+Gets the current agent from any context where it is available.
+
+**Returns:**
+
+<TypeScriptExample>
+
+```typescript
+{
+  agent: T | undefined,
+  connection: Connection | undefined,
+  request: Request | undefined
+}
+```
+
+</TypeScriptExample>
+
+**Usage:**
+
+<TypeScriptExample>
+
+```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
+  }
+}
+```
+
+</TypeScriptExample>

src/content/docs/agents/concepts/agent-class.mdx

@@ -341,12 +341,9 @@ Schedules are stored in the `cf_agents_schedules` SQL table. Cron schedules auto
 class MyAgent extends Agent {
   async onConnect() {
     // Add an MCP server
-    await this.addMcpServer(
-      "GitHub",
-      "https://mcp.example.com/mcp",
-      "https://my-worker.example.workers.dev", // callback host for OAuth
-      "agents" // routing prefix
-    );
+    await this.addMcpServer("GitHub", "https://mcp.example.com/sse", {
+      callbackHost: "https://my-worker.example.workers.dev"
+    });
   }
 }
 ```
@@ -361,15 +358,10 @@ class MyAgent extends Agent {
     console.log("Received email from:", email.from);
     console.log("Subject:", email.headers.get("subject"));
 
-    const raw = await email.getRaw();
-    console.log("Raw email size:", raw.length);
-
     // Reply to the email
     await this.replyToEmail(email, {
       fromName: "My Agent",
-      subject: "Re: " + email.headers.get("subject"),
-      body: "Thanks for your email!",
-      contentType: "text/plain"
+      body: "Thanks for your email!"
     });
   }
 }
@@ -387,6 +379,8 @@ export default {
 };
 ```
 
+For more details on email routing, resolvers, secure reply flows, and the full API, refer to the [Email Routing guide](/agents/guides/email/).
+
 ### Context Management
 
 `agents` wraps all your methods with an `AsyncLocalStorage` to maintain context throughout the request lifecycle. This allows you to access the current agent, connection, request, or email (depending of what event is being handled) from anywhere in your code: