AACP — Agent Action Compression Protocol
Deterministic coordination for multi-agent LLM systems.
Status:
v1.3· Benchmarks measured · MIT Licensed · IETF Internet-Draft filed
When agents coordinate in natural language, every instruction varies on every run, costs tokens, and produces no reliable audit trail. AACP replaces that with typed, validated, deterministic packets. Same input. Same output. Every time.
Links
| Spec and site | aacp.dev |
| IETF Draft | draft-mackay-aacp-01 |
| Python SDK | github.com/MackayAndrew/aacp — pip install aacp |
| TypeScript SDK | github.com/MackayAndrew/aacp-ts — npm install aacp-ts |
| LangChain | github.com/MackayAndrew/aacp-langchain |
| CrewAI | github.com/MackayAndrew/aacp-crewai |
| Community rules | github.com/MackayAndrew/aacp-community-rules — 241 rules |
| Registry API | registry.aacp.dev |
| VS Code extension | Dispatch AACP |
| Packet builder | dispatch.aacp.dev |
| Working lab | github.com/MackayAndrew/aacp-lab |
Install
# Python
pip install aacp
# TypeScript / JavaScript
npm install aacp-ts
The problem
Natural language (56 tokens) — varies on every run, not auditable:
"Please retrieve the employee salary records for the period ending
March 2026. I need all active employees, their departments, cost
centres, base salary, any changes made this month, and pension
contribution rates. Return as JSON array."
AACP v1.1 (52 tokens) — identical every run, validated, auditable:
FETCH|HR|return:HR-Agent|p:1|aacp:1.1|res:emp_salary|period:2026-03|filter:status=active|fmt:json
Measured results
Token counts from live API usage_metadata. 4-hop payroll workflow. May 2026.
| Hop | English | AACP | Claude | GPT-4o |
|---|---|---|---|---|
| fetch employees | 56 | 52 | -7.1% | -12.7% |
| fetch budgets | 57 | 47 | -17.5% | -16.0% |
| merge calculate | 65 | 43 | -33.8% | -31.6% |
| generate report | 62 | 43 | -30.6% | -33.3% |
| TOTAL | 240 | 185 | -22.9% | -23.7% |
Token reduction is a secondary benefit. The primary value is determinism and auditability -- every packet is identical across runs and machine-readable without post-processing.
Framework integration results
Validated on real workflows. June 2026.
| Framework | Coordination calls eliminated | Total cost saving | Deterministic |
|---|---|---|---|
| LangChain (59 hops) | 59 → 0 | 18% | YES |
| CrewAI (4 hops) | 4 → 0 | 30% | YES |
- aacp-langchain —
pip install aacp-langchain - aacp-crewai —
pip install aacp-crewai
Quick start (Python)
from aacp.encoders.workflows.payroll import PayrollEncoder
enc = PayrollEncoder()
pkt = enc.fetch_employees(period="2026-03")
print(pkt.packet)
# FETCH|HR|return:HR-Agent|p:1|aacp:1.1|res:emp_salary|period:2026-03|filter:status=active|fmt:json
print(f"Cost: ${pkt.api_cost_usd:.2f}") # $0.00
# Novel instructions — fallback to LLM, logged to registry
from aacp.encoders.fallback import FallbackEncoder
enc = FallbackEncoder()
pkt = enc.encode_english(
english="Cross-reference contractors against the approved vendor list.",
domain="FIN",
return_agent="FIN-Agent"
)
# First call: LLM once, ~$0.002
# Every subsequent identical call: $0.00 from registry cache
Quick start (TypeScript)
import { PayrollEncoder, AACPValidator, AACPDecoder } from "aacp-ts";
const enc = new PayrollEncoder();
const pkt = enc.fetchEmployees("2026-03");
console.log(pkt.packet);
console.log(pkt.apiCostUsd); // 0
Packet format
TASK|DOM|return:AGENT|p:PRIORITY|aacp:VERSION|key:value|key:value...
Valid TASK: FETCH PROC FLAG RESOLVE LOG SEND BUILD MERGE CALC REPORT ACK SYNC
Valid DOM: HR FIN SALES LEGAL IT CS MKT
Workflow encoders
8 encoders across 6 domains, each grounded in a documented real-world platform. Available in Python and TypeScript. Zero LLM cost.
| Encoder | Domain | Hops | Real-world basis |
|---|---|---|---|
PayrollEncoder |
HR | 6 | HMRC PAYE |
ITEncoder |
IT | 5 | Microsoft Entra ID |
InvoiceEncoder |
FIN | 3 | AP three-way match |
ContractEncoder |
LEGAL | 2-3 | NDA/MSA review |
SalesEncoder |
SALES | 5 | Salesforce Agentforce 2026 |
JMLEncoder |
HR+IT | 6 | ConductorOne, Lumos, CloudEagle |
CSResolutionEncoder |
CS | 5 | Zendesk Resolution Platform 2026 |
MonthEndEncoder |
FIN | 6 | NetSuite Autonomous Close 2026 |
See docs/encoder-reference.md for citations.
Three-tier fallback encoder
Tier 1 — Hash cache: exact match → $0.00
Tier 2 — Pattern match: registry or builtin → $0.00
Tier 3 — LLM fallback: novel → LLM once → logged → ~$0.002
next call → Tier 1 → $0.00
Amortisation benchmark: 6 LLM calls across 240 encoding operations. 91.6% saving.
Community rule library
241 pre-validated rules across 7 domains. MIT licensed. Zero API cost.
# Coming in v1.4:
from aacp import RuleRegistry
registry = RuleRegistry.from_community()
registry = RuleRegistry.from_hosted() # registry.aacp.dev
Browse: github.com/MackayAndrew/aacp-community-rules API: registry.aacp.dev
Multi-model lab results (Lab v3)
5 workflows, 4 models, all passing. June 2026.
| Model | Cost | Tokens in | Latency | Pass |
|---|---|---|---|---|
| gpt-4.1-mini | $0.0190 | 40,585 | 160s | ✓ 5/5 |
| gpt-4.1 | $0.0984 | 41,005 | 124s | ✓ 5/5 |
| claude-sonnet-4-5 | $0.2237 | 53,127 | 423s | ✓ 5/5 |
| gpt-4o | $0.2408 | 40,459 | 101s | ✓ 5/5 |
Lab: github.com/MackayAndrew/aacp-lab
Relationship to existing protocols
| Protocol | Layer | AACP relationship |
|---|---|---|
| MCP (Anthropic/AAIF) | Tool access | AACP inside MCP payloads |
| A2A (Google/AAIF) | Agent routing | AACP structures A2A message content |
| Existing APIs / JSON | Service comms | AACP for the LLM agent coordination layer on top |
AACP fills the coordination content layer -- the layer between routing (A2A, MCP) and task execution (the LLM doing actual work).
Roadmap
| Version | Status | Focus |
|---|---|---|
| v1.0 | Released | Pipe-delimited format, rule-based encoders |
| v1.1 | Released | Validated benchmarks — -22.9% Claude, -23.7% GPT-4o |
| v1.2 | Released | Fallback loop closed, PyPI + npm, IETF draft-01 |
| v1.3 | Released | 8 encoders, TypeScript SDK, VS Code extension, community rules (241), lab v3, amortisation benchmark, LangChain + CrewAI integrations |
| v1.4 | Planned | RuleRegistry (from_community, from_hosted), QBR encoder |
| v2.0 | Planned | IETF draft-02, AAIF submission |
Licence
MIT — free to use, implement, extend, and fork.
AACP is an independent protocol proposal. Not affiliated with Anthropic, Google, IBM, or the Linux Foundation, though designed to complement MCP, A2A, and ACP.
Metadata
Release files for aacp 1.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aacp-1.4.0.tar.gz | 33.9 kB | Without provenance | Details for aacp-1.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aacp-1.4.0-py3-none-any.whl | Python 3 | none | any | Details for aacp-1.4.0-py3-none-any.whl |
Total release size: 66.5 kB
Release files / aacp-1.4.0.tar.gz
| Download URL | aacp-1.4.0.tar.gz |
|---|---|
| Size | 33.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8a80474eb6f2d34d632cae4d69966fca70f81c8a041aa40895aa501bccf06b00
|
|
BLAKE2b-256 checksum How to use checksums |
af44d5d0bbe35f6d11ea0fcd53b82f23fbac2cbf4bc8ad1addbbc3ba94e24a72
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Release files / aacp-1.4.0-py3-none-any.whl
| Download URL | aacp-1.4.0-py3-none-any.whl |
|---|---|
| Size | 32.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
536a9b8dedfcf521527dbe0ae0efdf2249bfe0089a493c23c66d1569a85a8c6d
|
|
BLAKE2b-256 checksum How to use checksums |
594c6d167f1804febd36495438b5f35db6e24168b9aca5b54dfa837784be6ca4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Security for aacp 1.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.