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.

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.

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.

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

v1 scope

What this release does not do yet (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.
• No fs/* proxying. The agent does its own filesystem access within cwd; OMA does not yet proxy ACP file operations through its sandbox. Agents that require the client to serve files are not supported.
• Process backend is stateless. It starts one subprocess per run 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; usage_update.cost is ignored.
• ACP subprocess lifetime. An orchestrated ACP agent’s subprocess lives until the process exits (there is no per-agent disposal hook in runTeam / runTasks). Use the programmatic API + dispose() when you need explicit teardown.