Adapters Overview - Army of Agents

Adapters are the bridge between AoA’s orchestration layer and agent runtimes. Each adapter knows how to invoke a specific type of AI agent and capture its results.

How Adapters Work

When a heartbeat fires, AoA:

Looks up the agent’s adapterType and adapterConfig
Calls the adapter’s execute() function with the execution context
The adapter spawns or calls the agent runtime
The adapter captures stdout, parses usage/cost data, and returns a structured result

Built-in Adapters

Adapter	Type Key	Description
Claude Local	`claude_local`	Runs Claude Code CLI locally
Codex Local	`codex_local`	Runs OpenAI Codex CLI locally
OpenCode Local	`opencode_local`	Runs OpenCode CLI locally (multi-provider `provider/model`)
Cursor	`cursor`	Runs Cursor Agent CLI locally
OpenClaw	`openclaw`	Runs an OpenClaw agent remotely (SSE or webhook transport)
Process	`process`	Executes arbitrary shell commands
HTTP	`http`	Sends webhooks to external agents
Gemini Local	`gemini_local`	Runs Gemini CLI locally with session resume support
Hermes Local	`hermes_local`	Runs Hermes Agent (Nous Research) locally via the `hermes` CLI

Adapter Architecture

Each adapter is a package with three modules:

packages/adapters/<name>/
  src/
    index.ts            # Shared metadata (type, label, models)
    server/
      execute.ts        # Core execution logic
      parse.ts          # Output parsing
      test.ts           # Environment diagnostics
    ui/
      parse-stdout.ts   # Stdout -> transcript entries for run viewer
      build-config.ts   # Form values -> adapterConfig JSON
    cli/
      format-event.ts   # Terminal output for `aoa run --watch`

Three registries consume these modules:

Registry	What it does
Server	Executes agents, captures results
UI	Renders run transcripts, provides config forms
CLI	Formats terminal output for live watching

Choosing an Adapter

Need a coding agent on the local machine? Use claude_local, codex_local, opencode_local, cursor, gemini_local, or hermes_local
Need to run a script or command? Use process
Need to call an HTTP endpoint or external service? Use http
Need to run a remote OpenClaw agent? Use openclaw
Need something custom? See creating-an-adapter.md

​How Adapters Work

​Built-in Adapters

​Adapter Architecture

​Choosing an Adapter

How Adapters Work

Built-in Adapters

Adapter Architecture

Choosing an Adapter