A2AConnectGet started

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.

LF A2Apeer wire standardMCPtools / data planeA2AConnect interop planeadapters · AgentPeer · policy · audit · pluggable transportTransport bus · in-memory · buffered · HTTP JSON stubOrchestratorcustom Pythonpolicy ownerResearchergraph-style adapterresearch.webWritercrew-style adapterwrite.briefPolicy gatesbefore_offer · before_accept · allowlistsAudit trailMemoryAuditLog · hello → result lifecycleTyped JSON envelopev · id · type · from · to · ts · correlationId · sessionId · payload

Stack layers

Top to bottom

Each layer has one job. Brains stay swappable; the envelope and governance stay stable.

01

Agent brains

Your runtimes stay yours — Python, LangGraph-shaped graphs, CrewAI-shaped roles, OpenAI agents, or custom asyncio.

Python · LangGraph-shaped · CrewAI-shaped · custom

02

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

03

AgentPeer + governance

Handshake, capability negotiation, offer/accept, progress, events, result. Policy allowlists and MemoryAuditLog sit at the boundary.

hello · offer_task · policy · audit

04

Pluggable transport

Same envelopes over in-memory bus (dev), outbound buffer (backpressure), or HTTP JSON stub (edge).

in-memory · buffered · HTTP JSON

05

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.

A2AConnectLF A2A
Agent profile + capabilitiesAgent Card
task.offer → result / failedTask lifecycle
task.progress + eventStreaming updates
Policy + audit hooksProduct governance
MCP (orthogonal)—

Connection lifecycle

From hello to audited result

Five phases on one transport. Streaming progress and events never leave the envelope model.

  1. 01

    Discovery

    hello → hello.ack

    Peers open a session. sessionId binds later task traffic to the handshake.

    Wire types

    hellohello.ackpingpong
  2. 02

    Capabilities

    capabilities.query → announce

    Each peer advertises what it can run. Offers that require missing caps reject cleanly.

    Wire types

    capabilities.querycapabilities.announce
  3. 03

    Negotiate

    task.offer → accept | reject

    requiredCapabilities, goal, input, timeout, retries. Policy may deny before accept.

    Wire types

    task.offertask.accepttask.reject
  4. 04

    Execute

    start → progress · event → result

    Streaming progress and typed events share the transport. Buffer absorbs backpressure.

    Wire types

    task.starttask.progresseventtask.resulttask.failed
  5. 05

    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 version
  • idMessage id
  • typehello · task.offer · event · …
  • from / toAgent ids on the bus
  • tsUnix timestamp
  • sessionIdBound at hello.ack
  • correlationIdTies offer → result
  • payloadTyped body for the message

Transports

Same peers, different pipes

Swap the transport; keep AgentPeer, adapters, policy, and audit.

In-memory bus

Local demos & tests

create_bus() fans envelopes between AgentPeer transports in one process.

Outbound buffer

Backpressure

with_outbound_buffer() queues sends so slow peers do not stall producers.

HTTP JSON stub

Edge / multi-host

Same envelope over HTTP — swap transport without rewriting peer logic.

Canonical docs: a2aconnect.dev/architecture. Repo mirrors: docs/architecture.md, protocol/SPEC.md.