Add Agent class internals documentation

Synced from cloudflare/agents PR #636

This adds comprehensive documentation explaining the internal architecture
of the Agent class, including its layered structure (DurableObject -> Server -> Agent)
and detailed explanations of all core features and APIs.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: claude

src/content/docs/agents/concepts/agent-class.mdx

@@ -1,29 +1,27 @@
 ---
-title: Understanding the Agent class
+title: Agent class internals
 pcx_content_type: concept
 sidebar:
-  order: 10
+  order: 5
 ---
 
-import { Render } from "~/components";
+The core of the `agents` library is the exported `Agent` class. Following the pattern from [Durable Objects](/durable-objects/api/), the main API for developers is to extend the `Agent` so those classes inherit all the built-in features. While this effectively is a supercharged primitive that allows developers to only write the logic they need in their agents, it obscures the inner workings.
 
-The core of the `agents` library is the exported `Agent` class. Following the pattern from [Durable Objects](/durable-objects/api/), the main API for developers is to extend the `Agent` class so those classes inherit all the built-in features. While this effectively is a supercharged primitive that allows developers to only write the logic they need in their agents, it obscures the inner workings.
+This document tries to bridge that gap, empowering any developer aiming to get started writing agents to get the full picture and avoid common pitfalls. The snippets shown here are primarily illustrative and don't necessarily represent best practices. For a more in-depth look at the inner workings of the `Agent` class, check out the [API reference](/agents/api-reference/) and the [source code](https://github.com/cloudflare/agents/blob/main/packages/agents/src/index.ts).
 
-This document tries to bridge that gap, empowering any developer aiming to get started writing agents to get the full picture and avoid common pitfalls. The snippets shown here are primarily illustrative and don't necessarily represent best practices.
-
-## What is the Agent class?
+## What is the Agent?
 
 The `Agent` class is an extension of `DurableObject`. That is to say, they _are_ **Durable Objects**. If you're not familiar with Durable Objects, it is highly recommended that you read [What are Durable Objects](/durable-objects/) but at their core, Durable Objects are globally addressable (each instance has a unique ID) single-threaded compute instances with long term storage (KV/SQLite).
 
 That being said, `Agent` does **not** extend `DurableObject` directly but instead `Server`. `Server` is a class provided by [PartyKit](https://github.com/cloudflare/partykit/tree/main/packages/partyserver).
 
-You can visualize the logic as a Matryoshka doll: **DurableObject** → **Server** → **Agent**.
+You can visualize the logic as a Matryoshka doll: **DurableObject** -> **Server** -> **Agent**.
 
 ## Layer 0: Durable Object
 
 This won't cover Durable Objects in detail, but it's good to know what primitives they expose so we understand how the outer layers make use of them. The Durable Object class comes with:
 
-### constructor
+### `constructor`
 
 ```ts
 constructor(ctx: DurableObjectState, env: Env) {}
@@ -48,7 +46,7 @@ const stub = env.MY_DO.getByName("foo");
 await stub.bar();
 ```
 
-### fetch()
+### `fetch()`
 
 Durable Objects can take a `Request` from a Worker and send a `Response` back. This can **only** be done through the [`fetch`](/durable-objects/best-practices/create-durable-object-stubs-and-send-requests/#invoking-the-fetch-handler) method (which the developer must implement).
 
@@ -81,17 +79,17 @@ export class MyDurableObject extends DurableObject {
 }
 ```
 
-### alarm()
+### `alarm()`
 
-HTTP and RPC requests are not the only entrypoints for a DO. Alarms allow developers to schedule tasks to run at a later time. Whenever the runtime knows an alarm is due, it will call the `alarm()` method, which is left to the developer to implement.
+HTTP and RPC requests are not the only entrypoints for a DO. Alarms allow developers to schedule an event to trigger at a later time. Whenever the next alarm is due, the runtime will call the `alarm()` method, which is left to the developer to implement.
 
 To schedule an alarm, you can use the `this.ctx.storage.setAlarm()` method. For more information, refer to [Alarms](/durable-objects/api/alarms/).
 
-### this.ctx
+### `this.ctx`
 
 The base `DurableObject` class sets the [DurableObjectState](/durable-objects/api/state/) into `this.ctx`. There are a lot of interesting methods and properties, but we'll focus on `this.ctx.storage`.
 
-### this.ctx.storage
+### `this.ctx.storage`
 
 [DurableObjectStorage](/durable-objects/api/sqlite-storage-api/) is the main interface with the DO's persistence mechanisms, which include both a KV and SQLITE **synchronous** APIs.
 
@@ -106,15 +104,15 @@ const rows = sql.exec("SELECT * FROM contacts WHERE country = ?", "US");
 const token = kv.get("someToken");
 ```
 
-### this.ctx.env
+### `this.ctx.env`
 
-Lastly, it's worth mentioning that the DO also has the Worker `Env` in `this.env`. Read more about [bindings](/workers/runtime-apis/bindings).
+Lastly, it's worth mentioning that the DO also has the Worker `Env` in `this.env`. Read more in [Bindings](/workers/runtime-apis/bindings).
 
-## Layer 1: PartyKit Server
+## Layer 1: Partykit `Server`
 
 Now that you've seen what Durable Objects come with out-of-the-box, what [PartyKit](https://github.com/cloudflare/partykit)'s `Server` (package `partyserver`) implements will be clearer. It's an **opinionated `DurableObject` wrapper that improves DX by hiding away DO primitives in favor of more developer friendly callbacks**.
 
-An important note is that `Server` **does NOT make use any of the DO storage** so you will not see extra operations.
+An important note is that `Server` **does NOT persist to the DO storage** so you will not see extra storage operations by using it.
 
 ### Addressing
 
@@ -133,20 +131,20 @@ await stub.bar();
 Since we have a URL addressing scheme, we also get access to `routePartykitRequest()`.
 
 ```ts
-async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-  // Behind the scenes, PartyKit normalizes your DO binding names
-  // and tries to do some pattern matching.
-  const res = await routePartykitRequest(request, env);
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    // Behind the scenes, PartyKit normalizes your DO binding names
+    // and tries to do some pattern matching.
+    const res = await routePartykitRequest(request, env);
 
-  if (res) return res;
+    if (res) return res;
 
-  return Response("Not found", { status: 404 });
-}
+    return Response("Not found", { status: 404 });
+  }
 ```
 
 You can have a look at [the implementation](https://github.com/cloudflare/partykit/blob/main/packages/partyserver/src/index.ts#L122) if you're interested.
 
-### onStart
+### `onStart`
 
 The extra plumbing that `Server` includes on addressing allows it to expose an `onStart` callback that is **executed every time the DO starts up** (the DO was evicted, hibernated or never created at all) and **before any `fetch` or RPC**.
 
@@ -161,7 +159,7 @@ class MyServer extends Server {
 }
 ```
 
-### onRequest and onConnect
+### `onRequest` and `onConnect`
 
 `Server` already implements `fetch` for the underlying Durable Object and exposes 2 different callbacks that developers can make use of, `onRequest` and `onConnect` for HTTP requests and incoming WS connections, respectively (**WebSocket connections are accepted by default**).
 
@@ -189,15 +187,15 @@ Just as `onConnect` is the callback for every new connection, `Server` also prov
 
 There's also `this.broadcast` that sends a WS message to all connected clients (no magic, just a loop over `this.getConnections()`!).
 
-### this.name
+### `this.name`
 
-It's hard to get a Durable Object's `name` from within it. `partyserver` tries to make it available in `this.name` but it's not a perfect solution. Read more about it [here](https://github.com/cloudflare/workerd/issues/2240).
+It's hard to get a Durable Object's `name` from within it. `partyserver` tries to make it available in `this.name` but it's not a perfect solution. Read more about it in [this GitHub issue](https://github.com/cloudflare/workerd/issues/2240).
 
 ## Layer 2: Agent
 
 Now finally, the `Agent` class. `Agent` extends `Server` and provides opinionated primitives for stateful, schedulable, and observable agents that can communicate via RPC, WebSockets, and (even!) email.
 
-### this.state and this.setState()
+### `this.state` and `this.setState()`
 
 One of the core features of `Agent` is **automatic state persistence**. Developers define the shape of their state via the generic parameter and `initialState` (which is only used if no state exists in storage), and the Agent handles loading, saving, and broadcasting state changes (check `Server`'s `this.broadcast()` above).
 
@@ -221,7 +219,7 @@ class MyAgent extends Agent<Env, { count: number }> {
 
 State is stored in the `cf_agents_state` SQL table. State messages are sent with `type: "cf_agent_state"` (both from the client and the server). Since the `agents` provides [JS and React clients](/agents/api-reference/store-and-sync-state/#synchronizing-state), real-time state updates are available out of the box.
 
-### this.sql
+### `this.sql`
 
 The Agent provides a convenient `sql` template tag for executing queries against the Durable Object's SQL storage. It constructs parameterized queries and executes them. This uses the **synchronous** SQL API from `this.ctx.storage.sql`.
 
@@ -249,7 +247,7 @@ class MyAgent extends Agent {
 
 ### RPC and Callable Methods
 
-`agents` take Durable Objects RPC one step forward by implementing RPC through WebSockets, so clients can also call methods on the Agent directly. To make a method callable, developers can use the `@callable` decorator. Methods can return a serializable value or a stream (when using `@callable({ stream: true })`).
+`agents` take Durable Objects RPC one step forward by implementing RPC through WebSockets, so clients can also call methods on the Agent directly. To make a method callable through WS, developers can use the `@callable` decorator. Methods can return a serializable value or a stream (when using `@callable({ stream: true })`).
 
 ```ts
 class MyAgent extends Agent {
@@ -279,7 +277,7 @@ const result = await stub.add(2, 3);
 console.log(result); // 5
 ```
 
-### this.queue and friends
+### `this.queue` and friends
 
 Agents include a built-in task queue for deferred execution. This is useful for offloading work or retrying operations. The available methods are `this.queue`, `this.dequeue`, `this.dequeueAll`, `this.dequeueAllByCallback`, `this.getQueue`, and `this.getQueues`.
 
@@ -298,13 +296,15 @@ class MyAgent extends Agent {
 
 Tasks are stored in the `cf_agents_queues` SQL table and are automatically flushed in sequence. If a task succeeds, it's automatically dequeued.
 
-### this.schedule and friends
+### `this.schedule` and friends
 
 Agents support scheduled execution of methods by wrapping the Durable Object's `alarm()`. The available methods are `this.schedule`, `this.getSchedule`, `this.getSchedules`, `this.cancelSchedule`. Schedules can be one-time, delayed, or recurring (using cron expressions).
 
+Since DOs only allow one alarm at a time, the `Agent` class works around this by managing multiple schedules in SQL and using a single alarm.
+
 ```ts
 class MyAgent extends Agent {
-  async onStart() {
+  async foo() {
     // Schedule at a specific time
     await this.schedule(new Date("2025-12-25T00:00:00Z"), "sendGreeting", {
       message: "Merry Christmas!"
@@ -333,9 +333,9 @@ class MyAgent extends Agent {
 
 Schedules are stored in the `cf_agents_schedules` SQL table. Cron schedules automatically reschedule themselves after execution, while one-time schedules are deleted.
 
-### this.mcp and friends
+### `this.mcp` and friends
 
-`Agent` includes a multi-server MCP client. This enables your Agent to interact with external services that expose MCP interfaces. The MCP client is documented in detail at [MCP Client API](/agents/model-context-protocol/mcp-client-api/).
+`Agent` includes a multi-server MCP client. This enables your Agent to interact with external services that expose MCP interfaces. The MCP client is properly documented in [MCP client API](/agents/model-context-protocol/mcp-client-api/).
 
 ```ts
 class MyAgent extends Agent {
@@ -407,7 +407,7 @@ function someUtilityFunction() {
 }
 ```
 
-### this.onError
+### `this.onError`
 
 `Agent` extends `Server`'s `onError` so it can be used to handle errors that are not necessarily WebSocket errors. It is called with a `Connection` or `unknown` error.
 
@@ -428,9 +428,9 @@ class MyAgent extends Agent {
 }
 ```
 
-### this.destroy
+### `this.destroy`
 
-`destroy()` drops all tables, deletes alarms, clears storage, and aborts the context. The `this.abort` method that is called by `this.destroy` comes from `DurableObject` and ensures that the Agent is fully evicted. In order to do so, it throws an uncatchable error that will show up in your logs (read more at [abort()](/durable-objects/api/state/#abort)).
+`this.destroy()` drops all tables, deletes alarms, clears storage, and aborts the context. To ensure that the DO is fully evicted, `this.ctx.abort()` is called, which throws an uncatchable error that will show up in your logs (read more about it in [abort()](/durable-objects/api/state/#abort)).
 
 ```ts
 class MyAgent extends Agent {