Agent-to-Agent (A2A) Mesh

Learn how Kovalent nodes intelligently communicate, discover peers, and collaborate to solve complex queries securely over your Tailscale network.

The tenant mesh

When operating in the Team or Enterprise tiers, your local Kovalent nodes do not work in isolation. They form a secure tenant mesh. This allows nodes to query each other's specialized knowledge bases without centralizing sensitive data.

Discovery

The orchestrating node fetches peer manifests and scores each peer’s domain relevance against the query.

Federated Query / Consensus

Based on tier, the node either pulls raw vector chunks or delegates a sub-query for in-pod synthesis.

Final Assembly

The orchestrating node composes the peer’s response into a final, grounded answer for the user.

1. Peer discovery

Nodes expose a lightweight

/api/a2a/manifest

endpoint describing their domain expertise. Before executing a federated query, a node fetches its peers' manifests and embeds the user's query locally to rank peers by cosine similarity, routing the task only to the single best-matched node.

Dynamic Routing, not “spray and pray”

Nodes never broadcast blindly. Each manifest ships a pre-computed domain embedding, so the originating node scores relevance offline and selects the most capable peer.

2. Federated querying & consensus

Depending on your tier, nodes employ different strategies to synthesize data, trading raw compute against token efficiency.

Raw Vector Search (Community)

The orchestrating node sends a query vector to the target peer's

/api/a2a/search

endpoint. The peer performs a PGlite nearest-neighbour search (

embedding <-> query

) and returns the raw text chunks to the orchestrating node.

Map-Reduce Consensus (Pro/Team)

To conserve token limits, the node sends a sub-query to

/api/a2a/synthesize

. The peer searches its local database and uses its own local LLM to synthesize an answer, returning only the final compressed summary.

Local embeddings

Embeddings are computed in-process on the node. No text is ever sent to an external embedding API, which keeps the "data never leaves the node" promise intact end-to-end. Production nodes run a local ONNX model (e.g.

bge-small-en-v1.5

) in-pod; the reference node ships a deterministic offline embedder so the mesh performs genuine similarity search with zero external dependencies.

API reference

Every node exposes the same A2A surface. Transport security is delegated entirely to Tailscale, so endpoints are plain HTTP within the tenant mesh.

Method	Endpoint	Phase	Description
GET	`/api/a2a/manifest`	Discovery	Returns the node’s domain manifest + embedding for relevance scoring.
POST	`/api/a2a/search`	Federated Query	Runs a local pgvector search and returns raw chunks (Community).
POST	`/api/a2a/synthesize`	Consensus	Local search + in-pod synthesis; returns a compressed answer (Pro+).
POST	`/api/chat`	Orchestration	Entry point: discovers, scores, routes, and assembles the final answer.

Quickstart: run a local mesh

Spin up a two-node mesh (

node-a

node-b

) locally with Docker Compose. The nodes emit live telemetry to the Orchestrator API, which the Admin console renders in real time.

# Start the agent mesh (node-a on :8081, node-b on :8082)
docker compose --profile agents up -d --build

# Ask node-a a question; it discovers and delegates to node-b
curl -X POST http://localhost:8081/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I harden Tailscale ACLs?"}'

Because

node-b

advertises the security & networking domain,

node-a

scores it as the best-matched peer and delegates the sub-query via map-reduce synthesis.

Real-time telemetry

A2A interactions are fully observable. Nodes emit lightweight, non-blocking telemetry traces (e.g.

chat_initiated

manifest_evaluated

peer_selected

) to the Orchestrator, which fans them out to dashboards over Server-Sent Events (SSE).

Connecting to the live stream

Listen to the SSE stream from any client. On connect, the broker replays recent topology so you immediately see the existing mesh:

const es = new EventSource("https://api.kovalentai.com/api/telemetry/stream");

es.onmessage = (event) => {
  const trace = JSON.parse(event.data);
  // { sourceNode, targetNode, action, tier, timestamp }
  console.log(trace.sourceNode, "→", trace.targetNode, ":", trace.action);
};

Zero-Trust Compliance

Telemetry traces only contain metadata (node IDs and actions). Raw vector data never leaves the Data Plane.

Continue reading

The A2A mesh rides entirely on the encrypted transport described in Private Networking, and exists to deliver the guarantees laid out in our Platform Philosophy.