Which adapter should I use?¶
Muxlio runs workflow steps through executor capabilities (for example
agent/codex or agent/a2a). Each capability is implemented by an adapter
binary on the worker. Pick an adapter based on where the agent runs, how you
authenticate, and which protocol features you need.
This guide explains the three onboarding paths. Configuration limits and protocol details for ACP and A2A remain authoritative in the CLI and SDK reference — Run with real adapters. A2A recovery and polling are summarized under Recovery and limits in the service reference.
Three ways to run an agent step¶
Native CLI adapters (recommended when a provider CLI is installed)¶
Shipped executors: agent/antigravity, agent/claude, agent/codex,
agent/cursor, and agent/kiro.
Each adapter runs that vendor's installed CLI in the attempt workspace. Setup is
the same as using the CLI directly: install it, sign in, and list the capability in
~/.muxlio/config.json if you restrict workers. Steps run locally on the
worker. Provider streaming and tool activity appear in Muxlio live logs when the
CLI emits them (progress capability). These adapters report token usage when
the provider supplies it; they do not treat context-window occupancy as consumed
tokens.
Use a native adapter when you want provider-specific behavior (models, tools, billing) without implementing a protocol yourself.
Generic local agents — Agent Client Protocol (ACP)¶
Executor: agent/acp.
Runs any ACP protocol version 1 agent over stdio (program + args in task
params). The agent must speak JSON-RPC on stdin/stdout. This path is for
local agents you build or install separately (placeholders such as
/absolute/path/to/acp-compatible-agent in examples).
Setup highlights:
- Executable and args — passed directly; no shell.
- Host authorization —
executors.agent/acp.allow: truein worker config (requiresHostExecution). - Authentication — configure the agent's credentials in the executor environment; authenticate the agent before running workflows (Muxlio does not invent ACP login commands).
ACP negotiates protocol v1 only. Permission prompts, durable sessions, session loading, client FS/terminal services, remote tasks, and native typed generation are unsupported even if the agent advertises them. Token usage is unavailable; context-window or cost hints from the agent are not token totals.
Remote agents — Agent2Agent (A2A)¶
Executor: agent/a2a.
Talks to a remote agent over HTTP using A2A 0.3.0 JSON-RPC. The worker
submits work and can exit while the remote task continues (remote task
capability). Durable workflows should set retry.effect to reconcilable (or
reconcile) and requiredCapabilities: { remoteTask: "1" } so polls and
reconciliation use the remote task identity without resubmitting.
Setup highlights:
- Agent Card — discovered at
/.well-known/agent-card.jsonfromparams.url(optionalcardUrlon the same origin). - Bearer secret — map
A2A_TOKENthrough the worker shared request secret mechanism, not workflow parameters or URLs. - Remote capabilities — the card must expose a compatible JSON-RPC interface;
stream: truerequires advertised streaming. - Cancellation — local cancel stops the adapter process; it does not cancel remote work.
Submissions without a task ID stay inconclusive on reconcile. The adapter does not advertise idempotency keys (A2A message IDs are not deduplication guarantees). Token usage is unavailable.
Capability comparison (bundled adapters)¶
Values below come from shipped adapter.json manifests and adapter behavior as
of this release. Unsupported means the capability flag is absent or false and
the adapter must not emulate it. Unavailable for accounting means usage/cost is
not reported (missing usage stays nil; reported zero is zero).
| Capability | Native CLI (agent/claude, codex, cursor, kiro, antigravity) |
agent/acp |
agent/a2a |
command |
|---|---|---|---|---|
| Protocol | Provider CLI (no single protocol version) | ACP v1 | A2A 0.3.0 JSON-RPC | Child process argv |
| Setup / auth | Install + sign in to vendor CLI; optional agentHome |
allow: true, agent env + out-of-band agent login |
A2A_TOKEN bearer secret, HTTPS (loopback HTTP allowed) |
allow: true for host execution |
| Execution locality | Local worker | Local stdio child | Remote HTTP agent | Local child process |
| Artifacts / outputs | Yes (artifacts) |
Yes | Yes (bounded; no URI fetch) | Yes |
| Live progress / streaming | Yes (progress); provider-dependent |
Yes (session updates in logs) | Yes (progress); optional stream: true + resubscribe |
Yes (command output previews) |
| Mid-run cancel | No (cancel not advertised) |
Yes (session/cancel) |
No remote cancel; local stop only | Yes (signal child) |
| Durable sessions | No | No (ACP session IDs are not Muxlio checkpoints) | No | No |
| Interactive permissions | Provider-defined | Denied explicitly | N/A (remote agent) | N/A |
| Remote task handoff | No | No | Yes (remoteTask) |
No |
| Reconcile / idempotency | No reconcile; no idempotencyKey |
No | Reconcile yes; idempotency keys not advertised | No |
| Token / credit / cost reporting | Canonical accounting when the provider reports consumption |
Native ACP cost/credit delta only with a pre-prompt baseline | Unavailable | Unknown unless explicitly reported |
| Host execution gate | No | Required | No | Required |
Do not expect full protocol coverage
ACP and A2A adapters implement the subsets documented in Run with real adapters. Unsupported card extensions, auth modes, input modes, or protocol versions fail closed at invocation.
Minimal examples¶
Compile and dry-run without live agents using the fake executor (same pattern as
other examples/ workflows):
npm run build
muxlio check examples/acp.workflow.ts --json
muxlio check examples/a2a.workflow.ts --json
muxlio test examples/acp.workflow.ts --input examples/acp.input.json \
--fake-config examples/acp.fake.json --json
muxlio test examples/a2a.workflow.ts --input examples/a2a.input.json \
--fake-config examples/a2a.fake.json --json
ACP — local stdio agent¶
Workflow: examples/acp.workflow.ts.
- Build or install an ACP v1-compatible agent binary.
- In
~/.muxlio/config.json:
{
"executors": {
"agent/acp": {
"allow": true,
"env": {
"MUXLIO_ACP_PROGRAM": "/absolute/path/to/acp-compatible-agent"
}
}
}
}
- Authenticate the agent using its own instructions, then run:
Replace params.program in the workflow or rely on MUXLIO_ACP_PROGRAM for the
default executable used by the probe.
A2A — remote Agent Card¶
Workflow: examples/a2a.workflow.ts.
- Deploy or select an A2A 0.3.0 agent with
remoteTasksupport on the card. - Configure a worker secret handle that resolves to
A2A_TOKEN(see execution security). For example, map the handle to the name of an environment variable that contains your token:
The example workflow declares secretRefs and allows that secret name; the
token value never belongs in the workflow or its input file.
3. Set params.url to the agent origin (placeholder https://agent.example in
the example). The adapter discovers the Agent Card at
/.well-known/agent-card.json; the card must advertise A2A 0.3.0 and a
compatible JSON-RPC endpoint.
4. Run through the service so reconcile and polling apply. Muxlio polls by the
durable remote task identity. Local cancellation stops its adapter process
but leaves remote work running:
For ambiguous remote outcomes, see Recovery and limits and Run with real adapters — agent/a2a.
Providing a compatible agent¶
| Path | You provide |
|---|---|
| Native CLI | Vendor CLI on PATH or in agentHome, already authenticated |
| ACP | Executable implementing ACP v1 initialize → session/new → prompt → declared output files under paths Muxlio passes |
| A2A | HTTPS (or loopback) origin with valid Agent Card, JSON-RPC task API, artifacts named for output ports; bearer auth if required |
Conformance fixtures in muxlio-adapters/tests/conformance/ exercise ACP and A2A
adapters without paid external services.
Documentation site (GitHub Pages)¶
Published docs: https://muxlio.github.io/muxlio/
- Build:
pip install -r .github/requirements-docs.txt && mkdocs build --strict - Deploy:
.github/workflows/docs.ymlon pushes tomain(docs paths only). Pull requests build and upload a preview artifact; they do not deploy. - Repository setting (one-time): GitHub → Settings → Pages → Build and
deployment → Source: GitHub Actions (not a branch). No extra permissions are
required beyond the workflow's scoped
pages: writeon deploy jobs.