1# Configuration
2 
3## Wrangler Setup
4 
5```jsonc
6{
7  "name": "my-agents-app",
8  "durable_objects": {
9    "bindings": [
10      {"name": "MyAgent", "class_name": "MyAgent"}
11    ]
12  },
13  "migrations": [
14    {"tag": "v1", "new_sqlite_classes": ["MyAgent"]}
15  ],
16  "ai": {
17    "binding": "AI"
18  }
19}
20```
21 
22## Environment Bindings
23 
24**Type-safe pattern:**
25 
26```typescript
27interface Env {
28  AI?: Ai;                              // Workers AI
29  MyAgent?: DurableObjectNamespace<MyAgent>;
30  ChatAgent?: DurableObjectNamespace<ChatAgent>;
31  DB?: D1Database;                      // D1 database
32  KV?: KVNamespace;                     // KV storage
33  R2?: R2Bucket;                        // R2 bucket
34  OPENAI_API_KEY?: string;              // Secrets
35  GITHUB_CLIENT_ID?: string;            // MCP OAuth credentials
36  GITHUB_CLIENT_SECRET?: string;
37  QUEUE?: Queue;                        // Queues
38}
39```
40 
41**Best practice:** Define all DO bindings in Env interface for type safety.
42 
43## Deployment
44 
45```bash
46# Local dev
47npx wrangler dev
48 
49# Deploy production
50npx wrangler deploy
51 
52# Set secrets
53npx wrangler secret put OPENAI_API_KEY
54```
55 
56## Agent Routing
57 
58**Recommended: Use route helpers**
59 
60```typescript
61import { routeAgentRequest } from "agents";
62 
63export default {
64  fetch(request: Request, env: Env) {
65    return routeAgentRequest(request, env);
66  }
67}
68```
69 
70Helper routes requests to agents automatically based on URL patterns.
71 
72**Manual routing (advanced):**
73 
74```typescript
75export default {
76  async fetch(request: Request, env: Env) {
77    const url = new URL(request.url);
78    
79    // Named ID (deterministic)
80    const id = env.MyAgent.idFromName("user-123");
81    
82    // Random ID (from URL param)
83    // const id = env.MyAgent.idFromString(url.searchParams.get("id"));
84    
85    const stub = env.MyAgent.get(id);
86    return stub.fetch(request);
87  }
88}
89```
90 
91**Multi-agent setup:**
92 
93```typescript
94import { routeAgentRequest } from "agents";
95 
96export default {
97  fetch(request: Request, env: Env) {
98    const url = new URL(request.url);
99    
100    // Route by path
101    if (url.pathname.startsWith("/chat")) {
102      return routeAgentRequest(request, env, "ChatAgent");
103    }
104    if (url.pathname.startsWith("/task")) {
105      return routeAgentRequest(request, env, "TaskAgent");
106    }
107    
108    return new Response("Not found", { status: 404 });
109  }
110}
111```
112 
113## Email Routing
114 
115**Code setup:**
116 
117```typescript
118import { routeAgentEmail } from "agents";
119 
120export default {
121  fetch: (req: Request, env: Env) => routeAgentRequest(req, env),
122  email: (message: ForwardableEmailMessage, env: Env) => {
123    return routeAgentEmail(message, env);
124  }
125}
126```
127 
128**Dashboard setup:**
129 
130Configure email routing in Cloudflare dashboard:
131 
132```
133Destination: Workers with Durable Objects
134Worker: my-agents-app
135```
136 
137Then handle in agent:
138 
139```typescript
140export class EmailAgent extends Agent<Env> {
141  async onEmail(email: AgentEmail) {
142    const text = await email.text();
143    // Process email
144  }
145}
146```
147 
148## AI Gateway (Optional)
149 
150```typescript
151// Enable caching/routing through AI Gateway
152const response = await this.env.AI.run(
153  "@cf/meta/llama-3.1-8b-instruct",
154  { prompt },
155  {
156    gateway: {
157      id: "my-gateway-id",
158      skipCache: false,
159      cacheTtl: 3600
160    }
161  }
162);
163```
164 
165## MCP Configuration (Optional)
166 
167For exposing tools via Model Context Protocol:
168 
169```typescript
170// wrangler.jsonc - Add MCP OAuth secrets
171{
172  "vars": {
173    "MCP_SERVER_URL": "https://mcp.example.com"
174  }
175}
176 
177// Set secrets via CLI
178// npx wrangler secret put GITHUB_CLIENT_ID
179// npx wrangler secret put GITHUB_CLIENT_SECRET
180```
181 
182Then register in agent code (see api.md MCP section).
183