Agent Integrations¶
Use this guide to connect and operate existing agents. If you are building a new Raven agent, see Building an Agent; if you are implementing an ACP, CLI, HTTP, or other backend, see Protocol and Backend Integration. For wire messages and lifecycle details, see Agent Protocols.
Agent origin and runtime¶
“Raven agent” and “external agent” describe who supplies the agent. kind
describes the runtime backend Raven uses. These are independent axes: a
Raven-shipped agent can use ACP, and an external agent can use ACP, CLI, or
HTTP.
| Integration | Runtime configuration | Execution boundary |
|---|---|---|
| In-process backend | kind: builtin |
A Raven loop in the host process |
| Raven-shipped agent | Discovered folder, kind: acp |
Launcher starts Raven with the agent's own configuration |
| External local agent | kind: acp or kind: cli in subagents.agents |
Another product's process and native policy |
| OpenAI-compatible HTTP agent | kind: openai in subagents.agents |
Remote endpoint; no local tool loop in this backend |
| A2A peer | a2a.peers plus a2a_send |
An independent host, outside the sub-agent roster |
spawn and DAG nodes select from one roster. A node must use a name or worker
label actually advertised by the current tool; a familiar product name alone
does not install, enable, or authenticate an agent.
Raven-native agents¶
| Agent | Best for | Important boundary |
|---|---|---|
| Raven-Code | Coding, debugging, and verification | Edits real files; partition parallel writers' files, and treat todo completion as a claim rather than test evidence. |
| Raven-Design | Visual design, review, and presentation work | Requires design/media readiness; routes deck requests to hidden Raven-PPT. |
| Raven-Oncall | Running and watching multi-round or remote work | Needs target-machine access, budget, and stop conditions; the first response does not mean the job finished. |
| Raven-PPT | Producing .pptx decks |
Normally enters through Raven-Design; needs deck engine, templates, rendering, and media requirements. |
| Raven-Research | Live-web research and sourced reports | Needs the research profile and credentials; it is not a general coding or chat delegate. |
These five definitions are not necessarily five visible roster entries. The shipped Raven-PPT manifest is hidden behind Raven-Design's routing; an operator's local manifest may differ. Routing also considers declared requirements, attachments, and tier, so a task does not always run on the same implementation as the visible entry.
Definitions are discovered from agent folders, including the user-owned
$RAVEN_HOME/agents/ tree. Readiness depends on the runtime and any declared
engine wheel being installed in the interpreter that launches the agent.
Restart the resident host after changing a definition to ensure its live roster
is rebuilt. Do not assume that changing a display name creates a new identity.
Set them up through raven onboard or the WebUI agent settings.
From a TUI, WebUI, or configured channel, name the desired roster entry in the
request and state the workspace, allowed side effects, and evidence you expect.
For a DAG node, set subagent to the currently advertised roster name; a
generated worker label is valid only for the current run_subagent_dag call.
Stored Playbooks must use a registered roster name, not a turn-local label. A
display name that is not in the current roster does not select an agent.
Calling the five native agents¶
| Calling surface | Support | Notes |
|---|---|---|
Host delegation through spawn |
All five, when enabled and ready | Ask from the TUI, WebUI, or a configured channel; use the advertised roster name. Raven-PPT normally enters through Raven-Design's route. |
| Stateful instance chat | ACP agents that advertise stateful sessions | Continue an instance from the WebUI instance panel or the corresponding RPC; check the live capability snapshot before relying on resume. |
run_subagent_dag node |
Advertised roster agents | Put the roster name in subagent; generated Worker Table labels are turn-local and cannot be used in stored Playbooks. |
| Playbook | Registered roster agents | A Playbook ultimately dispatches through the same DAG registry; use Raven-Design for the normal Raven-PPT route. |
| Direct ACP over stdio | All five | Start the product launcher and speak newline-delimited JSON-RPC. Raven-Research starts ACP without an --acp flag. |
| One-shot CLI hosting | Raven-Code only | Use its launcher with --task or --prompt-file; --session continues the CLI session. |
| Messaging channels | All host-delegated agents | The channel reaches Raven first; delegation then uses the same roster and permissions. |
| Direct A2A call to one native agent | Not supported | A2A exposes a Raven host, not five independent native-agent endpoints. |
The first four surfaces are host-level ways to delegate work; only direct ACP and Raven-Code's CLI hosting start a native product launcher explicitly. A successful readiness probe or delegation receipt is not evidence that the task completed; inspect the result, files, and tests or report artifacts.
Sharing memory with the host¶
Each native agent runs as a Raven process of its own. Three settings under
subagents.runtime in the host's config.json keep that from costing a whole
Raven per agent. All three are on by default and are read live, so a change
applies to the next launch.
| Key | Default | What it does |
|---|---|---|
idleCloseS |
600 |
Closes an agent's process once it has been idle this many seconds: no request in flight either way and nothing said. An agent that still holds an armed reminder or a running plugin service is kept. Only an agent that can reopen its sessions (it declares loadSession or sessionCapabilities.resume) is closed, so the next turn resumes the session in a fresh process. 0 or null keeps agents until the host exits. |
llmRelay |
true |
The host makes a native agent's LiteLLM calls, so the agent never loads LiteLLM. The agent still builds each request, retries and records usage itself. An agent whose own env sets an LLM endpoint, a cloud credential, a proxy or a CA bundle makes its calls itself. |
forkTemplate |
true |
On Linux, native agents are forked from one process that has already loaded Raven, and share those pages instead of each loading its own copy. Other systems launch agents as before. |
The template loads ahead only the modules at least two native agents share --
one agent's own modules are imported by that agent after the fork -- so it
grows with what the agents have in common, not with how many kinds there are.
It is a process too, so it saves memory once two or more native agents run at
the same time; with a single agent it costs somewhat more than it saves. Set
forkTemplate to false on a device that only ever runs one. An agent the
relay or the template cannot serve -- the host cannot be reached, or the agent
runs on another interpreter -- starts the ordinary way.
Minimal ACP invocation¶
Each shipped entry is started by its launcher. Use the corresponding command:
| Agent | Launcher command | Note |
|---|---|---|
| Raven-Code | python agents/raven-code/run.py --acp |
Also supports one-shot CLI hosting. |
| Raven-Design | python agents/raven-design/run.py --acp |
Requires the design engine. |
| Raven-Oncall | python agents/raven-oncall/run.py --acp |
Requires registered target-machine access for operational work. |
| Raven-PPT | python agents/raven-ppt/run.py --acp |
Normally reached through Raven-Design; requires the PPT engine. |
| Raven-Research | python agents/raven-research/run.py |
ACP is the default hosting; this launcher has no --acp flag. |
Use the interpreter that has Raven and the agent's declared engine wheel installed. Request a deck through Raven-Design in normal use rather than selecting the hidden Raven-PPT route directly.
For example, start Raven-Code:
python /absolute/path/to/Raven/agents/raven-code/run.py --acp
The launcher renders that agent's config and starts raven acp over stdin and
stdout. Send one JSON-RPC object per line; keep logs and wrapper output off
stdout. After the process starts, the smallest useful request sequence is:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/absolute/path/to/project","mcpServers":[]}}
{"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"<session-id-from-session-new>","prompt":[{"type":"text","text":"Reply with one sentence; do not edit files."}]}}
| Field or argument | Meaning |
|---|---|
--acp |
Serve the agent over stdio ACP; it is not an HTTP listener. |
python |
Use the interpreter that has Raven and the agent's declared engine wheel installed. |
protocolVersion |
ACP protocol version requested during the handshake; Raven currently uses 1. |
clientCapabilities |
Features the caller can handle; {} is the minimal declaration. |
cwd |
Absolute task workspace for the session; it is not the agent's ACP home. |
mcpServers |
Per-session stdio MCP attachments; use [] when none are needed. |
sessionId |
The identifier returned by session/new; reuse it for later prompts. |
prompt |
An array of content blocks; the minimal block has type: "text" and text. |
The server may emit session/update notifications between these requests. Read
them, and handle permission or question requests before waiting for the final
prompt response. The full lifecycle and negotiated capabilities are in Agent
Protocols.
Task prompt templates¶
Use the advertised roster name and state the scope, allowed side effects, and evidence you expect. These one-line templates are starting points, not proof that a task can run or has completed:
| Agent | Example request |
|---|---|
| Raven-Code | Raven-Code: inspect the parser in src/parser.py; edit only the parser files; run the matching tests; report the command output. Do not commit or push. |
| Raven-Design | Raven-Design: review this dashboard for hierarchy and accessibility; propose concrete visual changes and save the feedback to the project workspace. |
| Raven-Oncall | Raven-Oncall: run this parameter sweep on the registered lab machine; use a two-hour budget; stop failed workers; compare each round and report the final artifacts. |
| Raven-PPT | Raven-PPT: create a .pptx product-review deck from these notes; use Raven-Design when possible; render every slide and return unresolved issues. |
| Raven-Research | Raven-Research: compare these approaches using sources from the last year; cite material claims with URLs and write the report to the requested workspace file. |
For every agent, verify readiness before a real task and inspect the final answer, generated files, and task evidence afterward. ACP readiness or a listed roster row proves that the process can be started; it does not prove that the task completed successfully.
Raven-Code: workspace and verification boundaries¶
Raven-Code's code-flow adds product behavior beyond an identity prompt. Give
each task a bound project directory, explicit file ownership, allowed side
effects, and a verification command; inspect the files, command output, and
Harness Manifest afterward.
| Area | Boundary |
|---|---|
| Project instructions | AGENTS.md, CLAUDE.md, and CONTEXT.md are read from the working directory under configured selection, path confinement, and prompt budget; they are not Agent-home bootstrap files. |
| File and workspace state | File tools track versions read by the session; with read-before-edit, unread or externally changed versions are refused. Shared checkouts expose the same HEAD and changes; notices and the read ledger are not file locks or worktree isolation, and full writes are not universally guarded. |
| Task state | todo persists per session; completion is a model claim, not test evidence. Existing sessions restore their checklist, while a new task needs a genuinely new session; in-place /new retains the session key and may not reset this product checklist. |
| Git evidence | The Harness Manifest reports changes, commits, blockers, and shared-workspace attribution in ACP response metadata; do not infer Git facts from “ready”. |
| Product configuration | The Raven-Code launcher enables its product configuration. Installing code-flow elsewhere does not enable every capability; notices/reports and the replacement tool face have separate gates. |
Request example: “Inspect project instructions, fix this parser bug in the owned files only, run matching tests, and report remaining changes or blockers. Do not commit or push.”
For follow-ups read Working with sub-agents; for background jobs read Long-running work (Oncall). See the implementation case study for the launcher and harness details.
Connect external agents¶
The following presets are declared in the current source. This is a list of supported configuration paths, not a claim that every vendor release or your local installation has passed a live task.
| Preset key | Transport and launcher | Check before use |
|---|---|---|
claude_code |
ACP adapter via npx |
Adapter download/runtime and the child's authentication |
codex |
ACP adapter via npx |
Preset sets INITIAL_AGENT_MODE=agent-full-access; assess host and network access |
opencode |
opencode acp |
Current preset withholds session MCP delivery via sessionMcp: false |
hermes |
hermes acp --accept-hooks |
Native authentication; the flag accepts previously unseen shell hooks |
openclaw |
openclaw acp |
Its gateway and authentication; startup has a longer handshake allowance |
minimax_code |
mcode acp |
Native ACP server; requires Node.js 22.19-22.x or 24-26.x. Install the CLI with npm install -g @minimax-ai/code --allow-scripts=@minimax-ai/code,better-sqlite3 (npm 12 blocks install-time scripts without the approval; npm 11 and older run the scripts anyway, and the ones that do not know the flag warn about it and still install) and sign in with mcode login -- adding --region global (or --region cn) when the account is not on the cn region, which is the account site the CLI defaults to. If the desktop app already holds the login, set MINIMAX_DATA_DIR to the absolute path of its data directory (the folder ~/.minimax, e.g. /Users/<you>/.minimax or C:\Users\<you>\.minimax), either in that agent's env map in ~/.raven/config.json, or in the environment Raven launches agents from (a POSIX login shell is read again when the page's "Check again" runs; a Windows child inherits Raven's own environment, so restart Raven there). |
dsh |
dsh --profile acp |
DSH installed (npm install -g @deepseek-ai/dsh, Node.js 24.9 or newer) and signed in; it declares session/resume and no loadSession, so Raven continues its sessions with session/resume |
mirothinker |
OpenAI-compatible HTTP | Endpoint/model/key; preset opts out of stateful replay |
mirasim_<agent> |
Raven's own ACP adapter over the Mirasim host's protocol | Mirasim installed on this computer and running, and the agent installed inside it. The rows are offered when Raven finds Mirasim: a host to reach (a port a Mirasim host wrote its token for, such as the desktop app's or mirasim serve's, or the socket of a server Mirasim runs here over ssh, either one answering), else the launcher Mirasim writes under its home (~/.mirasim/bin/mirasim, which it puts on no PATH), mirasim on the login shell's PATH, or a server a Mirasim installed here over ssh (~/.mirasim-remote); a row whose Mirasim is installed but not running says to open the app or start mirasim serve, or to let the app on another computer reach this one again. Session MCP withheld via sessionMcp: false |
GitHub Copilot, Qwen Code, CodeBuddy, Qoder, Grok Build, Kimi Code, and Pi also
have preset entries. Adapter versions and exact commands are maintained in
raven/agent/subagent/presets.py, raven/agent/subagent/acp_registry_presets.py,
and raven/agent/subagent/mirasim_presets.py.
Prefer the installed version's preset instead of reconstructing its flags.
The mirasim_* presets reach the agents Mirasim runs, one
row each: Claude Code, Codex, Kimi Code, Antigravity, Qwen Code, Grok Build, DSH,
Pi and ZCode CLI, named Claude Code-Mirasim and so on. Such a row is the agent on
the accounts and model routes set in Mirasim, which is why it can sit beside the
same agent's own preset. The adapter ships with Raven (raven/acp/mirasim/), so
nothing is downloaded; the {PYTHON} in its command becomes Raven's interpreter
when the row is written to config; if that interpreter is later gone, as after an
install moves, the row is pointed at the one serving Raven the next time the config
is read. Its model list is Mirasim's for that agent,
grouped under the agent's own name, Mirasim (the platform's quota) and Own key
(keys you added to Mirasim). Mirasim's platform also runs the own models of Claude
Code, Codex, Kimi Code and ZCode CLI, so for those four each such model is listed in
both of the first two groups: under the agent's name it runs on your own account,
under Mirasim on the platform's quota. Every turn names the route its model
runs on, so choosing the other one moves an existing session to that route
from its next turn. A session with no model chosen runs on Mirasim's default for
the agent, route included.
The adapter is one more client of the Mirasim host already running on the
machine -- the desktop app's, the one mirasim serve runs, or the one Mirasim
keeps on a machine it reaches over SSH -- so it starts nothing of its own, and Raven's turns show in the Mirasim
app as they run. A turn streams: its thinking, text, tool calls, plan and the
files it delivers reach Raven as they happen, and the context it used is reported
when it ends. A cancel stops the turn. Text sent to a running turn is taken into
it for Claude Code, Codex, DSH, Pi and ZCode CLI. Images reach Claude Code
inline; another agent gets an image linked as a local file as that file's path,
and refuses one sent inline. Sessions can be listed -- this agent's
sessions in the given directory, including ones begun in Mirasim itself --
resumed, loaded with their whole history, closed and deleted. Deleting one
also deletes its Mirasim session; the agent's own transcript files stay
where it keeps them. A turn Mirasim starts on its own in a session Raven holds,
such as a background job's report, is forwarded to Raven too, and what it stops
to ask is left to the Mirasim app.
The adapter looks for the host in this order: the socket of the host Mirasim
keeps on a machine it reaches over SSH (~/.mirasim-remote/run/server.sock,
Linux and macOS only), then every loopback port a host wrote its token for, as
run/local-<port>.token under Mirasim's state directory (MIRASIM_HOME, else
~/.mirasim): the desktop app's 4970 first, then 4939, where
mirasim serve listens unless told otherwise, then the rest in ascending
order. The first that answers is the host, and a port with a token file counts
as answering only when its /api/health names a Mirasim host: the token that
file holds goes only to a host that identified itself, not to whatever else may
hold the port by then. A host whose health cannot say is still reachable by
naming it in RAVEN_MIRASIM_HOST. A host writes its file for the port
it actually bound, so one that moved on because its own port was taken is still
found, a file a killed host left behind is passed over, and a host that comes
back on another port is found there when the adapter reconnects. When the host
listens anywhere else,
RAVEN_MIRASIM_HOST names it: unix:<path> for a socket (not on Windows, where
the desktop app's port is the way in), or a loopback port as <port>,
127.0.0.1:<port>, localhost:<port> or [::1]:<port>. On Linux and macOS
the adapter runs with the login shell's environment plus the row's own env,
not Raven's, so set the variable in your shell profile, or in the env of the
Mirasim rows that should use it; exported only in the shell that starts Raven,
it does not reach them. On Windows the adapter inherits Raven's own
environment, so setting it where Raven starts is enough.
What a turn Raven started stops to ask is put to Raven while the turn
waits: a tool approval as a permission request, and a
question -- Claude Code's AskUserQuestion when Mirasim's askTool setting is
on, or an MCP server's form -- as an elicitation, answered by you or by Raven's
question autofill. A client without forms has the question skipped and named in
the reply.
Question text, choices, replies and error details retain the sending agent's
content. Raven leaves redaction decisions to that agent, including when a
returned value matches a credential Raven itself holds.
Distinguish three claims when assessing compatibility:
- Preset declared: Raven has a configuration template.
- Handshake/probe successful: this installation starts and reports capabilities.
- Task verified: a real task exercised authentication, tools, and output.
Hand-written integrations need their own checks at all three applicable levels.
Connect and verify¶
- Install and authenticate the external agent according to its own version.
Ensure its executable is on the resident Raven process's
PATH. - Configure it from the WebUI's agent setup, or add a row to
subagents.agentsin the host config. Preserve existing rows and settings. - Inspect the configured row and readiness result. ACP probing may launch a process and a shim may download code; a full task test can spend provider quota.
- Run a harmless task such as “Reply with one sentence; do not edit files.” Then verify any required file, tool, or resume capability separately.
- Enable broader delegation only after checking permissions and isolation.
A minimal custom ACP entry using an already installed Hermes executable:
{
"subagents": {
"agents": [
{
"name": "Hermes Agent",
"preset": "hermes",
"kind": "acp",
"enabled": true,
"command": "hermes acp --accept-hooks",
"cwd": "/absolute/path/to/project",
"readyTimeoutMs": 30000,
"timeout": 600
}
]
}
}
This is a fragment to merge, not a replacement for your config. The hook flag
has the security consequence stated above. ACP command launches a server:
do not put {prompt}, {prompt_file}, or {agent_id} into it.
readyTimeoutMs limits the handshake; timeout limits a task. The latter
defaults to no automatic deadline when omitted.
For a CLI backend, command is an argv template. {prompt} is substituted as
one argument, {prompt_file} names a prompt file, and no placeholder means
stdin delivery. A resumeCommand must use {agent_id}; id provisioning and
transcript parsing must agree with the CLI. Do not copy those fields into ACP.
For an HTTP backend, configure baseUrl, model, and credentials instead of
a command. Host-side replay may provide session history, but it is not a
remote native session. This backend cannot read local paths or accept MCP
delivery. An OpenAI-compatible agent endpoint is distinct from changing Raven's
main model provider.
Files, state, and credentials¶
| Location or handle | Responsibility |
|---|---|
| User working directory | Files the task is authorized to read or change |
| Host Agent home | Host identity, sessions, skills, and memory |
| Agent state root | Launcher-rendered config and agent working state |
| Agent ACP home | The child engine's identity, transcripts, and skill pool |
instance |
Continue a child session where that backend supports it |
| Node id | Address a recorded task/output in the host session |
A CLI's readsLocalFiles is a declaration about its environment. ACP
capabilities are negotiated and interpreted by its adapter. The HTTP backend
has no local file access: send bounded content, not a host path. Configure
memory identities only when that agent actually supports the intended memory
path; adding metadata does not make an external product share Raven's memory.
Keep credentials out of prompts and shared manifests. A2A credentials are matched by origin, not by agent display name; its peer list is not an egress firewall. Follow the A2A guide.
The prompt files a native agent keeps in its ACP home -- soul.md and
agent.md under agent_memory/profile/, and TOOLS.md -- are regenerated
from the release and its config on every launch, so editing them in place
does not last. Put your own lines in the sibling *.local.md file
(agent_memory/profile/agent.local.md, for example); the next launch appends
it after the product text. Copy in only what you still need: text from an
older release can contradict the current one. Save it as UTF-8; a file in
another encoding (an editor's legacy code page, GBK for example) stops the
launch, and the error names it. A file that was edited in place,
or that an older release left behind, is saved as <name>.bak-<time>-<pid>
before it is replaced, and the launcher log names the backup. The regenerated
file keeps the access rights the old one had. On Windows the backup is a hard
link to the file, so it keeps them too; on a volume that cannot hard-link, the
launch stops and names the file instead.
Backups are not deleted for you.
Raven-PPT differs in one respect: its deck engine can share a home with the
host, so it replaces only a file it can show it wrote. A soul.md, agent.md
or TOOLS.md edited before this release is left as it is, without a backup,
and its *.local.md is not applied. Move the lines you still need into the
*.local.md file and delete the edited one; the next turn writes it fresh. A
write the engine cannot make is logged and retried on the next turn instead
of stopping it.
Security and troubleshooting¶
Outbound ACP automatically prefers an offered allow option. The parent's permission mode does not provide per-tool human review inside every external agent. Review native permissions, account privileges, writable mounts, hooks, and network access before using unattended delegation.
| Symptom | Check |
|---|---|
| Agent absent from the selectable roster | Discovery, enabled/hidden status, routing, readiness |
| Engine unavailable | Required wheel in the child interpreter, not merely another virtualenv |
| Handshake passes, task fails | Provider credentials, tool prerequisites, child stderr |
| CLI output missing or garbled | Exit status, transcript format, output parser |
| Instance does not continue | Resume contract and negotiated session support |
| MCP selection not delivered | Backend support and sessionMcp isolation policy |
| Remote agent cannot open a file | Content versus host-path transfer |
For graph failures see DAG Orchestration. For permissions and isolation see Permissions and Security.