External agents

OMA can orchestrate external agents that run as local processes alongside its LLM-backed agents. Two backend kinds are built in:

• process starts a generic local command for each agent run, sends the prompt by stdin or argument, and maps stdout/stderr/exit status into a normal agent result.
• acp drives a coding agent over the Agent Client Protocol (ACP) — a JSON-RPC-over-stdio standard implemented by Gemini CLI, Claude Code, Codex, and others.

An external agent is a first-class team member: it sits in the same task DAG, writes to the same shared memory, cascades failure to its dependents, and returns the same result shape as any LLM agent. The motivating shape is a hybrid team — an LLM planner decomposes the goal, an external coding agent writes the code, an LLM reviewer audits the diff — all in one runTeam / runTasks call.

Quick start

Declare an agent with backend instead of a model. Everything else about the team is unchanged:

import { OpenMultiAgent } from '@open-multi-agent/core'

const oma = new OpenMultiAgent({ defaultModel: 'claude-sonnet-4-6', defaultProvider: 'anthropic' })

const team = oma.createTeam('hybrid-dev', {
  name: 'hybrid-dev',
  agents: [
    { name: 'planner',  systemPrompt: 'Break the task into a short plan. Do not write code.' },
    {
      name: 'coder',
      systemPrompt: 'Writes and edits code by running an external coding CLI.',
      backend: {
        kind: 'process',
        command: 'node',
        args: ['scripts/code-agent.js'],
        cwd: process.cwd(),
      },
    },
    { name: 'reviewer', systemPrompt: 'Review the change and summarize risks. Do not edit files.' },
  ],
  sharedMemory: true,
})

const result = await oma.runTeam(team, 'Add a slugify() utility with tests, then review it.')

The coordinator routes the coding work to coder based on its roster description; the subprocess does the file edits; reviewer then reads the result from shared memory.

A runnable process version is at examples/integrations/external-agent-process.ts. A runnable ACP version is at examples/integrations/external-agent-acp.ts.

Installation

The process backend has no extra dependencies. It uses Node's built-in child process APIs and starts whatever local command you configure.

ACP support requires the optional peer dependency, loaded lazily so it never affects consumers that don't use ACP:

npm install @agentclientprotocol/sdk

You also need an ACP-speaking agent. Set the backend's command / args to launch it — any ACP agent works. Common choices:

Agent	command / args	Notes
Claude Code	npx -y @agentclientprotocol/claude-agent-acp	Official Claude Agent SDK adapter (Claude Code has no native ACP). Auth via ANTHROPIC_API_KEY.
Gemini CLI	gemini --acp	Native ACP. Note: Google is reportedly retiring the free-tier Gemini CLI (and its --experimental-acp flag) — verify availability before relying on it.
Codex	codex-acp (or codex --experimental-acp)	Experimental ACP support.

The ACP examples in this guide use Claude Code, which fits OMA's Anthropic-centric default and needs only one key (ANTHROPIC_API_KEY) for the whole team.

Configuration

AgentConfig.backend takes an ExternalAgentBackendConfig discriminated union:

Field	Type	Default	Meaning
kind	'process' | 'acp'	—	Backend discriminant.
command	string	—	Executable to spawn ('npx', 'gemini', …).
args	string[]	[]	Arguments passed to command.
env	Record<string,string>	—	Extra env vars, merged over process.env.
cwd	string	process.cwd()	Working directory for the subprocess.
input	'stdin' | 'argument' | 'none'	'stdin'	process only: how to pass the prompt to the command.
permission	'auto-approve' | 'reject' | fn	'auto-approve'	acp only: how to answer permission prompts (below).

When backend is set, the LLM-specific fields (model, provider, adapter, sampling, tools, context strategy) do not apply — the external agent runs its own loop, and model becomes optional. The agent's systemPrompt is the exception: it still shapes the external agent because OMA — lacking any ACP system-prompt field — prepends it to the agent's first prompt (once per session), on top of seeding the coordinator's routing as it does for every agent.

External backends have a text transport boundary. Their public Agent APIs accept the existing string form, but reject structured LLMMessage[] / ContentBlock[] arguments with InvalidMessageError before spawning a process or opening an ACP session. This avoids silently dropping image blocks or caller-owned history. beforeRun.prompt remains supported; changing beforeRun.messages is rejected for the same reason. AgentConfig.history does not seed a process or ACP session; it restores messages only for LLM-backed prompt() conversations. See Structured agent input.

For process, OMA starts a fresh subprocess per run. Use input: 'stdin' for commands that read a prompt from stdin, input: 'argument' when the command expects the prompt as the final argument, and input: 'none' for fixed adapters that derive their work from files or environment.

ACP permissions

ACP agents ask the client to approve sensitive tool calls (editing a file, running a command). Because OMA runs agents autonomously inside a DAG, the default is 'auto-approve' (it picks the least-privilege allow_once when offered, otherwise allow_always). Tighten it as needed:

backend: {
  kind: 'acp',
  command: 'npx',
  args: ['-y', '@agentclientprotocol/claude-agent-acp'],
  // Reject everything…
  permission: 'reject',
  // …or decide per request.
  permission: (req) => req.kind !== 'delete' && !req.title.includes('rm -rf'),
}

The callback receives a minimal, SDK-agnostic { title, kind, optionKinds } and returns true to approve / false to reject.

Security. Unlike OMA's filesystem-tool sandbox, external backends access cwd directly — they are local subprocesses with your permissions. Scope cwd to a project you trust the backend with. ACP backends can use permission to gate protocol permission prompts; process backends do not have protocol-level permission prompts, so constrain the configured command, args, env, and cwd. egressPolicy governs enforceable framework-owned LLM requests only; it does not constrain network calls made by process or ACP children. See the egress enforcement matrix.

How it works

Both built-in backends implement the same AgentBackend interface (run + stream) that AgentRunner already implements. The pool, scheduler, task queue, shared memory, and budget aggregation can therefore treat an external agent like an LLM agent, with no special cases.

Process backend

The process backend starts a fresh subprocess for each run. It joins the configured systemPrompt and user prompt, passes the result to the command, and maps process outcomes as follows:

Process outcome	Maps to
stdout + exit 0	success; stdout becomes result.output
stderr + exit 0	success; stderr is ignored unless the process writes it into stdout
exit code / signal	task failure; stderr is redacted and included in the error output
caller abort	cancellation; the child process is killed
no token signal	tokenUsage is {0, 0}

Use this backend for simple local CLIs, scripts, or adapters that do not need a long-lived agent protocol.

ACP backend

OMA takes the ACP client role. On the first run for an agent it spawns the subprocess, frames its stdio as newline-delimited JSON-RPC, initializes, and opens a session/new in cwd. Each agent.run(prompt) then sends one session/prompt turn and drains session/update notifications into a normal agent result:

ACP update / stop	Maps to
agent_message_chunk (text)	streamed text deltas + the result's output
tool_call / tool_call_update	entries in result.toolCalls
usage_update (used)	result.tokenUsage (see caveat)
stop end_turn	success
stop max_tokens / max_turn_requests	success with budgetExceeded (stopped early)
stop refusal	task failure (cascades to dependents)
stop cancelled	returns partial output (from an abort)

ACP token accounting caveat

ACP reports a single context-token figure (usage_update.used — "tokens currently in context"), not an input/output split, and it is cumulative across a session, not a per-turn delta. Because OMA reuses one session across an agent's turns, it records each turn's usage as the increment since the previous reading and stores it as tokenUsage.input_tokens (with output_tokens: 0) — so summing across turns telescopes to the latest figure instead of double-counting. That total aggregates into the run and honors maxTokenBudget. An agent that emits no usage_update reports {0, 0} and is therefore not budget-gated — size the budget on LLM agents, or bound the ACP agent with its own --max-* flags.

On a Hybrid runTeam() Single short circuit, semantic-profiler usage is charged before the external backend starts. The backend's reported usage is then added at the run boundary, so an ACP usage delta can exhaust the remaining run budget. The process backend continues to contribute {0, 0} because it has no token signal.

Control boundary

An external agent is a first-class team member at the orchestration layer and an opaque subprocess below it. The split is structural rather than a policy choice: when AgentConfig.backend is set, the agent resolves to the external backend and never constructs an AgentRunner, and the runner is where the tool registry, the tool executor, the filesystem sandbox, the context strategy, and the per-turn journal emission all live. Everything the orchestrator does around a task still happens; everything the runner does inside one does not.

Still applies. These are enforced above the backend and are backend-agnostic:

Control	Where it acts
Task DAG placement, dependency ordering, and failure cascade to dependents	Task queue and scheduler; a failed external task skips its dependents like any other
onPlanReady, onApproval, and onTaskDispatch gates	Orchestration level, so the assignee's backend kind is irrelevant to them. onTaskDispatch in particular runs immediately before dispatch and before the backend is resolved, so rejecting it means the subprocess is never spawned
Token budget	The backend's reported usage aggregates into the run and is checked against maxTokenBudget. Read the accounting caveat first: an ACP agent that emits no usage_update, and every process-backend agent, contributes {0, 0} and is therefore not budget-gated in practice
Shared memory	The orchestrator writes the completed task's output to shared memory under task:<id>:result after the task finishes
Run and task journal events	run/start, run/end, plan/set, task/status, memory/set, approval/request, approval/decision, and checkpoint/saved are emitted by the orchestrator and task-execution layers
Abort propagation	RunOptions.abortSignal reaches both backends. The process backend kills the child's process tree. The ACP backend sends session/cancel and relies on the agent to stop, so cancellation there is cooperative and the subprocess stays alive for the next turn
Process stderr redaction	A non-zero exit or signal builds its error message through the shared credential redactor, so stderr is scrubbed before it reaches the task result

Does not apply. None of these reach an external backend, and no configuration makes them:

Control	Why not
onToolCall per-call gate	The gate is evaluated by the tool executor inside AgentRunner. An external agent's tool calls never pass through it. ACP tool_call updates still populate result.toolCalls, but that is reporting, not a gate
Filesystem sandbox	AgentConfig.cwd scopes the built-in filesystem tools through that same runner. A backend's cwd is a plain working directory the subprocess reads and writes directly, with your process's permissions
egressPolicy	Scoped to framework-owned LLM requests. External backends and tool code are outside it by design, and the child owns its own network behavior. See the egress enforcement matrix
Tool-level journal events	turn/start, turn/end, user/message, assistant/message, llm/request, tool/call, tool/result, and context/replace are emitted only by the runner. Neither backend reads the journal recorder it is handed, so a journaled run records that an external task ran, not what happened inside it
Mid-task checkpoints	Neither backend calls the runner checkpoint hook, so an external task checkpoints at task boundaries only. A suspend tool decision fails closed there; see durable approvals

ACP permissions default to auto-approve. permission defaults to 'auto-approve', so unless the application sets it, every permission prompt the agent raises is answered yes. OMA picks the least-privilege option offered (allow_once before allow_always), which bounds the blast radius of one decision but does not change the default answer. 'reject' or a callback is the only way to make a permission prompt a real gate. The process backend has no protocol-level permission prompts at all, so the configured command, args, env, and cwd are the entire control surface.

Programmatic API

Most users only touch backend. To construct a backend directly, import from the matching subpath:

import { createAcpBackend } from '@open-multi-agent/core/acp'
import { createProcessBackend } from '@open-multi-agent/core/process'

const processBackend = createProcessBackend({ command: 'node', args: ['agent.js'] })
const processResult = await processBackend.run([{ role: 'user', content: [{ type: 'text', text: 'summarize' }] }])

const backend = createAcpBackend({ command: 'npx', args: ['-y', '@agentclientprotocol/claude-agent-acp'] })
const result = await backend.run([{ role: 'user', content: [{ type: 'text', text: 'refactor foo.ts' }] }])
await backend.dispose() // close the connection and kill the subprocess

Current limits

What the built-in backends do not do (open an issue with a real use case to pull any of these forward):

• Client role only. OMA drives external agents; it does not expose OMA agents as an ACP agent to editors. The backend builds an ACP client and registers exactly one handler on it, for session/request_permission.
• No fs/* proxying. OMA advertises empty clientCapabilities on initialize, so the agent does its own filesystem access within cwd rather than routing file operations back through OMA's sandbox. Agents that require the client to serve files are not supported.
• Process backend is stateless. It starts one subprocess per run, holds no session between runs, and maps stdout to output. Use ACP or a custom backend when you need sessions, structured tool events, or protocol-level permission prompts.
• No cost-based budgets. Budgeting is token-based. The ACP backend reads only usage_update.used; usage_update.cost is ignored.
• ACP subprocess lifetime. An orchestrated ACP agent's subprocess lives until the process exits. AcpBackend.dispose() exists but nothing in runTeam / runTasks calls it, so use the programmatic API and call dispose() yourself when you need explicit teardown.