@electric-ax/agents 0.1.5 → 0.2.2

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.

package/docs/quickstart.md

@@ -0,0 +1,201 @@
+---
+title: Quickstart
+titleTemplate: '... - Electric Agents'
+description: >-
+  Run the Electric Agents runtime and the built-in Horton assistant with a single CLI command, then connect from the web UI or define your own entities.
+outline: [2, 3]
+---
+
+# Quickstart
+
+One command starts the Electric Agents runtime, the web UI, and a local [Horton](./entities/agents/horton) assistant you can chat with right away. From there, define your own [entities](./usage/defining-entities) in your own app.
+
+```sh
+npx electric-ax agents quickstart
+```
+
+## What you'll need
+
+- **Node.js 18+**.
+- **[Docker](https://docs.docker.com/get-docker/)**. The runtime server, Postgres, and Electric run as containers.
+- **An [Anthropic API key](https://console.anthropic.com/settings/keys)**. Used by the built-in Horton agent.
+- _(Optional)_ A **[Brave Search API key](https://brave.com/search/api/)** if you want Horton to be able to search the web.
+
+## Set your API key
+
+Either export it in your shell:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+Or persist it in a `.env` file in the directory you run the CLI from (this creates or overwrites `.env` in the current directory):
+
+```sh
+cat <<'EOF' > .env
+ANTHROPIC_API_KEY=sk-ant-...
+# BRAVE_SEARCH_API_KEY=BS...
+EOF
+```
+
+The CLI also accepts `--anthropic-api-key <key>` if you'd rather pass it inline.
+
+## Start the runtime
+
+```sh
+npx electric-ax agents quickstart
+```
+
+This:
+
+1. Starts Postgres, Electric, and the Electric Agents runtime server in Docker (the runtime serves both the API and the web UI on `http://localhost:4437`).
+2. Starts a built-in **Horton** runtime in the foreground that registers the `horton` and `worker` entity types.
+3. Prints onboarding commands you can copy into a second terminal.
+
+Leave this terminal running. Press `Ctrl-C` to stop the built-in Horton runtime — the runtime server containers keep running in the background until you call [`electric agents stop`](#stop-the-dev-environment).
+
+## Chat with Horton
+
+### From the web UI
+
+Open [http://localhost:4437](http://localhost:4437). Spawn a `horton` entity from the dashboard and send it a message — its timeline updates live as the agent thinks, calls tools, and responds.
+
+### From the CLI
+
+In a separate terminal:
+
+```sh
+npx electric-ax agents spawn /horton/onboarding
+npx electric-ax agents send /horton/onboarding 'Walk me through Electric Agents'
+npx electric-ax agents observe /horton/onboarding
+```
+
+- `spawn` creates a new entity instance at the given path.
+- `send` delivers a message to the entity's inbox, waking its handler.
+- `observe` streams the entity's events to your terminal in real time, with reasoning, tool calls, and text deltas rendered inline.
+
+See the [CLI reference](./reference/cli) for the full command surface.
+
+## Define your own entity types
+
+Once you're chatting with Horton, the next step is to define your own entity types in your own app. Your app is just a process that registers entity types with the runtime server and receives webhook callbacks when they wake.
+
+### 1. Install the runtime SDK
+
+```sh
+mkdir my-agents-app && cd my-agents-app
+npm init -y
+npm install @electric-ax/agents-runtime
+npm install --save-dev tsx
+```
+
+### 2. Create a server
+
+Create `server.ts`:
+
+```ts
+import http from 'node:http'
+import {
+  createEntityRegistry,
+  createRuntimeHandler,
+} from '@electric-ax/agents-runtime'
+
+const ELECTRIC_AGENTS_URL =
+  process.env.ELECTRIC_AGENTS_URL ?? 'http://localhost:4437'
+const PORT = Number(process.env.PORT ?? 3000)
+const SERVE_URL = process.env.SERVE_URL ?? `http://localhost:${PORT}`
+
+const registry = createEntityRegistry()
+
+registry.define('assistant', {
+  description: 'A general-purpose AI assistant',
+  async handler(ctx) {
+    ctx.useAgent({
+      systemPrompt: 'You are a helpful assistant.',
+      model: 'claude-sonnet-4-5-20250929',
+      tools: [...ctx.electricTools],
+    })
+    await ctx.agent.run()
+  },
+})
+
+const runtime = createRuntimeHandler({
+  baseUrl: ELECTRIC_AGENTS_URL,
+  serveEndpoint: `${SERVE_URL}/webhook`,
+  registry,
+})
+
+const server = http.createServer(async (req, res) => {
+  if (req.url === '/webhook' && req.method === 'POST') {
+    await runtime.onEnter(req, res)
+    return
+  }
+  res.writeHead(404)
+  res.end()
+})
+
+server.listen(PORT, async () => {
+  await runtime.registerTypes()
+  console.log(`App server ready on port ${PORT}`)
+})
+```
+
+This does four things:
+
+1. **Defines an entity type** called `assistant` with a handler that configures and runs an LLM agent.
+2. **Creates a runtime handler** that connects to the runtime server.
+3. **Starts an HTTP server** to receive webhook callbacks from the runtime.
+4. **Registers entity types** with the runtime server on startup.
+
+See [App setup](./usage/app-setup) for the full `createRuntimeHandler` configuration.
+
+### 3. Run your app
+
+With the runtime server already running (from `electric agents quickstart` or `electric agents start`), start your app:
+
+```sh
+npx tsx server.ts
+```
+
+Your handler calls `ctx.useAgent()` in this process, so make sure `ANTHROPIC_API_KEY` is exported in this shell (or copy your `.env` into `my-agents-app`).
+
+### 4. Interact with your entity
+
+Spawn an instance, send it a message, and observe the timeline:
+
+```sh
+npx electric-ax agents spawn /assistant/my-assistant
+npx electric-ax agents send /assistant/my-assistant 'Hello!'
+npx electric-ax agents observe /assistant/my-assistant
+```
+
+Or open the web UI at `http://localhost:4437` and pick `/assistant/my-assistant` from the entity list.
+
+## Stop the dev environment
+
+`Ctrl-C` in the quickstart terminal stops the built-in Horton runtime. The runtime server containers keep running. To stop them:
+
+```sh
+npx electric-ax agents stop                  # stop containers, keep data
+npx electric-ax agents stop --remove-volumes # stop containers and wipe data
+```
+
+## Run pieces independently
+
+`quickstart` runs `start` then `start-builtin` for you. Run them yourself if you want the runtime server up across multiple sessions, or to run your own agent process instead of the built-ins:
+
+```sh
+npx electric-ax agents start          # runtime server + UI (background, Docker)
+npx electric-ax agents start-builtin  # built-in Horton + worker (foreground)
+```
+
+See the [CLI reference](./reference/cli#start) for the full set of commands.
+
+## Next steps
+
+- [Overview](./) — the mental model behind entities, handlers, and wakes.
+- [Usage overview](./usage/overview) — the full developer surface on one page.
+- [Defining entities](./usage/defining-entities) — entity types, schemas, and configuration.
+- [Writing handlers](./usage/writing-handlers) — handler lifecycle and the `ctx` API.
+- [Configuring the agent](./usage/configuring-the-agent) — `useAgent`, models, tools, and streaming.
+- [Built-in agents](./entities/agents/horton) — Horton and Worker, the agents that ship with the runtime.