> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cloudflare/agents/llms.txt
> Use this file to discover all available pages before exploring further.

# Routing

> How requests are routed to agents, naming patterns, and URL structures

This guide explains how requests are routed to agents, how naming works, and patterns for organizing your agents.

## How Routing Works

When a request comes in, `routeAgentRequest()` examines the URL and routes it to the appropriate agent instance:

```
https://your-worker.dev/agents/{agent-name}/{instance-name}
                              └─────┬─────┘ └─────┬──────┘
                            Class name      Unique instance ID
                            (kebab-case)
```

**Example URLs:**

| URL                        | Agent Class | Instance   |
| -------------------------- | ----------- | ---------- |
| `/agents/counter/user-123` | `Counter`   | `user-123` |
| `/agents/chat-room/lobby`  | `ChatRoom`  | `lobby`    |
| `/agents/my-agent/default` | `MyAgent`   | `default`  |

## Name Resolution

Agent class names are automatically converted to kebab-case for URLs:

| Class Name    | URL Path                   |
| ------------- | -------------------------- |
| `Counter`     | `/agents/counter/...`      |
| `MyAgent`     | `/agents/my-agent/...`     |
| `ChatRoom`    | `/agents/chat-room/...`    |
| `AIAssistant` | `/agents/ai-assistant/...` |

The router matches both the original name and kebab-case version, so these all work:

* `useAgent({ agent: "Counter" })` → `/agents/counter/...`
* `useAgent({ agent: "counter" })` → `/agents/counter/...`

## Basic Usage

### routeAgentRequest()

The main entry point for agent routing. Handles both HTTP requests and WebSocket upgrades:

```typescript theme={null}
import { routeAgentRequest } from "agents";

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    // Route to agents - returns Response or undefined
    const agentResponse = await routeAgentRequest(request, env);

    if (agentResponse) {
      return agentResponse;
    }

    // No agent matched - handle other routes
    return new Response("Not found", { status: 404 });
  }
};
```

### getAgentByName()

Get a specific agent instance for server-side RPC calls or request forwarding:

```typescript theme={null}
import { getAgentByName, routeAgentRequest } from "agents";

export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    // API endpoint that interacts with an agent
    if (url.pathname === "/api/increment") {
      const counter = await getAgentByName(env.Counter, "global-counter");
      const newCount = await counter.increment();
      return Response.json({ count: newCount });
    }

    // Regular agent routing
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};
```

## Instance Naming Patterns

The instance name (the last part of the URL) determines which agent instance handles the request. Each unique name gets its own isolated agent with its own state.

### Per-User Agents

Each user gets their own agent instance:

```typescript theme={null}
// Client
const agent = useAgent({
  agent: "UserProfile",
  name: `user-${userId}` // e.g., "user-abc123"
});
```

```
/agents/user-profile/user-abc123  → User abc123's agent
/agents/user-profile/user-xyz789  → User xyz789's agent (separate instance)
```

### Shared Rooms

Multiple users share the same agent instance:

```typescript theme={null}
// Client
const agent = useAgent({
  agent: "ChatRoom",
  name: roomId // e.g., "general" or "room-42"
});
```

```
/agents/chat-room/general  → All users in "general" share this agent
```

### Global Singleton

A single instance for the entire application:

```typescript theme={null}
// Client
const agent = useAgent({
  agent: "AppConfig",
  name: "default" // Or any consistent name
});
```

### Dynamic Naming

Generate instance names based on context:

```typescript theme={null}
// Per-session
const agent = useAgent({
  agent: "Session",
  name: sessionId
});

// Per-document
const agent = useAgent({
  agent: "Document",
  name: `doc-${documentId}`
});

// Per-game
const agent = useAgent({
  agent: "Game",
  name: `game-${gameId}-${Date.now()}`
});
```

## Routing Options

Both `routeAgentRequest()` and `getAgentByName()` accept options for customizing routing behavior.

### CORS

For cross-origin requests (common when your frontend is on a different domain):

<CodeGroup>
  ```typescript Default CORS theme={null}
  const response = await routeAgentRequest(request, env, {
    cors: true // Enable default CORS headers
  });
  ```

  ```typescript Custom CORS theme={null}
  const response = await routeAgentRequest(request, env, {
    cors: {
      "Access-Control-Allow-Origin": "https://myapp.com",
      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
      "Access-Control-Allow-Headers": "Content-Type, Authorization"
    }
  });
  ```
</CodeGroup>

### Location Hints

For latency-sensitive applications, hint where the agent should run:

```typescript theme={null}
// With getAgentByName
const agent = await getAgentByName(env.MyAgent, "instance-name", {
  locationHint: "enam" // Eastern North America
});

// With routeAgentRequest (applies to all matched agents)
const response = await routeAgentRequest(request, env, {
  locationHint: "enam"
});
```

Available location hints: `wnam`, `enam`, `sam`, `weur`, `eeur`, `apac`, `oc`, `afr`, `me`

### Jurisdiction

For data residency requirements:

```typescript theme={null}
// With getAgentByName
const agent = await getAgentByName(env.MyAgent, "instance-name", {
  jurisdiction: "eu" // EU jurisdiction
});

// With routeAgentRequest (applies to all matched agents)
const response = await routeAgentRequest(request, env, {
  jurisdiction: "eu"
});
```

### Props

Since agents are instantiated by the runtime rather than constructed directly, `props` provides a way to pass initialization arguments:

```typescript theme={null}
const agent = await getAgentByName(env.MyAgent, "instance-name", {
  props: {
    userId: session.userId,
    config: { maxRetries: 3 }
  }
});
```

Props are passed to the agent's `onStart` lifecycle method:

```typescript theme={null}
class MyAgent extends Agent<Env, State> {
  private userId?: string;
  private config?: { maxRetries: number };

  async onStart(props?: { userId: string; config: { maxRetries: number } }) {
    this.userId = props?.userId;
    this.config = props?.config;
  }
}
```

<Note>
  For `McpAgent`, props are automatically stored and accessible via `this.props`.
</Note>

### Hooks

`routeAgentRequest` supports hooks for intercepting requests before they reach agents:

```typescript theme={null}
const response = await routeAgentRequest(request, env, {
  onBeforeConnect: (req, lobby) => {
    // Called before WebSocket connections
    // Return a Response to reject, Request to modify, or void to continue
  },
  onBeforeRequest: (req, lobby) => {
    // Called before HTTP requests
    // Return a Response to reject, Request to modify, or void to continue
  }
});
```

## Custom URL Routing

For advanced use cases where you need control over the URL structure, you can bypass the default `/agents/{agent}/{name}` pattern.

### Using basePath (Client-Side)

The `basePath` option lets clients connect to any URL path:

```typescript theme={null}
// Client connects to /user instead of /agents/user-agent/...
const agent = useAgent({
  agent: "UserAgent", // Required but ignored when basePath is set
  basePath: "user" // → connects to /user
});
```

This is useful when:

* You want clean URLs without the `/agents/` prefix
* The instance name is determined server-side (e.g., from auth/session)
* You're integrating with an existing URL structure

### Server-Side Instance Selection

When using `basePath`, the server must handle routing:

```typescript theme={null}
export default {
  async fetch(request: Request, env: Env) {
    const url = new URL(request.url);

    // Custom routing - server determines instance from session
    if (url.pathname === "/user") {
      const session = await getSession(request);
      const agent = await getAgentByName(env.UserAgent, session.userId);
      return agent.fetch(request); // Forward request directly to agent
    }

    // Default routing for standard /agents/... paths
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};
```

### Receiving the Instance Identity (Client-Side)

When using `basePath`, the client doesn't know which instance it connected to until the server tells it:

```typescript theme={null}
const agent = useAgent({
  agent: "UserAgent",
  basePath: "user",
  onIdentity: (name, agentType) => {
    console.log(`Connected to ${agentType} instance: ${name}`);
  }
});

// Reactive state - re-renders when identity is received
return (
  <div>
    {agent.identified ? `Connected to: ${agent.name}` : "Connecting..."}
  </div>
);
```

## Multiple Agents

You can have multiple agent classes in one project. Each gets its own namespace:

```typescript theme={null}
// server.ts
export { Counter } from "./agents/counter";
export { ChatRoom } from "./agents/chat-room";
export { UserProfile } from "./agents/user-profile";

export default {
  async fetch(request: Request, env: Env) {
    return (
      (await routeAgentRequest(request, env)) ??
      new Response("Not found", { status: 404 })
    );
  }
};
```

```jsonc wrangler.jsonc theme={null}
{
  "durable_objects": {
    "bindings": [
      { "name": "Counter", "class_name": "Counter" },
      { "name": "ChatRoom", "class_name": "ChatRoom" },
      { "name": "UserProfile", "class_name": "UserProfile" }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["Counter", "ChatRoom", "UserProfile"]
    }
  ]
}
```

Each agent is accessed via its own path:

```
/agents/counter/...
/agents/chat-room/...
/agents/user-profile/...
```

## Troubleshooting

### "Agent namespace not found"

The error message lists available agents. Check:

1. Agent class is exported from your entry point
2. Class name in code matches `class_name` in `wrangler.jsonc`
3. URL uses correct kebab-case name

### Request returns 404

1. Verify the URL pattern: `/agents/{agent-name}/{instance-name}`
2. Check that `routeAgentRequest()` is called before your 404 handler
3. Ensure the response from `routeAgentRequest()` is returned (not just called)

### WebSocket won't connect

1. Don't modify the response from `routeAgentRequest()` for WebSocket upgrades
2. Ensure CORS is enabled if connecting from a different origin
3. Check browser dev tools for the actual error

### basePath not working

1. Ensure your Worker handles the custom path and forwards to the agent
2. Use `getAgentByName()` + `agent.fetch(request)` to forward requests
3. The `agent` parameter is still required but ignored when `basePath` is set
4. Check that the server-side route matches the client's `basePath`

## API Reference

### routeAgentRequest(request, env, options?)

Routes a request to the appropriate agent.

<ParamField path="request" type="Request" required>
  The incoming request
</ParamField>

<ParamField path="env" type="Env" required>
  Environment with agent bindings
</ParamField>

<ParamField path="options.cors" type="boolean | HeadersInit">
  Enable CORS headers
</ParamField>

<ParamField path="options.props" type="Record<string, unknown>">
  Props passed to whichever agent handles the request
</ParamField>

<ParamField path="options.locationHint" type="string">
  Preferred location for agent instances
</ParamField>

<ParamField path="options.jurisdiction" type="string">
  Data jurisdiction for agent instances
</ParamField>

<ParamField path="options.onBeforeConnect" type="Function">
  Callback before WebSocket connections
</ParamField>

<ParamField path="options.onBeforeRequest" type="Function">
  Callback before HTTP requests
</ParamField>

**Returns:** `Promise<Response | undefined>` - Response if matched, undefined if no agent route

### getAgentByName(namespace, name, options?)

Get an agent instance by name for server-side RPC or request forwarding.

<ParamField path="namespace" type="DurableObjectNamespace<T>" required>
  Agent binding from env
</ParamField>

<ParamField path="name" type="string" required>
  Instance name
</ParamField>

<ParamField path="options.locationHint" type="string">
  Preferred location
</ParamField>

<ParamField path="options.jurisdiction" type="string">
  Data jurisdiction
</ParamField>

<ParamField path="options.props" type="Record<string, unknown>">
  Initialization properties for `onStart`
</ParamField>

**Returns:** `Promise<DurableObjectStub<T>>` - Typed stub for calling agent methods or forwarding requests