calling agents

Author: elithrar

src/content/docs/agents/api-reference/calling-agents.mdx

@@ -0,0 +1,87 @@
+---
+title: Calling Agents
+pcx_content_type: concept
+sidebar:
+  order: 2
+
+---
+
+import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
+
+This page shows you how to call your Agents from Workers, including approaches for how to address and route requests to Agents.
+
+## Calling your Agent
+
+TODO:
+
+- created on the fly
+- retrieved if exists
+- naming
+
+You can create and run an instance of an Agent directly from a Worker in one of three ways:
+
+1. Using the `routeAgentRequest` helper: this will automatically map requests to an individual Agent based on the `/agents/:agent/:name` URL pattern. The value of `:agent` will be the name of your Agent class converted to `kebab-case`, and the value of `:name` will be the name of the Agent instance you want to create or retrieve.
+2. Calling `getAgentByName`, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.
+3. The [Durable Objects stub API](/durable-objects/api/id/), which provides a lower level API for creating and retrieving Agents.
+
+These three patterns are shown below: we recommend using either `routeAgentRequest` or `getAgentByName`, which help avoid some boilerplate.
+
+<TypeScriptExample>
+
+```ts
+import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from 'agents-sdk';
+
+interface Env {
+	// Define your Agent on the environment here
+	// Passing your Agent class as a TypeScript type parameter allows you to call
+	// methods defined on your Agent.
+	MyAgent: AgentNamespace<MyAgent>;
+}
+
+export default {
+	async fetch(request, env, ctx): Promise<Response> {
+		// Routed addressing
+		// Automatically routes HTTP requests and/or WebSocket connections to /agents/:agent/:name
+		// Best for: connecting React apps directly to Agents using useAgent from agents-sdk/react
+		(await routeAgentRequest(request, env)) || Response.json({ msg: 'no agent here' }, { status: 404 });
+
+		// Named addressing
+		// Best for: convenience method for creating or retrieving an agent by name/ID.
+		let namedAgent = getAgentByName<Env, MyAgent>(env.MyAgent, 'my-unique-agent-id');
+		// Pass the incoming request straight to your Agent
+		let namedResp = (await namedAgent).fetch(request);
+
+		// Durable Objects-style addressing
+		// Best for: controlling ID generation, associating IDs with your existing systems,
+		// and customizing when/how an Agent is created or invoked
+		const id = env.MyAgent.newUniqueId();
+		const agent = env.MyAgent.get(id);
+		// Pass the incoming request straight to your Agent
+		let resp = await agent.fetch(request);
+
+		return Response.json({ hello: 'visit https://developers.cloudflare.com/agents for more' });
+	},
+} satisfies ExportedHandler<Env>;
+
+export class MyAgent extends Agent<Env> {
+	// Your Agent implementation goes here
+}
+```
+</TypeScriptExample>
+
+### Naming your Agents
+
+TODO:
+
+- naming strategies
+- how to address them directly
+- validating names before you route to an agent
+- `this.name`
+
+
+
+### Next steps
+
+* [Build a chat Agent](/agents/getting-started/build-a-chat-agent/) using the `agents-sdk` and deploy it to Workers.
+* Learn more [using WebSockets](/agents/api-reference/websockets/) to build interactive Agents and stream data back from your Agent.
+* [Orchestrate asynchronous workflows](/agents/api-reference/run-workflows) from your Agent by combining the `agents-sdk` and [Workflows](/workflows).

src/content/docs/agents/api-reference/sdk.mdx

@@ -471,58 +471,7 @@ To learn more about how to manage state within an Agent, refer to the documentat
 
 :::
 
-## Routing to Agents
 
-You can create and run an instance of an Agent directly from a Worker in one of three ways:
-
-1. Using the `routeAgentRequest` helper: this will automatically map requests to an individual Agent based on the `/agents/:agent/:name` URL pattern. The value of `:agent` will be the name of your Agent class converted to `kebab-case`, and the value of `:name` will be the name of the Agent instance you want to create or retrieve.
-2. Calling `getAgentByName`, which will create a new Agent instance if none exists by that name, or retrieve a handle to an existing instance.
-3. The [Durable Objects stub API](/durable-objects/api/id/), which provides a lower level API for creating and retrieving Agents.
-
-These three patterns are shown below: we recommend using either `routeAgentRequest` or `getAgentByName`, which help avoid some boilerplate.
-
-<TypeScriptExample>
-
-```ts
-import { Agent, AgentNamespace, getAgentByName, routeAgentRequest } from 'agents-sdk';
-
-interface Env {
-	// Define your Agent on the environment here
-	// Passing your Agent class as a TypeScript type parameter allows you to call
-	// methods defined on your Agent.
-	MyAgent: AgentNamespace<MyAgent>;
-}
-
-export default {
-	async fetch(request, env, ctx): Promise<Response> {
-		// Routed addressing
-		// Automatically routes HTTP requests and/or WebSocket connections to /agents/:agent/:name
-		// Best for: connecting React apps directly to Agents using useAgent from agents-sdk/react
-		(await routeAgentRequest(request, env)) || Response.json({ msg: 'no agent here' }, { status: 404 });
-
-		// Named addressing
-		// Best for: convenience method for creating or retrieving an agent by name/ID.
-		let namedAgent = getAgentByName<Env, MyAgent>(env.MyAgent, 'my-unique-agent-id');
-		// Pass the incoming request straight to your Agent
-		let namedResp = (await namedAgent).fetch(request);
-
-		// Durable Objects-style addressing
-		// Best for: controlling ID generation, associating IDs with your existing systems,
-		// and customizing when/how an Agent is created or invoked
-		const id = env.MyAgent.newUniqueId();
-		const agent = env.MyAgent.get(id);
-		// Pass the incoming request straight to your Agent
-		let resp = await agent.fetch(request);
-
-		return Response.json({ hello: 'visit https://developers.cloudflare.com/agents for more' });
-	},
-} satisfies ExportedHandler<Env>;
-
-export class MyAgent extends Agent<Env> {
-	// Your Agent implementation goes here
-}
-```
-</TypeScriptExample>
 
 
 ### Next steps