ACP Spec Format

An ACP protocol is a YAML file that defines how agents coordinate. This page documents every top-level key and nested schema.

Top-level structure

acp: "1.0"           # Protocol version (required)
name: my-protocol     # Machine identifier (required)
title: My Protocol    # Human-readable title
description: ...      # What this protocol does

roles: { ... }        # Agent types
phases: { ... }       # Workflow stages
resources: [ ... ]    # Claimable items
rules: { ... }        # Per-role per-phase steps
governance: { ... }   # Budget, heartbeat, quorum
variables: { ... }    # Parameterization
topics: [ ... ]       # Cross-namespace pub/sub

Roles

Define agent types with capabilities and constraints.

roles:
  reviewer:
    description: "Review code for correctness"
    count: "2+"                    # min 2, no max
    model_hint: sonnet             # suggested model
    scope: ["src/**"]              # file access scope
    primitives:
      env: [read_file, grep]       # environment tools
      acp: [publish, get_state]    # coordination tools
    wait:
      types: [review.requested]    # sleep until this event
      max_timeout: 300000          # wake after 5min regardless
    reasoning_effort: medium       # low | medium | high
    context: 1                     # context windows to maintain

Count formats

Format	Meaning
1	Exactly one agent
"2+"	At least 2, no maximum
"1-3"	Between 1 and 3
[2, 5]	Between 2 and 5 (array form)
{ default: 3, min: 1, max: 10 }	Full config
0	Human-controlled (no AI agent spawned)

Primitives

Environment primitives (env): read_file, write_file, patch_file, list_files, glob, grep, shell, git_status, git_diff, git_commit, git_log, fetch, scrape

ACP primitives (acp): publish, claim, release, get_state, set_state

Phases

Workflow stages with automatic transitions.

phases:
  review:
    description: "Reviewers examine code changes"
    exit_condition:
      state_key: phase
      equals: revision
    allowed_transitions: [revision, done]
    timeout_ms: 600000

  revision:
    description: "Author addresses feedback"
    exit_condition:
      event: revision.complete
    allowed_transitions: [review, done]

Exit conditions

Type	Example
State key equals value	{ state_key: "phase", equals: "done" }
Event received	{ event: "review.complete" }
Timeout	{ timeout_ms: 300000 }

Resources

Named items that agents can claim (mutex locks).

resources:
  - name: "file:src/api.ts"
    description: "The API source file"
  - name: "task:deploy"
    description: "Deployment task"
    max_claims: 1

Rules

Per-role per-phase step sequences.

rules:
  reviewer:
    review:
      steps:
        - action: external
          description: "Read the code changes"
        - action: publish
          event: feedback
          description: "Share review feedback"
        - action: set_state
          key: reviewed_by_${agent_id}
          value: "true"

Step actions

Action	What it does
external	Agent performs work outside ACP (reads files, writes code)
publish	Publish an event
set_state	Set a shared state value
claim	Claim a resource
release	Release a claimed resource

Governance

Budget, monitoring, and approval controls.

governance:
  budget:
    max_cost: 10.00         # USD
    warn_at: 0.8            # warn at 80%
  heartbeat:
    interval_ms: 30000      # send every 30s
    dead_after_ms: 60000    # dead if no heartbeat for 60s
    auto_release_claims: true
  quorum:
    min_agents: 2           # minimum for decisions
  approval:
    required_for: [deploy, release]
    approvers: [lead]
  escalation:
    on_budget_warn: notify
    on_agent_death: redistribute

Variables

Parameterize protocols for reuse.

variables:
  max_reviewers:
    type: number
    default: 3
    description: "Maximum number of reviewers"
  target_branch:
    type: string
    default: main
    description: "Branch to review against"

roles:
  reviewer:
    count: "1-${max_reviewers}"

Variables are resolved at parse time. Override via CLI:

wgl protocol load spec.yaml --var max_reviewers=5 --var target_branch=develop

See Variables for full details.