Reference Implementation

The Agent Control Protocol ships a production-grade Go reference implementation covering all four conformance levels. It is the canonical artifact for understanding how the constitutional invariant is enforced in real software — with real cryptography, real hash chains, and a verifiable compliance test suite.

Execute(request) ⇒ ValidIdentity ∧ ValidCapability ∧ ValidDelegationChain ∧ AcceptableRisk

What the Implementation Covers

23 Go Packages

One package per ACP spec, from pkg/agent (identity) through pkg/ledger (hash-chained audit log) to pkg/pay (payment governance). Each package is independently importable.

5 Conformance Levels

L1 Core → L2 Security → L3 Full → L4 Extended. Each level builds on the previous, allowing partial adoption starting from the identity and capability layer.

138 + 5 Compliance Test Vectors

138 signed single-shot vectors (CORE, DCMA, HP, LEDGER, EXEC, PROV, PCTX, REP, RISK-2.0) plus 5 stateful sequence scenarios (ACR-1.0): cooldown activation, F_anom Rule 3 pattern detection, threshold boundaries, and privilege jumps.

ACR-1.0 Sequence Runner

A Go compliance runner that validates ACP-RISK-3.0 stateful behavior. Library mode (direct) or HTTP mode (external server). Run go run . --mode library --dir ../test-vectors/sequence --strict to verify any implementation end-to-end.

Cryptographic Primitives

Ed25519 signatures over JCS-normalized JSON (RFC 8785). Hash chains use SHA-256 with base64 (RFC 4648). Signing uses base64url without padding (RFC 4648 §5).

Package Structure

ACP-PROTOCOL-EN/impl/go/
├── pkg/
│   ├── crypto/     # ACP-SIGN-1.0 + ACP-AGENT-1.0 — Signing + identity (L1)
│   ├── tokens/     # ACP-CT-1.0      — Capability tokens (L1)
│   ├── registry/   # ACP-CAP-REG-1.0 — Capability registry (L1)
│   ├── handshake/  # ACP-HP-1.0      — Handshake protocol (L1)
│   ├── delegation/ # ACP-DCMA-1.1    — Delegation chains (L1)
│   ├── provenance/ # ACP-PROVENANCE-1.0 — Authority provenance (L1)
│   ├── risk/       # ACP-RISK-3.0    — Risk scoring + F_anom + Cooldown (L2)
│   ├── revocation/ # ACP-REV-1.0     — Revocation protocol (L2)
│   ├── reputation/ # ACP-REP-1.2     — Reputation module (L2)
│   ├── execution/  # ACP-EXEC-1.0    — Execution tokens (L3)
│   ├── ledger/     # ACP-LEDGER-1.3  — Audit ledger (L3)
│   ├── psn/        # ACP-PSN-1.0     — Policy snapshots (L3)
│   ├── policyctx/  # ACP-POLICY-CTX-1.1 — Policy context (L3)
│   ├── lia/        # ACP-LIA-1.0     — Liability attribution (L3)
│   ├── hist/       # ACP-HIST-1.0    — History queries (L4)
│   ├── govevents/  # ACP-GOV-EVENTS-1.0 — Governance events (L4)
│   ├── notify/     # ACP-NOTIFY-1.0  — Notifications (L4)
│   ├── disc/       # ACP-DISC-1.0    — Service discovery (L4)
│   ├── bulk/       # ACP-BULK-1.0    — Bulk operations (L4)
│   ├── crossorg/   # ACP-CROSS-ORG-1.1 — Cross-org fault-tolerant protocol (L4)
│   ├── pay/        # ACP-PAY-1.0     — Payment governance (L4)
│   └── sign2/      # ACP-SIGN-2.0    — Hybrid Ed25519 + ML-DSA-65 (cloudflare/circl, v1.21)
├── cmd/
│   ├── gen-ledger-vectors/   # Compliance vector generator (LEDGER)
│   └── gen-exec-vectors/     # Compliance vector generator (EXEC)
├── tla/
│   ├── ACP.tla               # Base formal model — Safety · RiskDeterminism (v1.17)
│   ├── ACP.cfg               # TLC configuration for ACP.tla
│   ├── ACP_Extended.tla      # Extended model — cooldown temporal state · delegation integrity (v1.20)
│   └── ACP_Extended.cfg      # TLC config — 5,684,342 states · 9 invariants · 0 violations
└── compliance/
    ├── adversarial/          # Adversarial evaluation — Exp 1–8 (cooldown evasion, multi-agent, backend stress, latency injection, token replay, stateless vs stateful, state-mixing vuln, RISK-3.0 fix)
    ├── runner/               # ACR-1.0 sequence compliance runner
    └── test-vectors/         # 73 signed + 65 unsigned RISK-2.0 + 5 sequence vectors

Admission Flow: How ACP Intercepts Agent Actions

Every agent action passes through a 6-step admission check before execution. The docs/admission-flow.md guide walks through each step with spec references, error codes, and Go/Python examples.

The 6-Step Admission Check

Identity validation → Capability verification → Delegation chain → Policy snapshot → Risk scoring → Execution token issuance. Any step can result in APPROVED, DENIED, or ESCALATED.

ACPAdmissionGuard Pattern

A drop-in wrapper for any agent action. Wraps capability token construction, admission request, and decision handling. Works offline (local signature verification) or online (full server flow).

LangChain Integration — `@acp_tool`

Drop-in replacement for LangChain's @tool. Every tool invocation is intercepted by ACP before execution — the LLM agent cannot bypass the check. Returns APPROVED, raises ACPDeniedError, or ACPEscalatedError.

@acp_tool(guard=guard,
          capability="acp:cap:financial.payment",
          resource="bank://accounts/*")
def transfer_funds(amount: float, ...) -> str:
    # only runs if ACP → APPROVED
    return bank.transfer(amount, ...)

Pydantic AI Integration — `RunContext` deps

The guard is injected as a RunContext dependency — every @agent.tool receives it via ctx.deps. DENIED actions raise ModelRetry, which Pydantic AI surfaces to the agent without exposing internal state.

@agent.tool
async def transfer_funds(
    ctx: RunContext[ACPAdmissionGuard],
    amount: float, to_account: str,
) -> str:
    result = ctx.deps.check(capability, resource)
    if result.denied:
        raise ModelRetry(f"DENIED: {result.error_code}")
    return bank.transfer(amount, to_account)

MCP Server Integration — `ACPToolDispatcher`

ACP admission control at the MCP dispatch layer. Every tools/call request passes ACP before the handler runs. Compatible with Claude Desktop and any MCP client. Returns isError: true for DENIED/ESCALATED actions — no state mutation.

@dispatcher.tool(
    capability="acp:cap:financial.payment",
    resource="bank://accounts/*",
    risk_params=["amount"],
)
def transfer_funds(amount: float, ...) -> str:
    # only runs if ACP → APPROVED
    return bank.transfer(amount, ...)

Admission Flow Guide → LangChain Demo → Pydantic AI Demo → MCP Demo → Core Demo → Multi-Org Demo →

Performance

ACP is compute-cheap but state-sensitive. Decision evaluation incurs minimal overhead; system throughput is bounded by the state backend, not the protocol logic. This is by design: the LedgerQuerier abstraction cleanly separates the two.

~820 ns

APPROVED path
baseline concurrency

~88 ns

cooldown path
9.5× faster — Step 2 early exit

~920k

req/s · 10 workers
degrades to ~712k at 500

6.7×

state contention spread
1-agent vs 100-agent workload

Benchmark results — Intel Core i7-8665U · Go 1.22 · Windows/amd64

Path	ns/op	allocs/op
APPROVED (baseline)	767	5
DENIED	784	5
F_anom all rules active (worst case)	921	5
Cooldown active (Step 2 short-circuit)	102	2

Run benchmarks: go test ./pkg/risk/... -bench=. -benchmem -benchtime=3s

Run the Reference Server

Start the ACP server in one command — no Go installation needed.

docker run -p 8080:8080 \
  -e ACP_INSTITUTION_PUBLIC_KEY=cA4s58S2dEJ-qye6EpJaJKKaVfvPT8mAQf97Vo8TInk \
  ghcr.io/chelof100/acp-server:latest

Or explore the full implementation source — start with pkg/ for packages or compliance/test-vectors/ for the signed test suite.

Browse ACP Reference Implementation