BUILDING

Building an agent

The from-zero guide to a new Raven agent: one command scaffolds a folder, the folder is discovered, and its server answers an ACP handshake. **The bar this guide holds itself to: a developer who has never read the source reaches a green handshake in ten minutes.** If any step below forces you into the source, that is a defect in this guide or in the scaffold -- report it as one.

1. The mental model

Raven is a harness of harnesses, two layers deep:

• The **host raven** is the first harness: it owns the turn loop, the

permission gate, the built-in tools, memory, and the roster of agents it can dispatch to.

• **Your agent** is a second harness riding that loop: a folder with a

launcher that renders a config and execs the installed raven's own `raven acp`. Your identity, your tools, and your hooks enter through the plugin seam; the core never imports your code and never learns your name.

Three words carry precise, different meanings here:

| Word | Means | Where it lives | |---|---|---| | **agent** | the thing itself: a folder the roster discovers, spawns, and dispatches to | `agents/<name>/` or `$RAVEN_HOME/agents/<name>/` | | **harness** | the mechanism an agent steers the loop with: plugins contributing tools and hooks | `plugins/<id>/` inside the agent, or an engine wheel | | **subagent** | the protocol seat: the roster row the dispatching model picks, spoken over ACP | `subagent.json`, validated by `raven/config/schema.py` |

2. Ten minutes to a green handshake

raven agents new my-agent

That is the whole quick start. Five things happen, and the command prints a four-segment card as they do:

1. **`1/4 wrote`** -- eleven files land under `$RAVEN_HOME/agents/my-agent/` (assembled in a staging directory and renamed as a whole, so a failure never leaves a half-written agent). `--here` lands in `./agents/<name>` instead; `--dry-run` prints the tree and writes nothing. 2. **`2/4 doctor`** -- the folder examines itself: `subagent.json` through the roster schema, `raven-plugin.toml` through the manifest parser, every `.py` compiled, and a real discovery scan reporting the row and its readiness. 3. **`3/4 smoke`** -- the discovered command is spawned and sent one ACP `initialize` frame. Three readable outcomes:

• **GREEN**: a legal reply came back; the chain works end to end.
• **refused**: no LLM key anywhere, so the launcher exited loudly before

serving. This is the fail-closed design working, not a broken chain -- provide a key (see `.env.example` in the folder) or configure a provider in the host raven, and the same command goes green.

• **FAILED**: anything else, with the stderr tail; the folder stays on

disk for inspection. `--no-smoke` skips this segment. 4. **`4/4 next`** -- restart the gateway so a live raven re-reads the tree; fill in the two TODO prompts in `subagent.json`; optionally pin the row.

There is no registration step: a folder under `$RAVEN_HOME/agents/` is discovered on every scan (the home tree is discovery's first priority, and it survives upgrades). Dispatch happens when the host's model reads your row's `description` and picks it -- which is why those TODOs matter.

A note on names: one kebab name derives every identity. `my-agent` is the folder and machine id (never renamed), `My-Agent` the display name (`--display` overrides), `my_agent` the python package, and `MY_AGENT` the env-var prefix (the `raven-` prefix drops for shipped agents: `raven-code` answers to `CODE_API_KEY`).

3. The eleven files

Each file, its one job, and the mistake most often made in it:

| File | Job | Common mistake | |---|---|---| | `subagent.json` | The roster row: the only file written for someone else (the dispatching model). `name` is the dispatch identity; `description` and `owns` are prompts -- the model decides from them alone when to pick you; `everos` ids are the machine identity (never change them after first use); `command` keeps `{PYTHON}` / `{SUBAGENT_DIR}` verbatim -- discovery resolves them in memory | Leaving the TODO prompts in place: the agent then never gets picked, and nothing errors | | `run.py` | The launcher: renders the config (secret slots, host LLM inheritance, state root, plugin roots) and execs `python -m raven acp` -- it is not in the room during the session | Writing state into the agent folder; everything the agent persists belongs under the state root | | `config.json` | The birth certificate: the diff between your agent and stock raven, in the host's own config schema. Ships as the minimal plugin slice | Adding `plugins.dirs` here -- the launcher injects it absolute at render time, and overwrites whatever this file says | | `install.py` | The optional pinning ceremony: registers the row through `raven.config.update_subagents`. Needed only for a folder outside the discovery tree, an edited row, or a deliberately pinned one | Running it and expecting a live raven to notice -- the roster is read at startup; restart the gateway | | `.env.example` | The secret slots, documented: the API key (own-key mode), the state root override, the ACP home override. Copy to `.env`, which stays in the folder and out of every wheel | Setting the key but no `providers` block in `config.json`: own-key mode renders a key with no provider/model to route on -- handshake green, first real turn dead | | `README.md` | The folder's own ten-minute card for whoever finds it later | -- | | `plugins/<id>/raven-plugin.toml` | The treaty: declarative manifest of what your plugin contributes (tools, hooks, and four more kinds). The host validates it without importing you. Empty `config_schema` means your slice passes through verbatim | A factory path that does not resolve -- activation logs a warning and skips the plugin; boot survives, your tool is silently absent | | `.../plugin.py` | The hook factory: an `AgentHook` with all six phases inherited as pass-through, one overridden as th