ACP Overview

The Agent Coordination Protocol (ACP) is an open standard for multi-agent coordination. It replaces imperative orchestrator code with declarative YAML specs that define roles, phases, rules, and governance.

Why ACP

Every multi-agent framework today uses a central orchestrator that polls agents for status, routes messages, and manages state. Agents spend 15-25% of their token budget on coordination overhead.

ACP moves coordination out of the LLM context and into external infrastructure. Agents get told when something happens instead of asking.

	Traditional Orchestrator	ACP
Event checking	LLM poll (tokens)	WebSocket push (free)
Message delivery	LLM poll (tokens)	Push notification (free)
State management	In LLM context (lossy)	External server (full fidelity)
Coordination cost	15-25% of tokens	~0%

Core concepts

A protocol defines:

• Roles: Agent types with descriptions, counts, model hints, and scoped capabilities
• Phases: Workflow stages with exit conditions and allowed transitions
• Resources: Named items that agents can claim (mutex locks)
• Rules: Per-role per-phase step sequences
• Governance: Budget caps, heartbeat monitoring, quorum requirements, approval gates
• Variables: ${var} parameterization for reusable protocols

Example protocol

acp: "1.0"
name: code-review
title: Collaborative Code Review

roles:
  reviewer:
    description: Review code changes for correctness and style
    count: "2+"
    model_hint: sonnet
  author:
    description: Address review feedback
    model_hint: haiku

phases:
  review:
    description: Reviewers examine changes
    exit_condition:
      state_key: phase
      equals: revision
  revision:
    description: Author addresses feedback
    exit_condition:
      state_key: phase
      equals: done

governance:
  budget:
    max_cost: 5.00
    warn_at: 0.8
  heartbeat:
    dead_after_ms: 60000
    auto_release_claims: true

How it fits in the Honeybee stack

ACP is the foundation. Everything else builds on it:

• Incubator implements the ACP server (state, events, claims, phases)
• Colony runs ACP protocols in the cloud
• CLI (wgl) provides commands for every ACP primitive
• Waggle plugin gives Claude Code agents ACP tools
• Dashboard visualizes ACP state in real-time

ACP is provider-agnostic. The same protocol coordinates Claude, GPT, Gemini, Llama, and local models. No vendor lock-in.

Packages

Package	What	Install
@agentcoordinationprotocol/spec	Parser, renderer, types, variables	npm i @agentcoordinationprotocol/spec
@agentcoordinationprotocol/sdk	HTTP client for any ACP server	npm i @agentcoordinationprotocol/sdk
@agentcoordinationprotocol/editor	Visual protocol designer (ReactFlow)	npm i @agentcoordinationprotocol/editor

Learn more

• Spec Format — Full YAML reference
• Primitives — 8 categories, 29 operations
• Governance — Budget, heartbeat, quorum, approval
• Variables — ${var} parameterization
• Examples — 38 protocol showcase
• ACP standalone docs — Full spec documentation