ACP — Agent Communication Protocol

A zero-server, zero-code-change P2P protocol for direct Agent-to-Agent communication.
Two steps for humans. Everything else is automatic.

English · 简体中文

---

Overview

ACP is a lightweight, open protocol that enables any two AI agents — regardless of framework, vendor, or runtime — to establish a direct, serverless P2P communication channel.

Unlike enterprise-grade solutions (Google A2A, IBM ACP) that require server infrastructure and SDK integration, ACP is designed for speed and simplicity: a human acts only as a messenger, passing a Skill URL to Agent A and the resulting acp:// link to Agent B. The agents handle everything else automatically.

Human Step 1 ──► Send Skill URL to Agent A  ──► Agent A returns acp:// link
Human Step 2 ──► Send acp:// link to Agent B ──► Agents connect directly

No central relay. No code changes. No configuration.

---

Table of Contents

• Why ACP
• Quick Start
• Dependencies
• Features
• API Reference
• SDKs
• Compatibility Test Suite
• Roadmap
• Protocol Comparison
• Repository Structure
• Contributing
• License

---

Why ACP

Existing multi-agent communication solutions impose significant operational overhead:

Challenge	Traditional Approach	ACP
Infrastructure	Requires a relay server or message broker	No server required — pure P2P
Integration	Modify agent code, import SDK	Zero code changes — Skill-driven
Setup	Register, configure, deploy	One link — instant connection
Portability	Framework-locked	Framework-agnostic — any agent, any language
Dependencies	Heavy SDK with transitive deps	One required dep (websockets)

Design philosophy: The acp:// link is the connection. No registry, no discovery service, no broker — just a URI that contains the full address of the other agent.

---

Quick Start

Step 1 — Install

pip install websockets

Step 2 — Download

curl -sO https://raw.githubusercontent.com/Kickflip73/agent-communication-protocol/main/relay/acp_relay.py

Step 3 — Connect two agents

Agent A (host):

python3 acp_relay.py --name "AgentA"
# Output: Your link: acp://1.2.3.4:7801/tok_xxxxx
# Send this link to Agent B

Agent B (guest):

python3 acp_relay.py --name "AgentB" --join "acp://1.2.3.4:7801/tok_xxxxx"
# Both sides: connected ✅

Step 4 — Send & receive

# Send a message
curl -X POST http://localhost:7901/message:send \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from AgentA"}'

# Stream incoming messages (SSE)
curl http://localhost:7901/stream

# Check AgentCard
curl http://localhost:7901/.well-known/acp.json

Restricted network? Use relay fallback

python3 acp_relay.py --name "AgentA" --relay
# Output: acp+wss://black-silence-11c4.yuranliu888.workers.dev/acp/tok_xxxxx

acp:// = P2P (default). acp+wss:// = relay fallback for firewalled/K8s environments.

---

Dependencies

ACP is designed to have minimal mandatory dependencies and truly optional extras. Unlike frameworks where importing any module silently pulls in unrelated dependencies, ACP's optional features are isolated and gracefully degraded without installation.

Package	Required?	Purpose	Install
websockets	✅ Required	P2P WebSocket transport	pip install websockets
cryptography	⚙️ Optional	Ed25519 identity signing (v0.8)	pip install cryptography

Zero implicit deps. If cryptography is not installed, --identity logs a warning and disables identity — the rest of ACP runs normally. There are no other hidden dependencies.

Node.js SDK (zero dependencies — uses built-in fetch + EventSource):

# No npm install needed — relay_client.js has no external deps

---

Features

Core (v0.1–v0.5)

• P2P WebSocket transport with NAT traversal
• AgentCard capability exchange (.well-known/acp.json)
• Task lifecycle: submitted → working → completed / failed / input_required
• SSE streaming endpoint (/stream)
• Synchronous request/reply (sync=true)
• Relay fallback for restricted networks (Cloudflare Worker)
• Message parts: text / file / data
• Server sequence numbers (server_seq) for ordering

v0.6 — Peer Registry & Error Codes

• Multi-session peer registry (/peers, /peer/{id}/send)
• Standardized error codes (ERR_NOT_CONNECTED, ERR_MSG_TOO_LARGE, ERR_NOT_FOUND, ERR_INVALID_REQUEST, ERR_TIMEOUT, ERR_INTERNAL)
• QuerySkill API (/skills/query)

v0.7 — Trust & Discovery

• HMAC-SHA256 message signing (--secret <key>) — closed-deployment integrity
• mDNS LAN peer discovery (--advertise-mdns) — LAN autodiscovery, no zeroconf library
• Context ID — multi-turn conversation grouping across messages

v0.8 — Ecosystem & Identity

• Ed25519 optional identity (--identity) — self-sovereign keypair, zero PKI
  • Auto-generates keypair to ~/.acp/identity.json (chmod 600) on first run
  • Every outbound message signed with Ed25519; inbound sigs verified (warn-only)
  • HMAC and Ed25519 can be active simultaneously
• Node.js SDK (sdk/node/) — zero external dependencies, TypeScript types, 19 tests
• Compatibility test suite (tests/compat/) — black-box spec compliance runner, parameterized by ACP_BASE_URL

---

API Reference

Endpoint	Method	Description
/.well-known/acp.json	GET	AgentCard (capabilities, identity, endpoints)
/message:send	POST	Send message to peer (supports sync, parts, task_id, context_id)
/stream	GET	SSE stream of incoming messages and events
/tasks	GET	List all tasks
/tasks/create	POST	Create a new task
/tasks/{id}	GET	Get task details
/tasks/{id}/update	POST	Update task status
/tasks/{id}/continue	POST	Send follow-up for input_required tasks
/tasks/{id}:cancel	POST	Cancel a task
/peers	GET	List connected peers
/peer/{id}	GET	Get peer info
/peer/{id}/send	POST	Send message to specific peer
/peers/connect	POST	Connect to a new peer via acp:// link
/skills/query	POST	Query this agent's available skills
/discover	GET	Discover LAN peers via mDNS (requires --advertise-mdns)
/status	GET	Agent status (connections, message counts, uptime)

POST /message:send

{
  "text": "Hello",           // shorthand for parts=[{type:text, content:...}]
  "parts": [...],            // or use explicit Part objects
  "sync": true,              // block until peer replies (default: false)
  "timeout": 30,             // seconds (default: 30, only with sync:true)
  "task_id": "task_abc",     // associate message with a task
  "context_id": "ctx_xyz",   // group messages into a multi-turn context
  "create_task": true,       // auto-create a task for this message
  "message_id": "msg_custom" // optional — auto-generated if omitted
}

Error Response Format

All errors return a consistent envelope:

{
  "ok": false,
  "error_code": "ERR_NOT_CONNECTED",
  "error": "No P2P connection",
  "failed_message_id": "msg_abc123"  // optional, for ERR_TIMEOUT / ERR_MSG_TOO_LARGE
}

See spec/error-codes.md for full reference.

---

SDKs

Python SDK (sdk/python/)

from sdk.python.acp_sdk.relay_client import RelayClient, ACPError

client = RelayClient("http://localhost:7901")
client.send("Hello from Python!")
msg = client.recv(timeout=10)
print(msg["parts"][0]["content"])

Node.js SDK (sdk/node/)

Zero external dependencies (built-in fetch + EventSource):

import { RelayClient } from './sdk/node/src/relay_client.js';

const client = new RelayClient('http://localhost:7901');
await client.send('Hello from Node!');
const msg = await client.recv({ timeout: 10000 });
console.log(msg.parts[0].content);

TypeScript types included (src/index.d.ts).

---

Compatibility Test Suite

Any ACP implementation can be validated against the spec:

# Run against the reference implementation
ACP_BASE_URL=http://localhost:7901 python3 tests/compat/run.py

# Run against any other implementation
ACP_BASE_URL=http://other-agent:8080 python3 tests/compat/run.py

Tests cover: AgentCard schema, /message:send, SSE streaming, task lifecycle, peer registry, error codes, HMAC signing. See tests/compat/README.md.

---

Optional Features

HMAC Message Signing (v0.7)

For closed deployments where both peers share a secret:

# Both agents must use the same --secret
python3 acp_relay.py --name "AgentA" --secret "my-shared-key"
python3 acp_relay.py --name "AgentB" --join "acp://..." --secret "my-shared-key"

Requires: no additional packages (uses stdlib hmac).

Ed25519 Identity (v0.8)

For open federation where peers need cryptographic attribution:

# First run: auto-generates ~/.acp/identity.json
python3 acp_relay.py --name "AgentA" --identity

# Subsequent runs: loads existing keypair
python3 acp_relay.py --name "AgentA" --identity

# Custom keypair path
python3 acp_relay.py --name "AgentA" --identity /path/to/id.json

Requires: pip install cryptography

See spec/identity-v0.8.md for full spec.

mDNS LAN Discovery (v0.7)

python3 acp_relay.py --name "AgentA" --advertise-mdns
# Peers on the same LAN appear at GET /discover

Requires: no additional packages (raw UDP multicast).

---

Roadmap

Version	Status	Highlights
v0.1	✅ Done	P2P WebSocket, AgentCard, basic send/recv
v0.2	✅ Done	Auto-reconnect, JSONL persistence, SSE streaming
v0.3	✅ Done	Task lifecycle, multi-session, relay fallback
v0.4	✅ Done	Multimodal parts (text/file/data), Cloudflare Worker relay
v0.5	✅ Done	QuerySkill API, server_seq ordering, message idempotency
v0.6	✅ Done	Peer registry, standardized error codes, minimal agent spec
v0.7	✅ Done	HMAC signing, mDNS LAN discovery, context_id
v0.8	✅ Done	Ed25519 identity, Node.js SDK, compat test suite
v0.9	🚧 Planning	spec/core-v0.8.md consolidated spec, Python async SDK, CLI improvements
v1.0	📋 Planned	Production release, DID identity option, stability guarantees

See acp-research/ROADMAP.md for detailed planning.

---

Protocol Comparison

Dimension	MCP (Anthropic)	A2A (Google)	IBM ACP	ACP (this project)
Scope	Agent ↔ Tool	Agent ↔ Agent (enterprise)	Agent ↔ Agent (REST)	Agent ↔ Agent (P2P)
Transport	stdio / HTTP+SSE	HTTP+SSE / JSON-RPC	REST HTTP	WebSocket (direct P2P)
Server required	—	✅ Yes	✅ Yes	❌ No
Code changes required	✅ Yes	✅ Yes	✅ Yes	❌ No
Required dependencies	Many	Many (incl. SQLAlchemy)	Many	websockets only
Task lifecycle	—	✅ Yes	✅ Yes	✅ Yes
Streaming	✅ SSE	✅ SSE	—	✅ SSE
Identity / signing	—	OAuth 2.0 (mandatory)	—	HMAC or Ed25519 (optional)
LAN discovery	—	—	—	✅ mDNS (optional)
Node.js SDK	✅	✅	—	✅ (zero deps)
Compat test suite	—	✅	—	✅
Target audience	Enterprise / teams	Enterprise	Enterprise	Personal / small teams

ACP's position: MCP standardizes Agent↔Tool. ACP standardizes Agent↔Agent. P2P, lightweight, open, zero infra.

---

Repository Structure

agent-communication-protocol/
├── relay/
│   ├── acp_relay.py          # Core daemon — single file, one required dep (websockets)
│   └── SKILL.md              # Agent instruction manifest — send this URL to any agent
├── spec/
│   ├── core-v0.1.md          # Core protocol spec (v0.1, English)
│   ├── core-v0.1.zh.md       # Core protocol spec (v0.1, Chinese)
│   ├── core-v0.5.md          # Core protocol spec (v0.5)
│   ├── error-codes.md        # Standard error codes (v0.6)
│   ├── transports.md         # Transport bindings + HMAC (v0.7)
│   ├── transports.zh.md      # Transport bindings (Chinese)
│   ├── identity-v0.8.md      # Ed25519 identity extension (v0.8)
│   ├── v0.6-minimal-agent.md # Minimal agent implementation guide
│   └── v0.8-planning.md      # v0.8 planning document
├── sdk/
│   ├── python/               # Python RelayClient SDK
│   └── node/                 # Node.js RelayClient SDK (zero deps, TS types)
├── tests/
│   └── compat/               # Black-box ACP spec compliance test suite
├── acp-research/
│   ├── ROADMAP.md            # Detailed version roadmap
│   └── reports/              # Competitive intelligence reports (A2A, ANP)
├── docs/
│   └── README.zh-CN.md       # Chinese documentation
├── CONTRIBUTING.md
└── LICENSE                   # Apache 2.0

---

Contributing

Contributions welcome! Please read CONTRIBUTING.md before submitting a PR.

• Bug reports & feature requests → GitHub Issues
• Protocol design discussions → GitHub Discussions
• Security vulnerabilities → Please do not file a public issue; contact maintainers directly.

---

License

ACP is released under the Apache License 2.0.

---

_{Built with ❤️ for the agent ecosystem — MCP standardizes Agent↔Tool, ACP standardizes Agent↔Agent.}