AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

agents-sdk

Build, debug, or review Cloudflare Agents SDK applications using the agents package.

Original source
cloudflare
License
Apache-2.0
Pinned revision
e44f580f9c4fa3bf268e284ae7706c7954ba31fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read cloudflare--agents-sdk at revision e44f580f9c4fa3bf268e284ae7706c7954ba31fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 21

references/routing.md

Routing

Fetch https://developers.cloudflare.com/agents/runtime/communication/routing/index.md for complete documentation.

Default URL Pattern

/agents/{kebab-class-name}/{instance-name}

import { routeAgentRequest } from "agents";

export default {
  fetch: (req, env) =>
    routeAgentRequest(req, env) ?? new Response("Not found", { status: 404 })
};

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

Subpaths after the instance name (e.g. /agents/my-agent/default/api/data) route to onRequest.

Custom Routing with getAgentByName

import { getAgentByName } from "agents";

export default {
  async fetch(req, env) {
    const url = new URL(req.url);
    if (url.pathname.startsWith("/api/")) {
      const agent = getAgentByName(env.MyAgent, "singleton");
      return agent.fetch(req);
    }
    return routeAgentRequest(req, env);
  }
};

Options

routeAgentRequest(req, env, {
  cors: true,
  prefix: "/api/agents",
  locationHint: "enam",
  jurisdiction: "eu",
  props: { userId: "123" },
  onBeforeConnect: async (req) => { /* auth check */ },
  onBeforeRequest: async (req) => { /* auth check */ }
});

props are delivered to onStart(props) on first access.

Client Side

useAgent({
  agent: "MyAgent",
  name: "instance-1",
  host: "https://my-worker.workers.dev",
  basePath: "/api/agents",
  path: "/custom-subpath"
});

Common Mistakes

  • Class name MyAgent becomes kebab my-agent in URLs — match exactly
  • "Namespace not found" error = the class_name in wrangler doesn't match your exported class
  • If sendIdentityOnConnect: false, the ready promise on the client may never resolve — use state sync instead