@electric-ax/agents 0.2.3 → 0.2.4

package/docs/examples/playground.md

@@ -1,46 +1,62 @@
 ---
-title: Pattern references
-titleTemplate: '... - Electric Agents'
+title: Playground
+titleTemplate: "... - Electric Agents"
 description: >-
-  Electric Agents pattern references for standalone, coordination, blackboard, and reactive designs.
+  Technical examples for experimenting with Electric Agents coordination patterns.
 outline: [2, 3]
 ---
 
-# Pattern references
+# Playground
 
-Electric Agents pattern references live in the monorepo under `packages/agents-runtime/skills/designing-entities/references/patterns/`.
+The [Electric Agents Playground](https://github.com/electric-sql/electric/tree/main/examples/agents-playground) is a collection of technical examples for trying coordination patterns against a local Electric Agents server.
 
 ## What it includes
 
-The patterns are organized into four categories.
+The playground currently includes two entity patterns.
 
-### Standalone
+### Perspectives
 
-- `single-agent` --- one entity handles the full task itself
+Perspectives is a manager-worker example. A manager agent spawns an optimist and a critic to examine the same question from different viewpoints, then synthesizes their responses into a balanced analysis.
 
-### Coordination
+It demonstrates:
 
-- `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
+- Spawning child agents from a custom tool.
+- Waking the manager when child runs finish.
+- Tracking child entity URLs in state.
+- Synthesizing worker outputs into a final response.
 
-### Blackboard (shared state)
+### Researcher
 
-- `blackboard` --- multiple workers coordinate through shared state
+Researcher is a coordinator example. It decomposes complex research questions into specialist sub-questions, spawns workers for each slice, and synthesizes the findings into a comprehensive answer with citations.
 
-### Reactive
+It demonstrates:
 
-- `reactive-observers` --- observes entity streams and reacts to changes
+- Dynamic fan-out based on the shape of the user's question.
+- Specialist worker agents focused on distinct research tasks.
+- Wake-on-finish coordination between coordinator and workers.
+- Final synthesis from multiple child reports.
 
-## Source references
+## Run it
 
-- [`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)
+Start the local agents infrastructure from the monorepo root:
 
-See [Agents & Patterns](../usage/spawning-and-coordinating.md) for detailed documentation of each pattern.
+```bash
+npx electric-ax agents start
+```
+
+Then configure and run the playground:
+
+```bash
+cd examples/agents-playground
+cp .env.example .env
+pnpm install
+pnpm dev
+```
+
+The app server starts on port `3000` and registers entity types with the agent server on port `4437`.
+
+## Source
+
+The source code is in [`examples/agents-playground`](https://github.com/electric-sql/electric/tree/main/examples/agents-playground).
+
+See [spawning & coordinating](../usage/spawning-and-coordinating.md) for the underlying coordination concepts.

package/docs/index.md

@@ -1,6 +1,6 @@
 ---
 title: Electric Agents
-titleTemplate: '... - 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]
@@ -22,7 +22,7 @@ Every step — runs, tool calls, text deltas, state changes — is appended to t
 
 <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.
+Start with the [Quickstart](/docs/agents/quickstart) to run the built-in `horton`, `worker`, and `coder` entities 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
 
@@ -45,8 +45,8 @@ Use entities to model anything long-lived and addressable — an agent session,
 ```ts
 const registry = createEntityRegistry()
 
-registry.define('assistant', {
-  description: 'A general-purpose AI assistant',
+registry.define("assistant", {
+  description: "A general-purpose AI assistant",
   async handler(ctx) {
     // ...
   },
@@ -58,12 +58,12 @@ registry.define('assistant', {
 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', {
+registry.define("support", {
   async handler(ctx, wake) {
-    if (wake.type === 'message_received') {
+    if (wake.type === "message_received") {
       ctx.useAgent({
-        systemPrompt: 'You are a support agent.',
-        model: 'claude-sonnet-4-5-20250929',
+        systemPrompt: "You are a support agent.",
+        model: "claude-sonnet-4-5-20250929",
         tools: [...ctx.electricTools, searchKbTool],
       })
       await ctx.agent.run()
@@ -94,7 +94,7 @@ async handler(ctx, wake) {
 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', {
+registry.define("tracker", {
   state: {
     items: {
       schema: z.object({
@@ -102,16 +102,16 @@ registry.define('tracker', {
         name: z.string(),
         done: z.boolean(),
       }),
-      primaryKey: 'key',
+      primaryKey: "key",
     },
   },
   async handler(ctx) {
     // read
-    const item = ctx.db.collections.items.get('item-1')
+    const item = ctx.db.collections.items.get("item-1")
 
     // write
     ctx.db.actions.items_insert({
-      row: { key: 'item-2', name: 'New', done: false },
+      row: { key: "item-2", name: "New", done: false },
     })
   },
 })
@@ -123,8 +123,8 @@ The core pattern is [`ctx.useAgent()`](/docs/agents/reference/agent-config) foll
 
 ```ts
 ctx.useAgent({
-  systemPrompt: 'You are a helpful assistant.',
-  model: 'claude-sonnet-4-5-20250929',
+  systemPrompt: "You are a helpful assistant.",
+  model: "claude-sonnet-4-5-20250929",
   tools: [...ctx.electricTools, myCustomTool],
 })
 
@@ -137,17 +137,17 @@ Functions the LLM can call during the agent loop. Each tool has a name, descript
 
 ```ts
 const searchKbTool: AgentTool = {
-  name: 'search_kb',
-  label: 'Search knowledge base',
-  description: 'Search the knowledge base',
+  name: "search_kb",
+  label: "Search knowledge base",
+  description: "Search the knowledge base",
   parameters: Type.Object({
-    query: Type.String({ description: 'Search query' }),
+    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) }],
+      content: [{ type: "text", text: JSON.stringify(results) }],
       details: {},
     }
   },
@@ -191,18 +191,18 @@ 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'))
+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.
+- [Quickstart](/docs/agents/quickstart) — run the built-in `horton`, `worker`, and `coder` entities 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.
+- [Built-in agents](/docs/agents/entities/agents/horton) — Horton, Worker, and Coder, the agents that ship with the runtime.
 - [Examples](/docs/agents/examples/playground) — pattern walkthroughs and demo apps.

package/docs/quickstart.md

@@ -1,6 +1,6 @@
 ---
 title: Quickstart
-titleTemplate: '... - Electric Agents'
+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]
@@ -19,7 +19,7 @@ npx electric-ax agents quickstart
 - **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.
+- *(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
 
@@ -49,7 +49,7 @@ 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.
+2. Starts a built-in **Horton** runtime in the foreground that registers the `horton`, `worker`, and `coder` 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).
@@ -94,25 +94,25 @@ npm install --save-dev tsx
 Create `server.ts`:
 
 ```ts
-import http from 'node:http'
+import http from "node:http"
 import {
   createEntityRegistry,
   createRuntimeHandler,
-} from '@electric-ax/agents-runtime'
+} from "@electric-ax/agents-runtime"
 
 const ELECTRIC_AGENTS_URL =
-  process.env.ELECTRIC_AGENTS_URL ?? 'http://localhost:4437'
+  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',
+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',
+      systemPrompt: "You are a helpful assistant.",
+      model: "claude-sonnet-4-5-20250929",
       tools: [...ctx.electricTools],
     })
     await ctx.agent.run()
@@ -126,7 +126,7 @@ const runtime = createRuntimeHandler({
 })
 
 const server = http.createServer(async (req, res) => {
-  if (req.url === '/webhook' && req.method === 'POST') {
+  if (req.url === "/webhook" && req.method === "POST") {
     await runtime.onEnter(req, res)
     return
   }
@@ -186,7 +186,7 @@ npx electric-ax agents stop --remove-volumes # stop containers and wipe data
 
 ```sh
 npx electric-ax agents start          # runtime server + UI (background, Docker)
-npx electric-ax agents start-builtin  # built-in Horton + worker (foreground)
+npx electric-ax agents start-builtin  # built-in Horton, worker, and coder (foreground)
 ```
 
 See the [CLI reference](./reference/cli#start) for the full set of commands.
@@ -198,4 +198,4 @@ See the [CLI reference](./reference/cli#start) for the full set of commands.
 - [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.
+- [Built-in agents](./entities/agents/horton) — Horton, Worker, and Coder, the agents that ship with the runtime.

package/docs/reference/agent-config.md

@@ -1,6 +1,6 @@
 ---
 title: AgentConfig
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   API reference for AgentConfig: system prompt, model, tools, streaming, and test responses.
 outline: [2, 3]
@@ -19,20 +19,26 @@ interface AgentConfig {
   provider?: KnownProvider
   tools: AgentTool[]
   streamFn?: StreamFn
+  getApiKey?: (
+    provider: string
+  ) => Promise<string | undefined> | string | undefined
+  onPayload?: SimpleStreamOptions["onPayload"]
   testResponses?: string[] | TestResponseFn
 }
 ```
 
 ## Fields
 
-| Field           | Type                         | Required | Description                                                                                                                                  |
-| --------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `systemPrompt`  | `string`                     | Yes      | System prompt sent to the LLM on each step.                                                                                                  |
-| `model`         | `string \| Model<any>`       | Yes      | Model identifier (e.g. `"claude-sonnet-4-5-20250929"`) or a resolved model object.                                                           |
-| `provider`      | `KnownProvider`              | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.                                                                         |
+| Field           | Type                         | Required | Description                                                                                         |
+| --------------- | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `systemPrompt`  | `string`                     | Yes      | System prompt sent to the LLM on each step.                                                         |
+| `model`         | `string \| Model<any>`       | Yes      | Model identifier (e.g. `"claude-sonnet-4-5-20250929"`) or a resolved model object.                  |
+| `provider`      | `KnownProvider`              | No       | Provider to use when `model` is a string. Defaults to `"anthropic"`.                                |
 | `tools`         | `AgentTool[]`                | Yes      | Tools available to the LLM. Spread `ctx.electricTools` when your runtime host provides runtime-level tools. See [`AgentTool`](./agent-tool). |
-| `streamFn`      | `StreamFn`                   | No       | Optional streaming callback passed to the underlying agent.                                                                                  |
-| `testResponses` | `string[] \| TestResponseFn` | No       | Mock LLM responses for testing. When set, no real LLM calls are made.                                                                        |
+| `streamFn`      | `StreamFn`                   | No       | Optional streaming callback passed to the underlying agent.                                         |
+| `getApiKey`     | `(provider) => string \| Promise<string> \| undefined` | No | Optional API-key resolver passed through to the model layer. |
+| `onPayload`     | `SimpleStreamOptions["onPayload"]` | No | Optional callback for raw streaming payloads from the model layer. |
+| `testResponses` | `string[] \| TestResponseFn` | No       | Mock LLM responses for testing. When set, no real LLM calls are made.                               |
 
 ## TestResponseFn
 
@@ -69,14 +75,16 @@ interface AgentHandle {
 
 ```ts
 interface AgentRunResult {
+  result?: unknown
   writes: ChangeEvent[]
   toolCalls: Array<{ name: string; args: unknown; result: unknown }>
   usage: { tokens: number; duration: number }
 }
 ```
 
-| Field       | Type                                   | Description                                                                             |
-| ----------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
-| `writes`    | `ChangeEvent[]`                        | Currently returned as an empty array placeholder.                                       |
-| `toolCalls` | `Array<{ name, args, result }>`        | Currently returned as an empty array placeholder.                                       |
+| Field       | Type                                   | Description                                                                 |
+| ----------- | -------------------------------------- | --------------------------------------------------------------------------- |
+| `result`    | `unknown`                              | Optional final result from the underlying agent adapter.                    |
+| `writes`    | `ChangeEvent[]`                        | Currently returned as an empty array placeholder.                           |
+| `toolCalls` | `Array<{ name, args, result }>`        | Currently returned as an empty array placeholder.                           |
 | `usage`     | `{ tokens: number; duration: number }` | Currently returned as `{ tokens: 0, duration: 0 }` until usage aggregation is wired in. |

package/docs/reference/agent-tool.md

@@ -1,6 +1,6 @@
 ---
 title: AgentTool
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Interface reference for AgentTool: name, description, TypeBox parameters schema, and execute function.
 outline: [2, 3]

package/docs/reference/built-in-collections.md

@@ -1,6 +1,6 @@
 ---
 title: Built-in collections
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Reference for the 17 runtime-managed collections: runs, steps, texts, toolCalls, inbox, errors, and more.
 outline: [2, 3]
@@ -43,7 +43,7 @@ All collections use `key` as the primary key.
 ```ts
 interface Run {
   key: string
-  status: 'started' | 'completed' | 'failed'
+  status: "started" | "completed" | "failed"
   finish_reason?: string
 }
 ```
@@ -55,7 +55,7 @@ interface Step {
   key: string
   run_id?: string
   step_number: number
-  status: 'started' | 'completed'
+  status: "started" | "completed"
   finish_reason?: string
   model_provider?: string
   model_id?: string
@@ -69,7 +69,7 @@ interface Step {
 interface Text {
   key: string
   run_id?: string
-  status: 'streaming' | 'completed'
+  status: "streaming" | "completed"
 }
 ```
 
@@ -91,7 +91,7 @@ interface ToolCall {
   key: string
   run_id?: string
   tool_name: string
-  status: 'started' | 'args_complete' | 'executing' | 'completed' | 'failed'
+  status: "started" | "args_complete" | "executing" | "completed" | "failed"
   args?: unknown
   result?: unknown
   error?: string
@@ -104,7 +104,7 @@ interface ToolCall {
 ```ts
 interface Reasoning {
   key: string
-  status: 'streaming' | 'completed'
+  status: "streaming" | "completed"
 }
 ```
 
@@ -148,14 +148,14 @@ interface WakeEntry {
 
 interface WakeChangeEntry {
   collection: string
-  kind: 'insert' | 'update' | 'delete'
+  kind: "insert" | "update" | "delete"
   key: string
 }
 
 interface WakeFinishedChildEntry {
   url: string
   type: string
-  run_status: 'completed' | 'failed'
+  run_status: "completed" | "failed"
   response?: string // concatenated text deltas from the finished run
   error?: string // error message(s) if run_status is "failed"
 }
@@ -163,7 +163,7 @@ interface WakeFinishedChildEntry {
 interface WakeOtherChildEntry {
   url: string
   type: string
-  status: 'spawning' | 'running' | 'idle' | 'stopped'
+  status: "spawning" | "running" | "idle" | "stopped"
 }
 ```
 
@@ -196,7 +196,7 @@ interface ChildStatusEntry {
   key: string
   entity_url: string
   entity_type: string
-  status: 'spawning' | 'running' | 'idle' | 'stopped'
+  status: "spawning" | "running" | "idle" | "stopped"
 }
 ```
 
@@ -249,7 +249,7 @@ type Manifest =
 
 interface ManifestChildEntry {
   key: string
-  kind: 'child'
+  kind: "child"
   id: string
   entity_type: string
   entity_url: string
@@ -259,7 +259,7 @@ interface ManifestChildEntry {
 
 interface ManifestSourceEntry {
   key: string
-  kind: 'source'
+  kind: "source"
   sourceType: string
   sourceRef: string
   wake?: WakeConfig
@@ -268,16 +268,16 @@ interface ManifestSourceEntry {
 
 interface ManifestSharedStateEntry {
   key: string
-  kind: 'shared-state'
+  kind: "shared-state"
   id: string
-  mode: 'create' | 'connect'
+  mode: "create" | "connect"
   collections: Record<string, { type: string; primaryKey: string }>
   wake?: WakeConfig
 }
 
 interface ManifestEffectEntry {
   key: string
-  kind: 'effect'
+  kind: "effect"
   id: string
   function_ref: string
   config: unknown
@@ -285,7 +285,7 @@ interface ManifestEffectEntry {
 
 interface ManifestContextEntry {
   key: string
-  kind: 'context'
+  kind: "context"
   id: string
   name: string
   attrs: Record<string, string | number | boolean>
@@ -295,9 +295,9 @@ interface ManifestContextEntry {
 
 interface ManifestCronScheduleEntry {
   key: string
-  kind: 'schedule'
+  kind: "schedule"
   id: string
-  scheduleType: 'cron'
+  scheduleType: "cron"
   expression: string
   timezone?: string
   payload?: unknown
@@ -306,16 +306,16 @@ interface ManifestCronScheduleEntry {
 
 interface ManifestFutureSendScheduleEntry {
   key: string
-  kind: 'schedule'
+  kind: "schedule"
   id: string
-  scheduleType: 'future_send'
+  scheduleType: "future_send"
   fireAt: string
   targetUrl: string
   payload: unknown
   producerId: string
   from?: string
   messageType?: string
-  status?: 'pending' | 'sent' | 'failed'
+  status?: "pending" | "sent" | "failed"
   sentAt?: string
   failedAt?: string
   lastError?: string