@electric-ax/agents 0.2.1 → 0.2.2

package/docs/entities/patterns/map-reduce.md

@@ -0,0 +1,81 @@
+---
+title: Map-Reduce
+titleTemplate: '... - Electric Agents'
+description: >-
+  Parallel processing pattern that splits work into chunks, processes simultaneously, and reduces results.
+outline: [2, 3]
+---
+
+# Map-Reduce
+
+Pattern: split input into chunks, process all in parallel, collect results.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/map-reduce.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/map-reduce.md)
+
+## Registration
+
+```ts
+export function registerMapReduce(registry: EntityRegistry) {
+  registry.define(`map-reduce`, {
+    description: `Map-reduce orchestrator that splits input into chunks, processes them in parallel with worker agents, then synthesizes results`,
+    state: {
+      children: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      ctx.useAgent({
+        systemPrompt: MAP_REDUCE_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, createMapChunksTool(ctx)],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+## How it works
+
+The agent exposes a `map_chunks` tool. When called:
+
+1. **Map phase** -- spawns one worker per chunk simultaneously. All workers run in parallel.
+2. Returns immediately. The entity is re-invoked as each worker finishes.
+3. The LLM synthesizes results once all workers have reported in via wake events.
+
+## Core
+
+```ts
+// Map phase - spawn all workers in parallel
+for (let i = 0; i < chunks.length; i++) {
+  spawnCounter++
+  const id = `chunk-${i}-${Date.now()}-${spawnCounter}`
+  const child = await ctx.spawn(
+    `worker`,
+    id,
+    { systemPrompt: task, tools: [`read`] },
+    {
+      initialMessage: chunks[i],
+      wake: `runFinished`,
+    }
+  )
+  ctx.db.actions.children_insert({
+    row: { key: id, url: child.entityUrl, chunk: i },
+  })
+}
+
+return {
+  content: [
+    {
+      type: `text` as const,
+      text: `Spawned ${chunks.length} parallel workers. You will be woken as each finishes with its output in finished_child.response.`,
+    },
+  ],
+  details: { chunkCount: chunks.length },
+}
+```
+
+## State collections
+
+| Collection | Purpose                                        |
+| ---------- | ---------------------------------------------- |
+| `children` | Spawned chunk workers (key, URL, chunk index). |

package/docs/entities/patterns/pipeline.md

@@ -0,0 +1,101 @@
+---
+title: Pipeline
+titleTemplate: '... - Electric Agents'
+description: >-
+  Sequential processing pattern where each stage's output feeds into the next via state transitions.
+outline: [2, 3]
+---
+
+# Pipeline
+
+Pattern: sequential stages where each stage's output feeds into the next.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/pipeline.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/pipeline.md)
+
+## Registration
+
+```ts
+export function registerPipeline(registry: EntityRegistry) {
+  registry.define(`pipeline`, {
+    description: `Pipeline orchestrator that chains sequential worker stages, feeding each stage output into the next`,
+    state: {
+      children: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      ctx.useAgent({
+        systemPrompt: PIPELINE_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, createRunStageTool(ctx)],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+## How it works
+
+The pipeline agent exposes a `run_stage` tool. The LLM drives the pipeline one stage at a time:
+
+1. The LLM calls `run_stage` with an instruction and input for the current stage.
+2. The tool spawns a worker with the instruction as its system prompt and the input as `initialMessage`, using `wake: 'runFinished'`.
+3. The tool returns immediately. The pipeline entity is re-invoked when the worker finishes.
+4. On each re-invocation, the wake event contains `finished_child.response` with the stage's output. The LLM then calls `run_stage` again with the next stage's instruction and the previous output as input.
+5. This repeats until all stages are complete.
+
+## Stage tool
+
+```ts
+function createRunStageTool(ctx: HandlerContext): AgentTool {
+  let stageCount = 0
+
+  return {
+    name: `run_stage`,
+    label: `Run Stage`,
+    description: `Spawns a worker for one pipeline stage.`,
+    parameters: Type.Object({
+      instruction: Type.String({
+        description: `The instruction for this stage.`,
+      }),
+      input: Type.String({ description: `The input for this stage.` }),
+    }),
+    execute: async (_toolCallId, params) => {
+      const { instruction, input } = params as {
+        instruction: string
+        input: string
+      }
+
+      stageCount++
+      const parentId = entityIdFromUrl(ctx.entityUrl)
+      const id = `${parentId}-stage-${stageCount}`
+
+      const child = await ctx.spawn(
+        `worker`,
+        id,
+        { systemPrompt: instruction, tools: [`read`] },
+        { initialMessage: input, wake: `runFinished` }
+      )
+      ctx.db.actions.children_insert({
+        row: { key: id, url: child.entityUrl, stage: stageCount },
+      })
+
+      return {
+        content: [
+          {
+            type: `text` as const,
+            text: `Stage ${stageCount} spawned. You will be woken when it finishes.`,
+          },
+        ],
+        details: { stage: stageCount },
+      }
+    },
+  }
+}
+```
+
+## State collections
+
+| Collection | Purpose                                             |
+| ---------- | --------------------------------------------------- |
+| `children` | Spawned worker references (key, URL, stage number). |

package/docs/entities/patterns/reactive-observers.md

@@ -0,0 +1,125 @@
+---
+title: Reactive observers
+titleTemplate: '... - Electric Agents'
+description: >-
+  Pattern for entities that watch others and react to changes using ctx.observe() with wake conditions.
+outline: [2, 3]
+---
+
+# Reactive observers
+
+Pattern: entities that watch other entities and react to changes.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/reactive-observers.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/reactive-observers.md)
+
+## Core mechanism
+
+An entity calls `ctx.observe(entity(entityUrl), { wake: { on: 'change', collections: [...] } })` to start watching another entity. The `entity()` helper (imported from `@electric-ax/agents-runtime`) wraps a raw URL into the correct observe target. When the observed entity has new activity in the specified collections, the observer is woken.
+
+## Monitor example
+
+The monitor watches multiple entities and reports status changes.
+
+**Source:** [`packages/agents-runtime/skills/designing-entities/references/patterns/reactive-observers.md`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/reactive-observers.md)
+
+```ts
+export function registerMonitor(registry: EntityRegistry) {
+  registry.define(`monitor`, {
+    description: `Health dashboard agent that watches multiple entities and reports status changes and anomalies`,
+    state: {
+      status: { primaryKey: `key` },
+    },
+
+    async handler(ctx) {
+      if (ctx.firstWake) {
+        ctx.db.actions.status_insert({ row: { key: `current`, value: `idle` } })
+      }
+      const baseObserveTool = createObserveTool(ctx)
+      const observeTool = {
+        ...baseObserveTool,
+        execute: async (toolCallId: string, params: unknown) => {
+          ctx.db.actions.status_update({
+            key: `current`,
+            updater: (draft) => {
+              draft.value = `observing`
+            },
+          })
+          return baseObserveTool.execute(toolCallId, params)
+        },
+      }
+
+      ctx.useAgent({
+        systemPrompt: MONITOR_SYSTEM_PROMPT,
+        model: `claude-sonnet-4-5-20250929`,
+        tools: [...ctx.electricTools, observeTool],
+      })
+      await ctx.agent.run()
+    },
+  })
+}
+```
+
+The monitor wraps the base observe tool to also transition its own state to `observing`.
+
+## The observe tool
+
+The `observe_entity` tool lets the LLM decide what to watch:
+
+```ts
+import { entity } from '@electric-ax/agents-runtime'
+
+export function createObserveTool(ctx: HandlerContext): AgentTool {
+  return {
+    name: `observe_entity`,
+    label: `Observe Entity`,
+    description: `Start observing another entity by its URL. The current entity will wake with a change payload when the observed entity has new activity.`,
+    parameters: Type.Object({
+      entity_url: Type.String({
+        description: `The URL of the entity to observe`,
+      }),
+      collections: Type.Optional(
+        Type.Array(Type.String(), {
+          description: `Which collections to watch (default: all). Options: texts, textDeltas, runs, toolCalls, childStatus`,
+        })
+      ),
+    }),
+    execute: async (_toolCallId, params) => {
+      const { entity_url, collections } = params as {
+        entity_url: string
+        collections?: string[]
+      }
+      try {
+        await ctx.observe(entity(entity_url), {
+          wake: { on: `change`, collections },
+        })
+        return {
+          content: [
+            {
+              type: `text`,
+              text: `Now observing entity: ${entity_url}. You will be woken when new activity is detected.`,
+            },
+          ],
+          details: {},
+        }
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: `text`,
+              text: `Error observing entity: ${err instanceof Error ? err.message : `Unknown error`}`,
+            },
+          ],
+          details: {},
+        }
+      }
+    },
+  }
+}
+```
+
+## Other reactive variants
+
+- **Summarizer** -- observes an entity's `texts` and `textDeltas` collections and produces progressive summaries of its output.
+- **Guardian** -- observes an entity's `texts` and `toolCalls` collections and evaluates output quality, checking for hallucination signals, safety issues, and formatting problems.
+
+All three follow the same structure: register an entity, wrap `createObserveTool` with a state transition, configure the agent with the observe tool, and run.

package/docs/examples/mega-draw.md

@@ -0,0 +1,106 @@
+---
+title: Mega Draw
+titleTemplate: '... - Electric Agents'
+description: >-
+  Multi-agent collaborative drawing example with coordinator-worker patterns and 100 tile agents.
+outline: [2, 3]
+---
+
+# Mega Draw
+
+A collaborative multi-agent drawing app where 100 AI agents each own a tile of a shared 1000x1000 pixel canvas and work together to produce a drawing from a single text prompt. Located at `examples/mega-draw/` in the repository.
+
+## What it demonstrates
+
+- **Coordinator + worker pattern** at scale (1 coordinator spawning 100 tile agents)
+- **Custom drawing tools** --- `fill_rect`, `draw_line`, `draw_circle`, `fill_gradient`, `set_pixels`
+- **Shared canvas** --- in-memory pixel buffer flushed to PNG, served via a live viewer
+- **Follow-up instructions** --- send a new prompt and only affected tiles get re-instructed
+- **Two-pass workflow** --- coordinator does a quick first pass for backgrounds, then a detail pass
+
+## Architecture
+
+```
+User
+  │
+  │  spawn /coordinator/my-drawing
+  │  send "Draw a sunset over mountains"
+  ▼
+┌────────────────────────────────┐
+│       Coordinator Agent        │
+│  - Receives prompt             │
+│  - Plans composition + palette │
+│  - Spawns 100 tile agents      │
+│  - Can re-instruct tiles       │
+└──────────┬─────────────────────┘
+           │ spawn tile-agent (10×10 grid)
+           ▼
+┌────────┐ ┌────────┐
+│Tile 0,0│ │Tile 1,0│  ...  (10 columns)
+└────────┘ └────────┘
+┌────────┐ ┌────────┐
+│Tile 0,1│ │Tile 1,1│  ...
+└────────┘ └────────┘
+   ...        ...       (10 rows = 100 tiles)
+```
+
+Each tile agent:
+
+- Owns a 100x100 pixel region
+- Can **see** 50px beyond its borders (200x200 viewport) for edge coordination
+- Can only **draw** within its own tile
+- Receives drawing instructions from the coordinator
+
+## Key files
+
+### `src/server.ts`
+
+Entry point. Creates the registry, runtime handler, and two HTTP servers (one for the Electric Agents webhook, one for the canvas viewer).
+
+```ts
+const registry = createEntityRegistry()
+registerCoordinator(registry, WEB_PORT)
+registerTileAgent(registry)
+
+const runtime = createRuntimeHandler({
+  baseUrl: ELECTRIC_AGENTS_URL,
+  serveEndpoint: `${SERVE_URL}/webhook`,
+  registry,
+})
+```
+
+### `src/coordinator.ts`
+
+The coordinator entity. Defines two custom tools:
+
+- `set_drawing_plan` --- sets the composition description and color palette
+- `instruct_tile` --- spawns or re-instructs a tile agent with drawing directions
+
+### `src/tile-agent.ts`
+
+The tile agent entity. Each instance gets drawing tools scoped to its tile:
+
+- `read_viewport` --- see current pixel state (own tile + neighbors)
+- `fill_rect`, `draw_line`, `draw_circle`, `fill_gradient`, `set_pixels`
+
+All coordinates are tile-relative (0--99) and automatically clipped to tile bounds.
+
+## Running it
+
+```bash
+cd examples/mega-draw
+pnpm install
+cp ../../.env.template .env  # Set ANTHROPIC_API_KEY
+pnpm dev
+```
+
+Requires a running Electric Agents runtime server at `http://localhost:4437`.
+
+Then in another terminal:
+
+```bash
+npx electric-ax agents spawn /coordinator/my-drawing
+npx electric-ax agents send /coordinator/my-drawing 'Draw a sunset over mountains'
+```
+
+View the canvas live at `http://localhost:3000/my-drawing` --- it auto-refreshes as tiles draw.

package/docs/examples/playground.md

@@ -0,0 +1,46 @@
+---
+title: Pattern references
+titleTemplate: '... - Electric Agents'
+description: >-
+  Electric Agents pattern references for standalone, coordination, blackboard, and reactive designs.
+outline: [2, 3]
+---
+
+# Pattern references
+
+Electric Agents pattern references live in the monorepo under `packages/agents-runtime/skills/designing-entities/references/patterns/`.
+
+## What it includes
+
+The patterns are organized into four categories.
+
+### Standalone
+
+- `single-agent` --- one entity handles the full task itself
+
+### Coordination
+
+- `manager-worker` --- multi-perspective analysis (optimist/pessimist/pragmatist)
+- `dispatcher` --- routes tasks to the appropriate agent type
+- `pipeline` --- sequential worker stages
+- `map-reduce` --- parallel chunk processing
+
+### Blackboard (shared state)
+
+- `blackboard` --- multiple workers coordinate through shared state
+
+### Reactive
+
+- `reactive-observers` --- observes entity streams and reacts to changes
+
+## Source references
+
+- [`single-agent`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/single-agent.md)
+- [`manager-worker`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/manager-worker.md)
+- [`dispatcher`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/dispatcher.md)
+- [`pipeline`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/pipeline.md)
+- [`map-reduce`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/map-reduce.md)
+- [`blackboard`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/blackboard.md)
+- [`reactive-observers`](https://github.com/electric-sql/electric/blob/main/packages/agents-runtime/skills/designing-entities/references/patterns/reactive-observers.md)
+
+See [Agents & Patterns](../usage/spawning-and-coordinating.md) for detailed documentation of each pattern.

package/docs/index.md

@@ -0,0 +1,208 @@
+---
+title: Electric Agents
+titleTemplate: '... - Electric Agents'
+description: >-
+  The durable runtime for long-lived agents — entities, handlers, wakes, agent loops, and coordination, built on Electric Streams, TanStack DB, and pi.
+outline: [2, 3]
+---
+
+<script setup>
+import EntityOverviewDiagram from '../../src/components/agents-home/EntityOverviewDiagram.vue'
+</script>
+
+# Electric Agents
+
+Electric Agents is **the durable runtime for long-lived agents**. It's a runtime and communication fabric for spawning and scaling collaborative agents on serverless compute, using your existing web and AI&nbsp;frameworks.
+
+Each agent is an **entity** — an addressable, schema-typed unit of state at `/{type}/{id}`. An entity's session and state live on a durable [Electric&nbsp;Stream](/streams/) of events.
+
+Entities **wake** when something happens — a message arrives, a child finishes, state changes, or a scheduled time elapses. When woken, the entity's handler runs. It can configure an LLM agent loop, update state, spawn children, and coordinate with other entities.
+
+Every step — runs, tool calls, text deltas, state changes — is appended to the entity's stream as it happens. Agents scale to zero and survive restarts. Any session can be replayed or [forked](/blog/2026/04/15/fork-branching-for-durable-streams) from any point, and observed in real time by any number of users and entities, both inside the system and from external apps.
+
+<EntityOverviewDiagram />
+
+Start with the [Quickstart](/docs/agents/quickstart) to run the built-in `horton` agent and connect your own app in a few minutes. The [Usage overview](/docs/agents/usage/overview) summarises the full developer surface in a single page.
+
+## How it works
+
+The runtime SDK is a layer over three foundations:
+
+- **[Electric&nbsp;Streams](/streams/)** — durable, ordered event log per entity.
+- **[TanStack&nbsp;DB](https://tanstack.com/db)** — typed local reads and writes via collections.
+- **Mario Zechner's [pi](https://github.com/badlogic/pi-mono) toolkit** — `pi-ai` (unified multi-provider LLM API) and `pi-agent-core` (agent runtime) for the LLM agent loop.
+
+**One stream per entity.** The runtime projects that stream into a typed local DB of collections — an `EntityStreamDB`. Inside a handler, that DB is `ctx.db`: writes go through `ctx.db.actions` (which append events to the stream), reads come from `ctx.db.collections`. The runtime ships [built-in collections](#built-in-collections) for runs, tool calls, text deltas, errors, inbox, and more, and you add your own typed [state](#state) collections per entity type.
+
+**Inside a handler.** When a handler calls `ctx.useAgent()`, the runtime configures the agent on its behalf and routes every step — model call, text delta, tool invocation, error — through the same projection, so the agent loop becomes durable events on the entity's stream.
+
+**Outside the handler.** Any app or other entity can call [`createAgentsClient().observe(entity('/type/id'))`](/docs/agents/usage/clients-and-react) to load an entity's stream into a local DB and react to changes in real time, with the same schemas and types as the handler.
+
+## Entities
+
+Use entities to model anything long-lived and addressable — an agent session, a chat thread, a research job, a coordinator, a worker. You register a **type** with [`registry.define()`](/docs/agents/reference/entity-registry) and spawn **instances** at `/{type}/{id}`. Each instance has its own state, handler, and event stream. See [Defining entities](/docs/agents/usage/defining-entities).
+
+```ts
+const registry = createEntityRegistry()
+
+registry.define('assistant', {
+  description: 'A general-purpose AI assistant',
+  async handler(ctx) {
+    // ...
+  },
+})
+```
+
+## Handlers
+
+The function that runs when an entity wakes. Receives a [`HandlerContext`](/docs/agents/reference/handler-context) (`ctx`) and a [`WakeEvent`](/docs/agents/reference/wake-event) (`wake`). The handler decides how to respond: configure an agent, update state, spawn children, or any combination. See [Writing handlers](/docs/agents/usage/writing-handlers).
+
+```ts
+registry.define('support', {
+  async handler(ctx, wake) {
+    if (wake.type === 'message_received') {
+      ctx.useAgent({
+        systemPrompt: 'You are a support agent.',
+        model: 'claude-sonnet-4-5-20250929',
+        tools: [...ctx.electricTools, searchKbTool],
+      })
+      await ctx.agent.run()
+    }
+  },
+})
+```
+
+## Wakes
+
+Events that trigger a handler invocation. Wake sources include incoming messages, child completion, state changes, and timers (scheduled sends, cron, timeouts). The [`WakeEvent`](/docs/agents/reference/wake-event) tells the handler why it was woken. See [Waking entities](/docs/agents/usage/waking-entities).
+
+```ts
+async handler(ctx, wake) {
+  // wake.type — "message_received", "wake", etc.
+  // wake.source — who triggered the wake
+  // wake.payload — message content or wake data
+
+  if (wake.type === "message_received") {
+    const userMessage = wake.payload
+    // handle incoming message
+  }
+}
+```
+
+## State
+
+Custom persistent collections on the entity. Defined as part of the [entity definition](/docs/agents/reference/entity-definition) and accessed through `ctx.db` alongside the [built-in collections](#built-in-collections). State is local to the entity, typed, and survives restarts. Use it for things that belong to the entity but aren't part of the agent's event stream — an order's items, a research job's findings, a chat session's TODOs. See [Managing state](/docs/agents/usage/managing-state).
+
+```ts
+registry.define('tracker', {
+  state: {
+    items: {
+      schema: z.object({
+        key: z.string(),
+        name: z.string(),
+        done: z.boolean(),
+      }),
+      primaryKey: 'key',
+    },
+  },
+  async handler(ctx) {
+    // read
+    const item = ctx.db.collections.items.get('item-1')
+
+    // write
+    ctx.db.actions.items_insert({
+      row: { key: 'item-2', name: 'New', done: false },
+    })
+  },
+})
+```
+
+## Agent loop
+
+The core pattern is [`ctx.useAgent()`](/docs/agents/reference/agent-config) followed by `ctx.agent.run()`. This runs the LLM in a loop — it generates text, calls tools, and continues until it has nothing left to do. All activity is automatically persisted to the entity's stream. See [Configuring the agent](/docs/agents/usage/configuring-the-agent).
+
+```ts
+ctx.useAgent({
+  systemPrompt: 'You are a helpful assistant.',
+  model: 'claude-sonnet-4-5-20250929',
+  tools: [...ctx.electricTools, myCustomTool],
+})
+
+await ctx.agent.run()
+```
+
+## Tools
+
+Functions the LLM can call during the agent loop. Each tool has a name, description, parameters (defined with [TypeBox](https://github.com/sinclairzx81/typebox) or any [Standard Schema](https://standardschema.dev) validator), and an execute function. Tools run in the handler's context and have access to the entity's state and coordination primitives. See [Defining tools](/docs/agents/usage/defining-tools) and the [`AgentTool` reference](/docs/agents/reference/agent-tool).
+
+```ts
+const searchKbTool: AgentTool = {
+  name: 'search_kb',
+  label: 'Search knowledge base',
+  description: 'Search the knowledge base',
+  parameters: Type.Object({
+    query: Type.String({ description: 'Search query' }),
+  }),
+  execute: async (_toolCallId, params) => {
+    const { query } = params as { query: string }
+    const results = await searchKnowledgeBase(query)
+    return {
+      content: [{ type: 'text', text: JSON.stringify(results) }],
+      details: {},
+    }
+  },
+}
+```
+
+## Coordination
+
+Entities interact through structured primitives. An entity can `spawn` children, `observe` other entities, `send` messages, and [share state](/docs/agents/usage/shared-state). These operations are all durable — they survive restarts and are tracked in the event stream. See [Spawning and coordinating](/docs/agents/usage/spawning-and-coordinating).
+
+```ts
+async handler(ctx) {
+  // spawn a child entity — wake parent when it finishes
+  const child = await ctx.spawn(
+    "worker",
+    "task-1",
+    {
+      systemPrompt: "Analyse the report",
+      tools: ["read"],
+    },
+    { initialMessage: "Find the top three issues", wake: "runFinished" }
+  )
+
+  // send a message to another entity
+  ctx.send("/notify/alerts", { level: "info", text: "Task started" })
+
+  // observe another entity's state changes
+  await ctx.observe(entity("/order/99"), {
+    wake: { on: "change", collections: ["status"] },
+  })
+}
+```
+
+## Built-in collections
+
+Every entity automatically has collections for runs, steps, texts, tool calls, errors, inbox, and more. These are populated by the runtime as the agent operates and give you live observability into every step of the agent loop — useful for chat UIs, debugging tools, dashboards, and analytics. Query them from the handler or observe them externally. See the [Built-in collections reference](/docs/agents/reference/built-in-collections).
+
+```ts
+// from inside a handler
+const allRuns = ctx.db.collections.runs.toArray
+const lastError = ctx.db.collections.errors.toArray.at(-1)
+
+// from outside — load an entity's stream into a local DB
+const client = createAgentsClient({ baseUrl: 'http://localhost:4437' })
+const db = await client.observe(entity('/support/ticket-42'))
+console.log(db.collections.texts.toArray)
+```
+
+## Next steps
+
+- [Quickstart](/docs/agents/quickstart) — run the built-in `horton` agent and connect your own app.
+- [Usage overview](/docs/agents/usage/overview) — the full developer surface on one page.
+- [Defining entities](/docs/agents/usage/defining-entities) — entity types, schemas, and configuration.
+- [Writing handlers](/docs/agents/usage/writing-handlers) — handler lifecycle and the `ctx` API.
+- [Configuring the agent](/docs/agents/usage/configuring-the-agent) — `useAgent`, models, tools, and streaming.
+- [Spawning & coordinating](/docs/agents/usage/spawning-and-coordinating) — multi-entity topologies and shared state.
+- [Built-in agents](/docs/agents/entities/agents/horton) — Horton and Worker, the agents that ship with the runtime.
+- [Examples](/docs/agents/examples/playground) — pattern walkthroughs and demo apps.