MCP standardized Agent↔Tool. ACP standardizes Agent↔Agent.
P2P · Zero server required · curl-compatible · works with any LLM framework

Alpha ↔ Beta bidirectional P2P communication — no central server, no OAuth

$ # Agent A — get your link
$ python3 acp_relay.py --name AgentA
✅ Ready.  Your link: acp://1.2.3.4:7801/tok_xxxxx
           Send this link to any other Agent to connect.

$ # Agent B — connect with one API call
$ curl -X POST http://localhost:7901/peers/connect \
       -d '{"link":"acp://1.2.3.4:7801/tok_xxxxx"}'
{"ok":true,"peer_id":"peer_001"}

$ # Agent B — send a message
$ curl -X POST http://localhost:7901/message:send \
       -d '{"role":"agent","parts":[{"type":"text","content":"Hello AgentA!"}]}'
{"ok":true,"message_id":"msg_abc123","peer_id":"peer_001"}

$ # Agent A — receive in real-time (SSE stream)
$ curl http://localhost:7901/stream
event: acp.message
data: {"from":"AgentB","parts":[{"type":"text","content":"Hello AgentA!"}]}

Quick Start

Option A — AI Agent native (2 steps, zero config)

# Step 1: Send this URL to Agent A (any LLM-based agent)
https://raw.githubusercontent.com/Kickflip73/agent-communication-protocol/main/SKILL.md

# Agent A auto-installs, starts, and replies:
# ✅ Ready. Your link: acp://1.2.3.4:7801/tok_xxxxx

# Step 2: Send that acp:// link to Agent B
# Both agents are now directly connected. Done.

Option B — Manual / script

# Install
pip install websockets

# Start Agent A
python3 relay/acp_relay.py --name AgentA
# → ✅ Ready. Your link: acp://YOUR_IP:7801/tok_xxxxx

# In another terminal — Agent B connects
python3 relay/acp_relay.py --name AgentB \
  --join acp://YOUR_IP:7801/tok_xxxxx
# → ✅ Connected to AgentA

Option C — Docker

docker run -p 7801:7801 -p 7901:7901 \
  ghcr.io/kickflip73/agent-communication-protocol/acp-relay \
  --name MyAgent

Behind NAT / Firewall / Sandbox?

ACP v1.4 includes a three-level automatic connection strategy — zero config required:

Level 1 — Direct connect       (public IP or same LAN)
   ↓ fails within 3s
Level 2 — UDP hole punch       (both behind NAT — NEW in v1.4)
           DCUtR-style: STUN address discovery → relay signaling → simultaneous probes
           Works with ~70% of real-world NAT types (full-cone, port-restricted)
   ↓ fails
Level 3 — Relay fallback       (symmetric NAT / CGNAT — ~30% of cases)
           Cloudflare Worker relay, stateless, no message storage

SSE events reflect the current connection level in real-time: dcutr_started → dcutr_connected / relay_fallback.
GET /status returns connection_type: p2p_direct | dcutr_direct | relay.

To force relay mode (e.g., for backward compatibility), add --relay on startup to get an acp+wss:// link.

→ See NAT Traversal Guide

Routing Topology Declaration (`transport_modes`, v2.4)

Agents declare which routing topologies they support via the transport_modes top-level AgentCard field:

Default: ["p2p", "relay"] — both topologies supported; absent means the same.

# Sandbox / NAT-only agent (relay only)
python3 relay/acp_relay.py --name SandboxAgent --transport-modes relay

# Edge agent with public IP (P2P only, no relay dependency)
python3 relay/acp_relay.py --name EdgeAgent --transport-modes p2p

AgentCard snippet:

{
  "transport_modes": ["p2p", "relay"],
  "capabilities": {
    "supported_transports": ["http", "ws"]
  }
}

Distinction: transport_modes declares routing topology (which path data takes). capabilities.supported_transports declares protocol bindings (how bytes are framed). They are orthogonal — see spec §5.4.

Architecture

Handshake (humans only do steps 1 and 2)

  Human
    │
    ├─[① Skill URL]──────────────► Agent A
    │                                  │  pip install websockets
    │                                  │  python3 acp_relay.py --name A
    │                                  │  → listens on :7801/:7901
    │◄────────────[② acp://IP:7801/tok_xxx]─┘
    │
    ├─[③ acp://IP:7801/tok_xxx]──► Agent B
    │                                  │  POST /connect {"link":"acp://..."}
    │                                  │
    │          ┌────────── WebSocket Handshake ──────────┐
    │          │  B → A : connect(tok_xxx)               │
    │          │  A → B : AgentCard exchange             │
    │          │  A, B  : connected ✅                   │
    │          └──────────────────────────────────────────┘
    │
   done                ↕ P2P messages flow directly

P2P Direct Mode (default)

  Machine A                                          Machine B
┌─────────────────────────────┐    ┌─────────────────────────────┐
│  ┌─────────────────────┐    │    │    ┌─────────────────────┐  │
│  │    Host App A       │    │    │    │    Host App B       │  │
│  │  (LLM / Script)     │    │    │    │  (LLM / Script)     │  │
│  └──────────┬──────────┘    │    │    └──────────┬──────────┘  │
│             │ HTTP          │    │               │ HTTP         │
│  ┌──────────▼──────────┐    │    │    ┌──────────▼──────────┐  │
│  │   acp_relay.py      │    │    │    │   acp_relay.py      │  │
│  │  :7901  HTTP API    │◄───┼────┼────┤  POST /message:send │  │
│  │  :7901/stream (SSE) │────┼────┼───►│  GET /stream (SSE)  │  │
│  │  :7801  WebSocket   │◄═══╪════╪═══►│  :7801  WebSocket   │  │
│  └─────────────────────┘    │    │    └─────────────────────┘  │
└─────────────────────────────┘    └─────────────────────────────┘
                         Internet / LAN (no relay server)

Host app integration (3 lines):

# Send a message to the remote agent
requests.post("http://localhost:7901/message:send",
              json={"role":"agent","parts":[{"type":"text","content":"Hello"}]})

# Listen for incoming messages in real-time (SSE long-poll)
for event in sseclient.SSEClient("http://localhost:7901/stream"):
    print(event.data)   # {"type":"message","from":"AgentB",...}

Full Connection Strategy (v1.4 — automatic, zero user config)

┌────────────────────────────────────────────────────────────────┐
│             Three-Level Connection Strategy                    │
│                                                                │
│  Level 1 — Direct Connect (best)                               │
│  ┌──────────┐                          ┌──────────┐            │
│  │  Agent A │◄═══════ WS direct ══════►│  Agent B │            │
│  └──────────┘    (public IP / LAN)     └──────────┘            │
│                                                                │
│  Level 2 — UDP Hole Punch (v1.4, both behind NAT)              │
│  ┌──────────┐   ┌─────────────┐        ┌──────────┐            │
│  │  Agent A │──►│  Signaling  │◄───────│  Agent B │            │
│  │  (NAT)   │   │ (addr exch) │        │  (NAT)   │            │
│  └──────────┘   └─────────────┘        └──────────┘            │
│       │          exits after                 │                  │
│       └──────────── WS direct ──────────────┘                  │
│                    (true P2P after punch)                       │
│                                                                │
│  Level 3 — Relay Fallback (~30% symmetric NAT cases)           │
│  ┌──────────┐   ┌─────────────┐        ┌──────────┐            │
│  │  Agent A │◄─►│    Relay    │◄──────►│  Agent B │            │
│  └──────────┘   │ (stateless) │        └──────────┘            │
│                 └─────────────┘                                │
│                  frames only, no message storage               │
└────────────────────────────────────────────────────────────────┘

Signaling server does one-time address exchange only (TTL 30s), forwards zero message frames.
Relay is the last resort, not the main path — only triggered by symmetric NAT / CGNAT.

Why ACP

Governance metadata (v2.85/v2.87) — A2A #1717 (2026-04-09, Microsoft governance team) proposes adding trust_score, capability_manifest, and policy_compliance to Agent Cards. ACP already ships all three: governance_metadata.governance_score, governance_metadata.policies[], and PATCH /policy-compliance (v2.87). No proposal, no committee — working code with tests.

Skill authorization tiers (v2.50+) — A2A #1716 (2026-04-09, RFC stage) identifies the same gap ACP solved in v2.50: SecurityRequirement authenticates callers but cannot restrict which skills they invoke or with what parameters. ACP's authorization_tier (T0–T3) + capability_token + human_confirmation_required + 5-factor effective_tier provides complete skill-boundary authorization — with 60+ passing tests.

Bilateral signed interaction records (v2.59+) — A2A #1718 (2026-04-05, viftode4) correctly identifies that unilateral relay-signed records can be forged: if the relay lies, the record is worthless. ACP v2.61 solved this with bilateral co-signing: caller and relay both sign the same canonical payload. A record signed by both parties is non-repudiable by either. Chain of records (SHA-256 previous_hash) is tamper-evident without trusting either party. Bilateral records feed into effective_tier as the bilateral_ir_adj factor (v2.76) — a corpus of mutual interaction history can lower the authorization floor for a trusted, well-known peer. GET /ir/test-vectors (v2.64) enables cross-implementation verification. 29+ passing tests.

A2A #1672 has 425 comments (as of 2026-04-12) and still no implementation merged into spec. The leading proposal requires a central CA (getagentid.dev) — single point of failure, registration bottleneck, privacy leak. ACP v2.85 ships Ed25519 identity default-on: self-generated keypair, no CA, no registration, works offline and air-gapped. ACP v2.93 publishes ACP-RFC-004 — a full comparison (9 dimensions) and multi-provider DID approach, responding directly to the aeoess three-layer model articulated in A2A #1712.

A2A #1680 & #1684 — community debate: when cancel can't complete immediately, return WORKING or new CANCELING state? CancelTaskRequest schema is missing from spec. ACP v1.5.2 resolves all of this with synchronous, idempotent cancel semantics.

A2A #1685 — error response Content-Type undefined in spec (PR #1600 removed application/problem+json without replacing it). A2A #1681 — push notification config API exposes credentials in plaintext. ACP avoids both by design: uniform application/json + URL-only webhooks.

Offline delivery (v2.0-alpha / v2.97 / v2.98 / v3.8) — A2A has no spec-level offline buffering. If you send a message while your peer is restarting, it's gone. ACP automatically queues the message on your local relay (up to 100 per peer), and flushes the queue the moment the peer reconnects. GET /offline-queue shows what's waiting. v2.97 --persist-queue adds SQLite-backed durability: messages survive relay restarts, solving the heartbeat-agent offline window (A2A #1667). v2.98 POST /tasks/queue completes the offline-first story for task workloads: enqueue a task with 202 Accepted, pick up results later via poll or SSE — no blocking, no dropped work. v3.8 --heartbeat-agent + GET /offline-queue/summary closes the loop: cron-style agents wake up, call the lightweight summary endpoint (has_messages, total_queued, oldest_queued_at) for a fast pre-check before heavier processing, then stamp POST /availability/heartbeat when done.

AgentCard limitations (v2.7 → v2.28) — A2A #1694 (opened 2026-03-27) proposes adding a limitations field. ACP v2.7 shipped working code the same day; ACP v2.20 upgrades to structured LimitationObject[] with stable/runtime split (permanent: bool), 6 kind types (capability|modality|scale|domain|access|other), machine-readable codes. ACP v2.28 extends this to per-skill granularity: every skill object now carries its own limitations[], enabling orchestrators to ask "does skill X support audio?" rather than just "does this agent support audio?". GET /skills?has_limitation=modality returns only skills with modality-kind limitations; POST /skills/query response includes skill_limitations_declared[] for pre-flight routing decisions. Old clients ignore the optional field — fully backward-compatible. A2A #1694 is still an open proposal with no merged implementation.

LAN discovery (v2.1-alpha) — A2A has no spec-level mechanism for agents to find each other on a local network. ACP GET /peers/discover scans your /24 subnet in 1–3 seconds: 64-thread TCP probe on common ACP ports, then /.well-known/acp.json fingerprint on every open port. Returns a list of ACP agents with their acp:// links — ready to connect. No mDNS required on the target side. Find any ACP relay on your LAN, even ones you don't control.

Multi-relay federation (v3.10) — A2A has no cross-relay message routing mechanism. When agents are on different relay instances (different orgs, different networks), there's no standard way to deliver messages between them. ACP v3.10 adds POST /federation to connect remote relays as peers, and POST /federation/route to route messages to peers on remote relays — all in ~120 lines of stdlib Python. Federated messages fall back to offline-queue when the target peer is offline, composable with --persist-queue for durable cross-relay delivery. capabilities.federation: true lets orchestrators discover federation-capable relays via AgentCard.

Numbers

• 0.6ms avg send latency · 2.8ms P99
• 1,100+ req/s sequential throughput · 1,200+ req/s concurrent (10 threads)
• < 50ms SSE push latency (threading.Event, not polling)
• 1574/1574 unit + integration tests PASS (error handling · pressure test · NAT traversal · ring pipeline · transport_modes · context query · federation · Pub/Sub · heartbeat-agent · task-queue-worker · governance-compliance · governance-audit)
• 190+ commits · 3,300+ lines · zero known P0/P1 bugs

API Reference

HTTP default port: 7901 · WebSocket port: 7801

AgentCard response example (GET /.well-known/acp.json):

{
  "name": "MyAgent",
  "acp_version": "2.4.0",
  "transport_modes": ["p2p", "relay"],
  "capabilities": {
    "streaming": true,
    "supported_transports": ["http", "ws"]
  }
}

transport_modes (v2.4+): declares routing topology — "p2p" (direct) and/or "relay" (relay-mediated). Default: ["p2p", "relay"]. Distinct from capabilities.supported_transports which declares protocol bindings.

Optional Features

Task State Machine

Track cross-agent task progress:

submitted → working → completed ✅
                    → failed    ❌
                    → input_required → working (waiting for more input)

API: POST /tasks to create · POST /tasks/{id}:update to update status.

Heartbeat / Cron Agents

ACP natively supports offline agents (cron-style agents that wake up periodically), no persistent connection required.

How it works

Cron Agent wakes up every 5 minutes:
1. Start acp_relay.py (get an acp:// link)
2. PATCH /.well-known/acp.json to broadcast availability
3. GET /recv to drain queued messages, process in batch
4. POST /message:send to reply
5. Exit (relay shuts down cleanly)

# Python — cron agent template
import subprocess, time, requests

relay = subprocess.Popen(["python3", "relay/acp_relay.py", "--name", "MyCronAgent"])
time.sleep(1)   # wait for startup

BASE = "http://localhost:7901"

# Broadcast availability
requests.patch(f"{BASE}/.well-known/acp.json", json={
    "availability": {
        "mode": "cron",
        "last_active_at": "2026-03-24T10:00:00Z",
        "next_active_at": "2026-03-24T10:05:00Z",
        "task_latency_max_seconds": 300,
    }
})

# Drain and process queued messages
msgs = requests.get(f"{BASE}/recv?limit=100").json()["messages"]
for m in msgs:
    text = m["parts"][0]["content"]
    requests.post(f"{BASE}/message:send",
                  json={"role":"agent","parts":[{"type":"text","content":f"Processed: {text}"}]})

relay.terminate()

Why it matters: A2A #1667 is still discussing heartbeat agent support as a proposal. ACP /recv solves this natively — available today.

Agent Identity (v2.85)

ACP auto-generates an Ed25519 keypair on first run — no flags required. The keypair is saved to ~/.acp/identity.json and reused across restarts.

# Default — Ed25519 auto-generated, zero config (v2.85+)
python3 relay/acp_relay.py --name MyAgent

# Custom keypair path (backward compat)
python3 relay/acp_relay.py --name MyAgent --identity ~/.acp/my-agent.json

# Hybrid identity (v1.5) — CA cert file
python3 relay/acp_relay.py --name MyAgent --ca-cert /path/to/agent.crt

# Disable identity (testing/embedded)
python3 relay/acp_relay.py --name MyAgent --no-identity

AgentCard example (hybrid mode):

{
  "identity": {
    "scheme":     "ed25519+ca",
    "public_key": "",
    "did":        "did:acp:",
    "ca_cert":    "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
  },
  "capabilities": {
    "identity": "ed25519+ca"
  }
}

Verification strategy (verifier's choice):

• Trust only did:acp: — verify Ed25519 signature, ignore ca_cert
• Trust only CA — verify certificate chain, ignore DID
• Require both — highest security
• Accept either — highest interoperability

Why it matters: A2A #1672 (44 comments, still in discussion) is converging on the same hybrid model. ACP v1.5 ships it today.

SDKs

What's New

→ Full Changelog

Repository Structure

agent-communication-protocol/
├── SKILL.md              ← Send this URL to any agent to onboard
├── relay/
│   └── acp_relay.py      ← Core daemon (single file, stdlib-first)
├── spec/                 ← Protocol specification documents
├── sdk/                  ← Python / Node.js / Go / Rust / Java SDKs
├── tests/                ← Compatibility + integration test suites
├── docs/                 ← Chinese docs, conformance guide, blog drafts
└── acp-research/         ← Competitive intelligence, ROADMAP

Show HN

ACP — P2P protocol for AI Agents to talk directly, no server required

The problem: Most multi-agent setups require a central orchestration server. When Agent A wants to message Agent B, you build infrastructure. When Agent B is behind NAT, you give up and poll.

What ACP does: Agent A runs one command, gets an acp:// link, sends it to Agent B. Agent B pastes the link. They're connected P2P — through NAT, firewalls, sandboxes — in under 5 seconds. No server. No registration. No OAuth dance.

# Agent A — anywhere in the world
python3 acp_relay.py --name AgentA
# ✅ Ready. Your link: acp://1.2.3.4:7801/tok_xxxxx

# Agent B — behind a corporate firewall / in a cloud sandbox
curl -X POST http://localhost:7901/peers/connect \
     -d '{"link":"acp://1.2.3.4:7801/tok_xxxxx"}'
# ✅ Connected. {"peer_id":"peer_001"}

How it works: Three-level auto-fallback — direct WebSocket → UDP hole punch (DCUtR) → relay. Your agents don't know or care which level they're on. The right level is chosen in < 3s.

ACP vs A2A (Google's protocol): A2A requires OAuth 2.0, an HTTPS endpoint you must host, and an agent registry. ACP requires pip install websockets. A2A is great for enterprise platforms; ACP is for individuals, sandboxed agents, and fast prototyping.

Status: Single-file Python daemon, 1574 tests passing, Apache 2.0. Built in public over ~190 commits. Would love feedback on the P2P design and the acp:// URI scheme.

Contributing

Contributions welcome! See CONTRIBUTING.md.

• Bug reports & feature requests → GitHub Issues
• Protocol design discussion → GitHub Discussions

License

Apache License 2.0

🚀 Quick Start

# Install
pip install websockets

# Start Agent A
python3 relay/acp_relay.py --name AgentA
# → ✅ Ready. Your link: acp://YOUR_IP:7801/tok_xxxxx

# In another terminal — Agent B connects
python3 relay/acp_relay.py --name AgentB \
  --join acp://YOUR_IP:7801/tok_xxxxx
# → ✅ Connected to AgentA