@electric-ax/agents 0.2.3 → 0.3.0

package/docs/entities/agents/horton.md

@@ -1,6 +1,6 @@
 ---
 title: Horton agent
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   The built-in Horton assistant - chat, research, code, and dispatch subagents in one entity type.
 outline: [2, 3]
@@ -8,7 +8,7 @@ outline: [2, 3]
 
 # Horton agent
 
-The built-in assistant registered by the Electric Agents dev server. Horton can chat conversationally, search the web, read and edit files, run shell commands, and dispatch subagents (workers) for isolated subtasks.
+The built-in assistant registered by the Electric Agents dev server. Horton can chat conversationally, search the web, read and edit files, run shell commands, and dispatch workers for isolated subtasks.
 
 **Source:** [`packages/agents/src/agents/horton.ts`](https://github.com/electric-sql/electric/blob/main/packages/agents/src/agents/horton.ts)
 
@@ -46,14 +46,14 @@ After the first agent run completes, Horton calls `generateTitle()` (Haiku) to s
 
 ## Details
 
-| Property          | Value                                                                             |
-| ----------------- | --------------------------------------------------------------------------------- |
-| Type name         | `horton`                                                                          |
-| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                                     |
-| Title model       | `claude-haiku-4-5-20251001`                                                       |
+| Property          | Value                                             |
+| ----------------- | ------------------------------------------------- |
+| Type name         | `horton`                                          |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)     |
+| Title model       | `claude-haiku-4-5-20251001`                       |
 | Tools             | `ctx.electricTools` + base Horton tool set, plus docs/skill tools when configured |
-| Working directory | Passed at bootstrap (defaults to `process.cwd()`)                                 |
-| Title generation  | Yes, after the first run if no title tag exists                                   |
+| Working directory | Passed at bootstrap (defaults to `process.cwd()`) |
+| Title generation  | Yes, after the first run if no title tag exists   |
 
 ## Extending Horton
 
@@ -64,10 +64,10 @@ import {
   HORTON_MODEL,
   buildHortonSystemPrompt,
   createHortonTools,
-} from '@electric-ax/agents'
+} from "@electric-ax/agents"
 
-registry.define('my-assistant', {
-  description: 'Horton with an extra custom tool',
+registry.define("my-assistant", {
+  description: "Horton with an extra custom tool",
   async handler(ctx) {
     const readSet = new Set<string>()
     ctx.useAgent({

package/docs/entities/agents/worker.md

@@ -1,6 +1,6 @@
 ---
 title: Worker
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Generic sandboxed subagent type. Spawned by Horton (or any agent) via the spawn_worker tool with a system prompt and a chosen tool subset.
 outline: [2, 3]
@@ -19,7 +19,7 @@ interface WorkerArgs {
   systemPrompt: string
   tools?: Array<WorkerToolName>
   sharedDb?: { id: string; schema: SharedStateSchemaMap }
-  sharedDbToolMode?: 'full' | 'write-only'
+  sharedDbToolMode?: "full" | "write-only"
 }
 ```
 
@@ -36,13 +36,13 @@ interface WorkerArgs {
 
 ```ts
 type WorkerToolName =
-  | 'bash'
-  | 'read'
-  | 'write'
-  | 'edit'
-  | 'brave_search'
-  | 'fetch_url'
-  | 'spawn_worker'
+  | "bash"
+  | "read"
+  | "write"
+  | "edit"
+  | "brave_search"
+  | "fetch_url"
+  | "spawn_worker"
 ```
 
 These are the same primitives Horton uses. Pick the smallest subset the worker needs — tools are the worker's permission set.
@@ -56,9 +56,9 @@ The canonical way to spawn a worker is the `spawn_worker` tool, which Horton cal
 ```ts
 spawn_worker({
   systemPrompt:
-    'You are a focused researcher. Find the three most-cited papers on X and return their titles, authors, and DOIs as a markdown table.',
-  tools: ['brave_search', 'fetch_url'],
-  initialMessage: 'Begin research now.',
+    "You are a focused researcher. Find the three most-cited papers on X and return their titles, authors, and DOIs as a markdown table.",
+  tools: ["brave_search", "fetch_url"],
+  initialMessage: "Begin research now.",
 })
 ```
 
@@ -93,10 +93,10 @@ When you finish, respond with a concise report covering what was done and any ke
 
 ## Details
 
-| Property          | Value                                                                                                                     |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| Type name         | `worker`                                                                                                                  |
-| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                                                                             |
-| Tools             | Subset of 7 primitives plus optional shared-state tools. **No `ctx.electricTools`.**                                      |
-| Working directory | Provided to `registerWorker` at bootstrap                                                                                 |
+| Property          | Value                                                                 |
+| ----------------- | --------------------------------------------------------------------- |
+| Type name         | `worker`                                                              |
+| Model             | `HORTON_MODEL` (`claude-sonnet-4-5-20250929`)                         |
+| Tools             | Subset of 7 primitives plus optional shared-state tools. **No `ctx.electricTools`.** |
+| Working directory | Provided to `registerWorker` at bootstrap                             |
 | Description       | `Internal — generic worker spawned by other agents. Configure via spawn args (systemPrompt + tools + optional sharedDb).` |

package/docs/entities/patterns/blackboard.md

@@ -1,6 +1,6 @@
 ---
 title: Blackboard (shared state)
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Multi-agent coordination using shared state as a common data structure for reads and writes.
 outline: [2, 3]
@@ -23,12 +23,12 @@ const debateSchema = {
   arguments: {
     schema: z.object({
       key: z.string(),
-      side: z.enum(['pro', 'con']),
+      side: z.enum(["pro", "con"]),
       text: z.string(),
       round: z.number(),
     }),
-    type: 'shared:argument',
-    primaryKey: 'key',
+    type: "shared:argument",
+    primaryKey: "key",
   },
 }
 ```
@@ -36,7 +36,7 @@ const debateSchema = {
 ### Registration
 
 ```ts
-import { db } from '@electric-ax/agents-runtime'
+import { db } from "@electric-ax/agents-runtime"
 
 export function registerDebate(registry: EntityRegistry) {
   registry.define(`debate`, {
@@ -97,7 +97,7 @@ const args = shared.arguments.toArray
 ### State transitions
 
 ```ts
-type DebateStatus = 'idle' | 'debating' | 'ruling' | 'done'
+type DebateStatus = "idle" | "debating" | "ruling" | "done"
 ```
 
 ## Other blackboard variants

package/docs/entities/patterns/dispatcher.md

@@ -1,6 +1,6 @@
 ---
 title: Dispatcher
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Message routing pattern that classifies incoming messages and dispatches to specialist agents.
 outline: [2, 3]

package/docs/entities/patterns/manager-worker.md

@@ -1,6 +1,6 @@
 ---
 title: Manager-Worker
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Coordination pattern where a parent spawns specialist children, waits for completion, and synthesizes results.
 outline: [2, 3]

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

@@ -1,6 +1,6 @@
 ---
 title: Map-Reduce
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Parallel processing pattern that splits work into chunks, processes simultaneously, and reduces results.
 outline: [2, 3]

package/docs/entities/patterns/pipeline.md

@@ -1,6 +1,6 @@
 ---
 title: Pipeline
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Sequential processing pattern where each stage's output feeds into the next via state transitions.
 outline: [2, 3]

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

@@ -1,6 +1,6 @@
 ---
 title: Reactive observers
-titleTemplate: '... - Electric Agents'
+titleTemplate: "... - Electric Agents"
 description: >-
   Pattern for entities that watch others and react to changes using ctx.observe() with wake conditions.
 outline: [2, 3]
@@ -66,7 +66,7 @@ The monitor wraps the base observe tool to also transition its own state to `obs
 The `observe_entity` tool lets the LLM decide what to watch:
 
 ```ts
-import { entity } from '@electric-ax/agents-runtime'
+import { entity } from "@electric-ax/agents-runtime"
 
 export function createObserveTool(ctx: HandlerContext): AgentTool {
   return {

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` and `worker` 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],
 })
 
@@ -135,19 +135,21 @@ await ctx.agent.run()
 
 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).
 
+External tools, resources, and prompts can also be loaded from [Model Context Protocol](https://modelcontextprotocol.io) servers — declared in `mcp.json`, the desktop app's `settings.json`, or programmatically. See [MCP servers](/docs/agents/usage/mcp-servers).
+
 ```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 +193,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` and `worker` 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
 
@@ -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 and worker (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]