Architecture
The interop plane between agent brains — detailed.
A2AConnect is the product layer that makes mixed-runtime fleets operable: adapters, AgentPeer, policy, audit, and pluggable transport. It maps to LF A2A and sits beside MCP — it does not invent a rival wire standard.
System map
Three peers. One bus. Governed handoff.
Orchestrator (policy owner) → researcher (graph-style) → writer (crew-style), with audit on every lifecycle edge.
Stack layers
Top to bottom
Each layer has one job. Brains stay swappable; the envelope and governance stay stable.
Agent brains
Your runtimes stay yours — Python, LangGraph-shaped graphs, CrewAI-shaped roles, OpenAI agents, or custom asyncio.
Python · LangGraph-shaped · CrewAI-shaped · custom
Runtime adapters
RuntimeAdapter → TaskHandler via from_async_fn. No hard SDK lock-in; wrap the brain you already run.
from_async_fn · graph-style · crew-style
AgentPeer + governance
Handshake, capability negotiation, offer/accept, progress, events, result. Policy allowlists and MemoryAuditLog sit at the boundary.
hello · offer_task · policy · audit
Pluggable transport
Same envelopes over in-memory bus (dev), outbound buffer (backpressure), or HTTP JSON stub (edge).
in-memory · buffered · HTTP JSON
Local interop profile
Typed JSON messages mapped conceptually to LF A2A task lifecycle. Complements MCP for tools — does not replace either standard.
hello.* · capabilities.* · task.* · event
LF A2A
Industry peer wire standard. A2AConnect maps profile ≈ Agent Card, task.* ≈ Task lifecycle — does not replace it.
MCP
Agent ↔ tools/data. Orthogonal vertical: use MCP for tools, A2AConnect for peer handoff.
Standards map
Where LF A2A & MCP sit
Local interop profile for DX and tests; conceptual bridge to LF A2A on the roadmap. MCP remains the tools plane.
| A2AConnect | LF A2A | Role |
|---|---|---|
| Agent profile + capabilities | Agent Card | Discovery surface |
| task.offer → result / failed | Task lifecycle | Handoff semantics |
| task.progress + event | Streaming updates | Same transport |
| Policy + audit hooks | Product governance | A2AConnect layer |
| MCP (orthogonal) | — | Tools / data, not peers |
Connection lifecycle
From hello to audited result
Five phases on one transport. Streaming progress and events never leave the envelope model.
01
Discovery
hello → hello.ack
Peers open a session. sessionId binds later task traffic to the handshake.
Wire types
hellohello.ackpingpong02
Capabilities
capabilities.query → announce
Each peer advertises what it can run. Offers that require missing caps reject cleanly.
Wire types
capabilities.querycapabilities.announce03
Negotiate
task.offer → accept | reject
requiredCapabilities, goal, input, timeout, retries. Policy may deny before accept.
Wire types
task.offertask.accepttask.reject04
Execute
start → progress · event → result
Streaming progress and typed events share the transport. Buffer absorbs backpressure.
Wire types
task.starttask.progresseventtask.resulttask.failed05
Govern
policy + audit
before_offer / before_accept gates. MemoryAuditLog records the full lifecycle for fleets.
Wire types
before_offerbefore_acceptMemoryAuditLog
Envelope
Every message is typed JSON
Stable headers, swappable payload. Correlation and session ids stitch the handoff together.
vProfile versionidMessage idtypehello · task.offer · event · …from / toAgent ids on the bustsUnix timestampsessionIdBound at hello.ackcorrelationIdTies offer → resultpayloadTyped body for the message
Transports
Same peers, different pipes
Swap the transport; keep AgentPeer, adapters, policy, and audit.
In-memory bus
Local demos & testscreate_bus() fans envelopes between AgentPeer transports in one process.
Outbound buffer
Backpressurewith_outbound_buffer() queues sends so slow peers do not stall producers.
HTTP JSON stub
Edge / multi-hostSame envelope over HTTP — swap transport without rewriting peer logic.
Canonical docs: a2aconnect.dev/architecture. Repo mirrors: docs/architecture.md, protocol/SPEC.md.