Working with sub-agents¶
Delegate a bounded task, inspect what the specialist actually did, and continue the right session when you need changes. Raven exposes both delegated tasks and stateful agent instances; they are different things.
Set up agents first with Agent Integrations. This page covers using them, not installing their transports.
What the host does and what it hands over¶
Raven itself works as your agent manager. It sorts a request into tasks, hands
each to the sub-agent that fits it, keeps track of every task until you accept
the result, and gathers what the agents report into one answer, where each task it
covers gets its own section under a heading that names the task, whether that is the
task's result or a single line on how it is going. When it asks you
to decide several things and your reply settles only some of them, it acts on
those and asks about the rest again at the end of every reply, until you decide
each one, drop it or tell it to leave it for later. On the web page with the Task
Board on, the rest wait on the board instead: every question still open is listed
on its task's card, so a reply asks only what is new. A later message
about a task's work -- a correction, more work, or a question about why it was
done that way -- goes back to the instance that did the work, which still has
its context. Raven answers in the session, what it already knows and where your
tasks stand by its own record itself. Any work that needs a tool, however small,
goes to the agent that fits it, and to the built-in Raven-General agent only
when none does: looking something up, checking a result and a cleanup as much as
a script or a document. Raven's own turn holds the session while it works,
so handing the work over keeps it free for your next message. An agent's report
comes to Raven, and the page shows it folded (the terminal as one line), so when
one comes back Raven tells you in its own words what was done and what came of it: each finding by what it is rather than by the
report's label, and the grounds the report gives for a verdict. In a
session running on a Harness with workers, such as a Persona, Raven hands work
only to those workers; work none of them covers, it tells you about and asks how to
go on instead of doing it itself. On a turn where both dispatch tools are disabled,
Raven does the work itself.
Work on a registered machine¶
An agent entry that names a machine runs on that registered machine, works
there and leaves its files there; entries without one run locally as before.
Working on Registered Machines walks through registering the
machine, installing its node, configuring the entry, and what to expect when
the connection drops.
Remote ACP agents can use the MCP servers granted to their entry through the Raven node. Server definitions and credentials stay on the host, as do tool restrictions and sandbox rules. The node tells which task a bridge belongs to by the process that opened it, and the host checks that task against the grant; another task cannot select a grant by name.
The host serves each granted server from a Unix socket where the system supports
one. Otherwise, as on Windows, it listens on a port on 127.0.0.1 and opens the
server only for a connection that presents that endpoint's random token; the
token stays on the host. CLI agents on machines continue without lent MCP. A
host restart recovers the task result but does not restore its previous MCP
connections.
Choose a collaboration shape¶
| Need | Use | Completion evidence |
|---|---|---|
| One specialist task | Ask the host to spawn it |
Returned result and relevant files/tests |
| Parallel or dependent work | DAG orchestration | Node outputs, dependencies, and verdicts |
| Repeat a reviewed procedure | Playbook | The actual graph result, not merely a dispatch receipt |
| Continue with a particular specialist | Direct chat with its stateful instance | That instance's response/history |
| Run and keep watching a long job | Oncall | Campaign status and final report |
spawn and run_subagent_dag are model tools, not shell commands. Delegation
uses additional model calls and can start subprocesses or external work.
A first read-only collaboration¶
- Open a session in the project's working directory. Check the chosen agent is enabled and ready.
- Ask: “Have Raven-Code review the public API in this checkout. Do not edit files. Return compatibility risks with file references, then summarize the findings for me.”
- Inspect the delegated task and its result in the WebUI sub-agent panel or task view. A stream of activity is progress, not proof of success.
- Open its resumable instance, if one exists, and ask: “Expand the highest priority risk. Do not change the implementation yet.”
- Return to the main session and ask it to incorporate the follow-up into the final summary.
The generic raven agent is another option when no specialized setup is ready.
Choose a stateful backend if follow-up matters; a one-shot
stateless task is not automatically a resumable chat.
Sessions, instances, and task ids¶
The host session is the session you opened. An instance is addressed by an agent and handle within that session. A DAG node id identifies a task and its outputs; it does not identify a session to chat with.
Reusing an instance can preserve that child's context. A new instance starts separate state. The WebUI can create an instance for an enabled, stateful agent even before the host delegates anything to it; creation records an idle instance and does not itself run a task.
Do not assume all agents see the host's entire transcript. Send the specific requirements and attachments they need. File paths refer to the execution environment that receives them, not automatic transfers to every remote agent.
Direct chat and handoff¶
The sub-agent panel shows instance history and, when supported, a composer addressed to that instance. Direct turns use their own execution lane. They can run alongside the host or other instances, but a busy instance cannot necessarily accept another normal turn.
The direct session is kept separately from the main transcript. On your next turn to the main agent, the runtime supplies a Handoff Block: instance identity, times, and paths to recorded prompts/results. It does not paste the whole exchange or produce an automatic semantic summary. Ask the host to read the relevant records when the decision depends on their contents.
The host is also told about user-created instances and still-running direct turns. This is evidence of activity, not evidence that a specialist finished. Forgetting an instance removes its addressability; it does not erase the record directories used for audit.
Steer an active turn¶
Steering adds a correction to a turn already running, instead of starting a new task. For example: “Limit this review to public interfaces; leave internal helpers out.” The correction is read before a later model call; it cannot undo an action already performed.
The server exposes subagents.instance.steer. Client UI support varies; the
current WebUI instance composer uses normal direct turns, so do not assume
typing into it invokes steer. A client implementing the RPC sends:
{
"session_key": "HOST_SESSION_KEY",
"agent": "Raven-Code",
"handle": "INSTANCE_HANDLE",
"text": "Limit the review to public interfaces; do not edit files."
}
These are RPC parameters, not a CLI command. Resolve session/agent/handle from the current instance list rather than inventing an address.
| Response | Meaning |
|---|---|
injected |
Text accepted for the running turn; not a promise it already acted on it |
no_turn |
No active turn; send a normal follow-up if still wanted |
unsupported |
This run's transport cannot accept steering |
CLI-agent runs and ACP agents without Raven's negotiated steering extension cannot be assumed to support it. See Agent Protocols.
Models, modes, and shared files¶
Where an instance advertises modes or models, its controls use that instance's own menu. A mode override can take precedence over the host session's tier; clearing it restores inheritance. Clearing a model override returns to the agent's own choice. Neither setting grants new filesystem or tool permissions.
For coding work the host follows its built-in multi-agent-coding skill.
When coding tasks run side by side in one Git
project, the host asks each coding agent to create a git worktree of its own, on
a branch named for its task, and to report the worktree's path and branch. The
changes stay on those branches until you ask for them to be merged, and the
worktrees stay until you ask for them to be removed. The same skill keeps one
instance per task, sends a follow-up on an unfinished task to that task's
instance, and moves a task to another coding agent when the first reports that
its quota is used up.
Worktree creation is a step performed by the coding agent under the host's instructions. Check the reported path and branch before concurrent edits. When constructing a graph yourself, assign working copies or explicit file ownership: the dispatcher does not create worktrees or lock files. Raven-Code's shared-workspace report helps identify overlap.
Troubleshooting¶
| Symptom | Check |
|---|---|
| Agent missing | Enabled roster, installation readiness, and current session |
| Cannot create or resume an instance | Backend statefulness and whether the agent is enabled |
| Direct send refuses while busy | Wait for this instance; use a capable steering client for in-turn corrections |
| Host does not use the follow-up | Send a new host turn and ask it to inspect handoff records |
| Visible history but no live activity after restart | Recorded history is not automatic execution recovery |
| Successful return but wrong result | Verify files, evidence, and DAG verdicts before retrying |
Stop or retry only after checking side effects. For scheduled work, canceling a session is not proof that the remote process or campaign stopped. Use the Oncall lifecycle for that case.