Agent Pair Protocol

An open protocol for end-to-end encrypted between two personal AI agents. Agent↔Agent across trust boundaries: SPAKE2 pairing via a short human-exchanged code, dumb relay, keys never leave the host.

Comment 2

Inspiration

I write APIs. My friend writes firmware for machines.

On paper, our job is simple: agree on a contract, ship data, watch the lights blink. In practice, we spent two and a half days hunting a single bug: the machine never received what the backend thought it had sent.

The debugging loop looked like this:

  1. I paste logs into my AI assistant.
  2. I screenshot the answer into WhatsApp.
  3. He pastes them into his AI assistant.
  4. He sends a different theory back.
  5. I copy that into my chat again.
  6. Repeat until someone falls asleep.

We were not collaborating. We were human routers for two AIs that could not talk to each other. Every insight had to pass through tired fingers, broken context, and a group chat that mixed stack traces with "still failing."

That week left a mark. The tools were brilliant in isolation. Together, they were deaf. I did not want a better chat app for developers. I wanted a protocol where my agent and his agent could negotiate a contract, exchange evidence, and fail closed — without us becoming the wire.

That frustration became Agent Pair Protocol.

What it does

Agent Pair is an open protocol for personal agent-to-agent communication: two AI agents, each acting for one human, exchange end-to-end-encrypted messages through an untrusted relay to negotiate concrete deliverables — schedules, API contracts, documents, firmware interfaces.

In the API + firmware story, the agents would:

  • Pair once via a short code humans exchange out-of-band (WhatsApp is fine for the code; never for the payload)
  • Negotiate a machine-readable contract with budgets and deadlines
  • Exchange proposals, counters, and test evidence under cryptographic authenticity
  • Co-sign only when both sides (and both humans, when gates require it) are ready

Design principles we refuse to compromise:

  1. Keys never leave the agent host. The model reasons; the host signs.
  2. The relay is dumb. It sees routing metadata and ciphertext — nothing else.
  3. Humans gate trust. Bonding requires a code exchanged between people. Either side can revoke unilaterally.
  4. Authenticity is not trustworthiness. A verified message is still untrusted input for an AI model. We surface peer content as data, not as instructions to obey.

The reference stack ships today: a TypeScript protocol library, an MCP server (agentpair) so Cursor / Claude / Codex-style clients can drive the host, a Hono + SQLite dumb relay, and conformance vectors so a third party can implement Core without guessing.

How we built it

We treated this as a protocol first, product second problem.

  • Wire format: fixed crypto suite (Ed25519, X25519, XChaCha20-Poly1305, SPAKE2 for pairing). No algorithm agility field — that class of bugs is how alg:none happens.
  • Sign-the-blob envelopes: serialize once, sign the exact bytes, never re-canonicalize JSON across languages.
  • Bonded pairing: short human-exchanged codes, identity-bound fingerprints, single-use codes, human approval gates.
  • Negotiation profile: sessions with goals, budgets, deadlines, turn discipline, and co-sign paths.
  • Spillover: large payloads leave the 64 KiB envelope cap as encrypted artifacts on the relay.
  • MCP binding: tools like pair_init, pair_join, session_open, session_msg so agents do the work while humans stay in the trust loop.
  • Conformance mindset: golden vectors, relay conformance suite, checklist mapping every MUST in the Core spec to a test.

Codex and agentic coding tools were part of the build loop for scaffolding tests, exploring edge cases in the receiver algorithm, and keeping a large monorepo consistent while the wire format evolved. The security-sensitive decisions (what is signed, what the relay may never learn, how peer content is presented to the model) stayed human-owned.

Challenges we ran into

The WhatsApp problem was only the surface. Underneath sat harder questions:

  • How do two agents trust a peer without trusting the network?
  • How do you stop a relay from swapping identities during pairing?
  • How do you let AIs negotiate without letting peer text become prompt injection with a signature on top?
  • How small can Core stay so someone else can implement it in a weekend?

We hit real bugs that forced design changes — including identity-bound pairing fingerprints after a class of relay identity-swap attacks became obvious. We also learned that "the model will be careful" is not a security property. Authenticity ≠ trustworthiness had to become a first-class section of the protocol, not a footnote.

Building for two humans on two machines is also unforgiving. Demo state dies if one MCP restarts mid-pair. DX papercuts feel like protocol bugs. That pressure kept the design honest.

Accomplishments that we're proud of

  • A working end-to-end path: pair → bond → negotiate → spillover → co-sign, over a real relay.
  • A security model with teeth: human-gated bonding, dumb relay, keys on host, untrusted-peer presentation of inbox content.
  • Spec + reference implementation that track each other, with golden vectors and a conformance checklist — not a slide deck that "could be a protocol someday."
  • Keeping Core small on purpose: Negotiation is a profile, not the whole universe. Third parties should be able to invent use cases we never planned (including the API ↔ firmware loop that started this).

What we learned

Collaboration between people is often secretly collaboration between their tools. When those tools cannot talk, humans become the protocol — and humans make terrible transports: high latency, lossy context, emotional fatigue.

We also learned that multi-agent systems fail first at the trust boundary, not at the model quality boundary. Two excellent agents still cannot safely coordinate if every byte is either fully trusted or fully manual.

And personally: the most valuable product insight came from being exhausted at 1 a.m., still pasting stack traces into WhatsApp, thinking "there has to be a better wire for this."

What's next for Agent Pair Protocol

Near term (public v1.0):

  • Spec freeze and npm 1.0.0 of agentpair + @agentpair/protocol
  • Fresh-clone dogfood: two humans, two machines, one real deliverable
  • "Implement Core in a weekend" guide on top of golden vectors
  • Optional public relay with hard rate limits (self-host remains first-class)

After that:

  • Independent Core implementations (Python / Go / Rust) against our vectors
  • Skill packs for concrete negotiations (API contracts, scheduling, hardware interfaces)
  • Real-world dogfood with the original pain: backend agent ↔ firmware agent agreeing on a payload schema and proving both sides pass the same acceptance checks — without another two-day WhatsApp archaeology session

If this works, nobody has to be the router for their AI again.

Built With

Share this project:

Updates