guide

a2a for code review: bring any agent into the room

diff social speaks a2a 1.0, the agent2agent protocol. its own review agents are a2a agents with published agent cards, and any a2a agent can join a review as a peer. here is how that works, with the real card from this instance.

what a2a is, in one paragraph

a2a (agent2agent) is an open protocol for agents to discover each other and work together. it was introduced by google in 2025 and is now a linux foundation project. an agent publishes an agent card, a json document saying who it is, where to reach it, how to authenticate, and which skills it offers; another agent reads the card and sends it tasks as json-rpc messages, with streaming updates.

a2a vs mcp

they are complementary, not rivals: an a2a agent can use mcp tools inside, and often does.

a real agent card

every diff social instance publishes the card for its built-in agents at /.well-known/agent-card.json. this one, from diffsocial.dev, shortened:

{
  "name": "diff social",
  "description": "built-in agents of this diff social instance; pick one with tenant",
  "version": "0.1.0",
  "supportedInterfaces": [
    { "url": "https://diffsocial.dev/a2a", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }
  ],
  "capabilities": { "streaming": true, "pushNotifications": false },
  "defaultInputModes": ["application/vnd.diffsocial.focus+json", "text/plain"],
  "defaultOutputModes": ["application/vnd.diffsocial.proposal+json", "text/plain"],
  "securitySchemes": { "bearer": { "httpAuthSecurityScheme": { "scheme": "Bearer" } } },
  "skills": [
    { "id": "flags" }, { "id": "history" }, { "id": "semantics" },
    { "id": "reviewer" }, { "id": "patcher" }
  ]
}

each built-in agent also has its own card, at /a2a/agents/<id>/agent-card.json. what each one does is described in the agents in a room.

bringing your own agent

• run any agent that speaks a2a 1.0 and publishes an agent card;
• a team admin adds it to diff social by the card's address; the agent then appears beside the built-in ones;
• in a room, people select lines and ask it, exactly as they ask the built-in agents; it receives the selected lines and their context, and answers in the stream;
• its answer is a proposal that a person accepts or rejects. agents propose; people decide.

diff social reaches outside agents only at public addresses: a card that resolves to a private or internal address is refused, so adding an agent cannot be used to make the server call into its own network. each team keeps its own list of agents, up to 20.

why a2a suits review

review benefits from several independent opinions more than from one model with more tools. a2a lets a team mix agents from different vendors, and its own, in one review, each seeing the same lines and answering in the same stream, with people deciding what to keep.