Skip to main content

AACP — Agent Action Compression Protocol

PyPI version npm version

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.


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

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)

Source distribution for aacp 1.4.0
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)

Table of built distributions (wheels) for aacp 1.4.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page