unique partial

Author: elithrar

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

@@ -30,6 +30,8 @@ An Agent can have many (millions of) instances: each instance is a separate micr
 
 Instances of an Agent are addressed by a unique identifier: that identifier (ID) can be the user ID, an email address, GitHub username, a flight ticket number, an invoice ID, or any other identifier that helps to uniquely identify the instance and for whom it is acting on behalf of.
 
+<Render file="unique-agents" />
+
 ### Agent
 
 Writing an Agent requires you to define a class that extends the `Agent` class from the `agents-sdk` package. An Agent encapsulates all of the logic for an Agent, including how clients can connect to it, how it stores state, the methods it exposes, and any error handling.

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

@@ -14,6 +14,8 @@ Learn how to call your Agents from Workers, including how to create Agents on-th
 
 Agents are created on-the-fly and can serve multiple requests concurrently. Each Agent instance is isolated from other instances, can maintain its own state, and has a unique address.
 
+<Render file="unique-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.

src/content/docs/agents/getting-started/quickstart.mdx

@@ -39,6 +39,14 @@ Inside this directory, there are a number of files, but we only need to worry ab
 
 Let's take a look at how the Agent in the quick start is defined.
 
+:::note[Escape hatch]
+
+You can escape from the rest of this quickstart guide right here: run `npm run start` to run the code locally, open `src/index.ts` to explore the code, and run `npx wrangler@latest deploy` to deploy it your Cloudflare account.
+
+The rest of this quickstart briefly steps through the code and sending requests to the Agent: if this is your first time using the Agents SDK and/or Cloudflare Workers, you'll likely want to keep reading.
+
+:::
+
 ### Understand the Agent class
 
 Open the `src/index.ts` file in your editor:
@@ -71,33 +79,23 @@ Your Agent is now running locally on your machine, and ready to communicate with
 
 ### Communicate with your Agent
 
-Let's communicate with your Agent and have it run a simple task.
+Let's communicate with your Agent and have it book us a flight (well, pretend to).
 
-The example Agent in this quick start project exposes both HTTP and WebSocket endpoints, and so we'll use [`wscat`](https://github.com/websockets/wscat) as a command-line WebSocket client to communicate with our Agent's chat endpoint.
-
-Install `wscat`:
-
-```sh
-npm install -g wscat
-```
-
-Run `wscat` and connect to an instance of your Agent (running locally). Remember that each Agent can have many _instances_, each able to interact with users, tools and other APIs independently, as well as store state specific to that instance.
-
-```sh
-# The code in this project will automatically create a new Agent on-the-fly when
-# you provide a name: e.g. /agents/my-agent/foo or /agents/my-agent/user-1238139
-# This allows you to create as many Agents as you want, each with their own
-# state and able to manage their own tasks.
-wscat --connect "ws://localhost:8787/agents/my-agent/abc123def"
-```
+TODO:
 
+- Make a request for a booking
+- get a response
+- confirm the booking
+- get the booked flight
 
 
 #### Agent routing
 
 In the `agents-quick-start` we use the `routeAgentRequest` helper to automatically handle routing to existing and creating new Agent instances on-the-fly.
 
-If you open up `src/index.ts`,
+If you open up `src/index.ts`, you'll see that `routeAgentRequest` handles requests to `/agents/:agent/:name` - in our case, that's `/agents/flight-agent/:name`, where name is a unique identifier for that Agent instance.
+
+<Render file="unique-agents" />
 
 <TypeScriptExample filename="src/index.ts">
 
@@ -117,7 +115,7 @@ export default {
 
 </TypeScriptExample>
 
-You can learn about more ways to call into your Agents, as well as how to add authentication in front of your Agents, by reviewing [documentation on Calling Agents](/agents/api-reference/calling-agents/).
+You can learn about more ways to call into your Agents, as well as how to add authentication in front of your Agents, by reviewing the [documentation on calling Agents](/agents/api-reference/calling-agents/).
 
 ### Ship to production
 

src/content/partials/agents/unique-agents.mdx

@@ -0,0 +1,12 @@
+---
+{}
+
+---
+
+:::note
+
+An instance of an Agent is globally unique: given the same name (or ID), you will always get the same instance of an agent. This means that you don't have to synchronize state across requests: if an Agent instance represents a specific user, team, channel or other entity, you can use the Agent instance to store state for that entity.
+
+If the client disconnects, you can always route the client back to the exact same Agent and pick up where they left off.
+
+:::