Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""The A2A ingress in one process: this SDK's /libp2p-http handler for one
agent behind a py-libp2p host, called with this SDK's client, the streaming
client and an httpx client on MeshTransport. The real agentmesh-node as a caller is
exercised by tests/integration."""
import json
import threading
from dataclasses import dataclass
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import biscuit_auth as ba
import httpx
import multiaddr
import pytest
import trio
from libp2p.peer.id import ID
from libp2p.peer.peerinfo import info_from_p2p_addr
from agent_mesh.authorizer import ProviderAuthorizerOptions
from agent_mesh.controlplane import ROLE_NODE
from agent_mesh.httpx_transport import MeshTransport, split_mesh_url
from agent_mesh.identity import Identity
from agent_mesh.libp2p_http import (
AGENT_CARD_PATH,
HTTP_PROTOCOL,
A2AEndpoint,
HTTPRequest,
HTTPResponse,
ProviderOptions,
http_ingress_handler,
http_request_over_stream,
mesh_http_target,
mesh_interface_url,
open_http_request,
rewrite_agent_card,
)
from agent_mesh.session import MeshSession
from .test_session import CP, CP_KEY, libp2p_host
# What the control plane renders for a policy granting the node role every
# A2A service on any target, and nothing else.
POLICY_RULES = [
'granted_service_all("a2a") <- role("mesh:role:node")',
'granted_service_all("mesh:system") <- role("mesh:role:node")',
'target_unrestricted(true) <- role("mesh:role:node")',
]
def mint(peer_id: str, role: str) -> bytes:
return ba.BiscuitBuilder(
"node({p}); client_peer_id({p}); expiration(2035-01-01T00:00:00Z); role({r});", {"p": peer_id, "r": role}
).build(CP.private_key).to_bytes()
STOCK_CARD = {
"name": "echo-agent",
"version": "1.0.0",
"capabilities": {"streaming": True, "pushNotifications": False},
"supportedInterfaces": [
{"url": "http://127.0.0.1:7777/", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"},
{"url": "127.0.0.1:50051", "protocolBinding": "GRPC", "protocolVersion": "1.0"},
],
"signatures": [{"protected": "eyJhbGciOiJFUzI1NiJ9", "signature": "c3RhbGU"}],
"skills": [],
"defaultInputModes": ["text/plain"],
"defaultOutputModes": ["text/plain"],
}
class FakeA2AServer(BaseHTTPRequestHandler):
"""Stands in for an A2A server beside the agent: echoes the request and,
on /stream, answers with three SSE events as message/stream would."""
seen: list[dict] = []
def _answer(self) -> None:
length = int(self.headers.get("content-length") or 0)
body = self.rfile.read(length) if length else b""
FakeA2AServer.seen.append(
{
"method": self.command,
"path": self.path,
"peer": self.headers.get("x-peer-id"),
"body": body.decode(),
"biscuit": self.headers.get("x-mesh-biscuit"),
"encoding": self.headers.get("accept-encoding"),
}
)
if self.path == f"/{AGENT_CARD_PATH}" and self.headers.get("x-card") == "missing":
self.send_response(404)
self.send_header("content-type", "text/plain")
self.send_header("content-length", "7")
self.end_headers()
self.wfile.write(b"no card")
return
if self.path == "/stream":
self.send_response(200)
self.send_header("content-type", "text/event-stream")
self.end_headers()
for i in range(3):
self.wfile.write(f"data: {json.dumps({'event': i})}\n\n".encode())
self.wfile.flush()
return
if self.path == f"/{AGENT_CARD_PATH}":
grpc_only = self.headers.get("x-card") == "grpc-only"
interfaces = [i for i in STOCK_CARD["supportedInterfaces"] if not grpc_only or i["protocolBinding"] == "GRPC"]
payload = json.dumps({**STOCK_CARD, "supportedInterfaces": interfaces}).encode()
else:
payload = json.dumps({"path": self.path, "echo": body.decode()}).encode()
self.send_response(200)
self.send_header("content-type", "application/json")
self.send_header("x-backend", "fake")
self.send_header("content-length", str(len(payload)))
self.end_headers()
self.wfile.write(payload)
do_GET = _answer
do_POST = _answer
def log_message(self, *_args) -> None: # noqa: D102 - quiet
pass
@pytest.fixture(scope="module")
def backend_url():
server = ThreadingHTTPServer(("127.0.0.1", 0), FakeA2AServer)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
yield f"http://127.0.0.1:{server.server_port}"
server.shutdown()
async def start_agent(nursery, target, authorized: list[str]):
identity = Identity.generate()
host = libp2p_host(identity)
biscuit = mint(identity.peer_id, ROLE_NODE)
options = ProviderOptions(
authorizer=ProviderAuthorizerOptions(trusted_keys=lambda: [CP_KEY], own_biscuit=lambda: biscuit, policy_rules=lambda: POLICY_RULES),
on_authorized=lambda peer, _v, service: authorized.append(f"{peer} {service}"),
)
host.set_stream_handler(HTTP_PROTOCOL, http_ingress_handler(A2AEndpoint(target=target), options))
started = trio.Event()
addr_box = []
async def run():
async with host.run(listen_addrs=[multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/0")]):
addr_box.append(multiaddr.Multiaddr(f"{host.get_addrs()[0]}"))
started.set()
await trio.sleep_forever()
nursery.start_soon(run)
await started.wait()
return host, addr_box[0]
@dataclass
class _Credential:
biscuit: bytes
@dataclass
class _Mesh:
credential: _Credential
class FakeSession:
"""What MeshTransport needs of a session: the host, the credential and
_egress_peer(); the peer is already connected and verified here."""
def __init__(self, host, biscuit: bytes) -> None:
self.host = host
self.mesh = _Mesh(_Credential(biscuit))
async def _egress_peer(self, peer, target_service) -> ID:
return ID.from_base58(str(peer))
def test_the_agent_is_reachable_by_authorized_callers(backend_url):
authorized: list[str] = []
async def main():
async with trio.open_nursery() as nursery:
agent, addr = await start_agent(nursery, backend_url, authorized)
caller_identity = Identity.generate()
caller = libp2p_host(caller_identity)
caller_biscuit = mint(caller_identity.peer_id, ROLE_NODE)
guest_biscuit = mint(caller_identity.peer_id, "mesh:role:guest")
async with caller.run(listen_addrs=[]):
await caller.connect(info_from_p2p_addr(addr))
pid = agent.get_id()
# The agent is forwarded the request with the caller's identity and without its biscuit.
res = await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", "/card?x=1", headers={"x-mesh-biscuit": "spoof"})
assert res.status == 200
assert res.headers.get("x-backend") == "fake"
assert res.json() == {"path": "/card?x=1", "echo": ""}
assert FakeA2AServer.seen[-1]["peer"] == caller_identity.peer_id
assert FakeA2AServer.seen[-1]["biscuit"] is None
assert f"{caller_identity.peer_id} a2a://agent" in authorized
post = await http_request_over_stream(
caller, pid, caller_biscuit, "a2a://agent", "/", method="POST", headers={"content-type": "application/json"}, body='{"jsonrpc": "2.0"}'
)
assert post.status == 200 and post.json()["echo"] == '{"jsonrpc": "2.0"}'
# A streamed body arrives event by event.
streamed = await open_http_request(caller, pid, caller_biscuit, "GET", mesh_http_target("a2a://agent", "/stream"))
assert streamed.status == 200 and streamed.headers["content-type"] == "text/event-stream"
events = []
async for chunk in streamed.iter_body():
events.extend(line for line in chunk.decode().split("\n") if line.startswith("data:"))
await streamed.aclose()
assert events == ['data: {"event": 0}', 'data: {"event": 1}', 'data: {"event": 2}']
# An httpx client on the mesh transport, as the A2A SDK's client is.
session = FakeSession(caller, caller_biscuit)
url = MeshSession.mesh_url(str(pid), "a2a://agent")
assert url == f"http://mesh/mesh/{pid}/a2a/agent"
async with httpx.AsyncClient(transport=MeshTransport(session)) as client: # type: ignore[arg-type]
answer = await client.post(url, json={"method": "message/send"}, headers={"x-mesh-biscuit": "spoof"})
assert answer.status_code == 200 and answer.json()["echo"] == '{"method":"message/send"}'
assert FakeA2AServer.seen[-1]["peer"] == caller_identity.peer_id
assert FakeA2AServer.seen[-1]["biscuit"] is None
async with client.stream("GET", url + "/stream") as answer:
lines = [line async for line in answer.aiter_lines() if line.startswith("data:")]
assert lines == ['data: {"event": 0}', 'data: {"event": 1}', 'data: {"event": 2}']
with pytest.raises(httpx.UnsupportedProtocol):
await client.get("http://mesh/not/the/mesh")
# What the policy does not grant is refused before the agent is reached.
before = len(FakeA2AServer.seen)
assert (await http_request_over_stream(caller, pid, guest_biscuit, "a2a://agent", "/card")).status == 403
assert (await http_request_over_stream(caller, pid, caller_biscuit, "inference://agent", "/")).status == 403
assert len(FakeA2AServer.seen) == before
# Granted, but not this agent: 404 after authorization.
assert (await http_request_over_stream(caller, pid, caller_biscuit, "a2a://other", "/card")).status == 404
assert (await http_request_over_stream(caller, pid, b"", "a2a://agent", "/card")).status == 401
assert (await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", "/../other/x")).status == 400
# A URL parser reads %2e as a dot too; the spelling does not get past the check.
assert (await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", "/%2e%2e/other/x")).status == 400
assert (await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", "/.%2E/other/x")).status == 400
assert (await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", "/%2f..%2fother/x")).status == 400
assert (await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", "/%5c..%5cother/x")).status == 400
nursery.cancel_scope.cancel()
async def with_timeout():
with trio.fail_after(30):
await main()
trio.run(with_timeout)
def test_the_card_of_an_agent_behind_a_node_comes_back_rewritten_for_the_mesh(backend_url):
async def main():
async with trio.open_nursery() as nursery:
agent, addr = await start_agent(nursery, backend_url, [])
caller_identity = Identity.generate()
caller = libp2p_host(caller_identity)
caller_biscuit = mint(caller_identity.peer_id, ROLE_NODE)
async with caller.run(listen_addrs=[]):
await caller.connect(info_from_p2p_addr(addr))
pid = agent.get_id()
base = MeshSession.mesh_url(str(pid), "a2a://agent")
async with httpx.AsyncClient(transport=MeshTransport(FakeSession(caller, caller_biscuit))) as client: # type: ignore[arg-type]
answer = await client.get(f"{base}/{AGENT_CARD_PATH}")
assert answer.status_code == 200 and answer.headers["content-type"] == "application/json"
card = answer.json()
assert card["supportedInterfaces"] == [{"url": base, "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}]
assert card["capabilities"] == {"streaming": True, "pushNotifications": False}
assert "signatures" not in card and card["name"] == "echo-agent" and card["skills"] == []
assert FakeA2AServer.seen[-1]["path"] == f"/{AGENT_CARD_PATH}"
# The bare service root serves the card too, the way a2a-go resolves a pathful base URL,
# and the fetch is the SDK's own: at the well-known path, without the client's accept-encoding.
assert (await client.get(base, headers={"accept-encoding": "x-test-only"})).json() == card
assert FakeA2AServer.seen[-1]["path"] == f"/{AGENT_CARD_PATH}" and FakeA2AServer.seen[-1]["encoding"] != "x-test-only"
missing = await client.get(f"{base}/{AGENT_CARD_PATH}", headers={"x-card": "missing"})
assert missing.status_code == 404 and missing.text == "no card"
refused = await client.get(f"{base}/{AGENT_CARD_PATH}", headers={"x-card": "grpc-only"})
assert refused.status_code == 502 and "no supported interface the mesh can carry" in refused.text
assert (await client.get(f"{base}/card")).json() == {"path": "/card", "echo": ""}
raw = await http_request_over_stream(caller, pid, caller_biscuit, "a2a://agent", f"/{AGENT_CARD_PATH}")
assert raw.status == 200 and raw.json() == card
nursery.cancel_scope.cancel()
async def with_timeout():
with trio.fail_after(30):
await main()
trio.run(with_timeout)
def test_rewrite_agent_card_keeps_only_what_the_mesh_carries():
with pytest.raises(ValueError, match="not a JSON object"):
rewrite_agent_card([], "http://mesh/x")
with pytest.raises(ValueError, match="no supported interface"):
rewrite_agent_card({"supportedInterfaces": []}, "http://mesh/x")
assert rewrite_agent_card({"supportedInterfaces": [{"url": "http://localhost:7777/", "protocolBinding": "http+json"}]}, "http://mesh/x") == {
"supportedInterfaces": [{"url": "http://mesh/x", "protocolBinding": "http+json"}],
}
def test_rewrite_agent_card_keeps_the_interface_path_the_provider_names():
# As agentmesh-node's TestA2AServiceCardKeepsInterfacePaths: the provider's node names
# each interface relative to its target URL, and the caller's card resolves it under
# the mesh URL, so an agent whose JSON-RPC endpoint is "/invoke" stays reachable there.
base = "http://mesh/mesh/12D3KooWpeer/a2a/agent"
card = rewrite_agent_card(
{
"supportedInterfaces": [
{"url": "invoke", "protocolBinding": "JSONRPC"},
{"url": "a2a/rest", "protocolBinding": "HTTP+JSON"},
{"url": "", "protocolBinding": "JSONRPC"},
{"url": "v1/rpc?tenant=a", "protocolBinding": "JSONRPC"},
{"url": "http://localhost:7777/invoke", "protocolBinding": "JSONRPC"},
{"protocolBinding": "JSONRPC"},
{"url": "localhost:50051", "protocolBinding": "GRPC"},
],
},
base,
)
assert [iface["url"] for iface in card["supportedInterfaces"]] == [
f"{base}/invoke",
f"{base}/a2a/rest",
base,
f"{base}/v1/rpc?tenant=a",
base,
base,
]
BASE = "http://127.0.0.1:8080/mesh/12D3KooWpeer/a2a/agent"
# As agentmesh-node's TestMeshInterfaceURLStaysInService: a provider cannot use the
# relative reference to point a caller at another path on the caller's own node.
@pytest.mark.parametrize(
("ref", "want"),
[
("", BASE),
("invoke", f"{BASE}/invoke"),
("a2a/rest/", f"{BASE}/a2a/rest/"),
("?tenant=a", f"{BASE}?tenant=a"),
("../../../../debug/connect-peer", BASE),
("a/../../x", BASE),
("%2e%2e/%2e%2e/debug", BASE),
("./invoke", BASE),
("/debug/connect-peer", BASE),
("//evil.example/x", BASE),
("http://localhost:7777/invoke", BASE),
("mailto:[email protected]", BASE),
("%zz", BASE),
# Go's url.Parse and URL.EscapedPath, byte for byte.
("invoke#frag", f"{BASE}/invoke"),
("invoke#%zz", BASE),
("in\tvoke", BASE),
("1a:b", BASE),
("v1/a:b", f"{BASE}/v1/a:b"),
("a%2Fb", f"{BASE}/a%2Fb"),
("a%41", f"{BASE}/a%41"),
("%2f/debug", BASE),
("%2A", f"{BASE}/*"),
("it's(1)*", f"{BASE}/it's(1)*"),
("a b", f"{BASE}/a%20b"),
("a b%41", f"{BASE}/a%20bA"),
("\u00e9t\u00e9", f"{BASE}/%C3%A9t%C3%A9"),
("\ud800", f"{BASE}/%EF%BF%BD"),
("x?", f"{BASE}/x"),
("x?a?b", f"{BASE}/x?a?b"),
],
)
def test_mesh_interface_url_stays_in_the_service(ref, want):
assert mesh_interface_url(BASE, ref) == want
def test_an_in_process_handler_sees_the_verified_caller():
async def hello(request: HTTPRequest, caller) -> HTTPResponse:
return HTTPResponse(status=201, body=f"hello {caller.peer_id} {request.method} {request.path}".encode())
async def main():
async with trio.open_nursery() as nursery:
agent, addr = await start_agent(nursery, hello, [])
caller_identity = Identity.generate()
caller = libp2p_host(caller_identity)
async with caller.run(listen_addrs=[]):
await caller.connect(info_from_p2p_addr(addr))
res = await http_request_over_stream(caller, agent.get_id(), mint(caller_identity.peer_id, ROLE_NODE), "a2a://agent", "/agent/card")
assert res.status == 201 and res.text == f"hello {caller_identity.peer_id} GET /agent/card"
nursery.cancel_scope.cancel()
async def with_timeout():
with trio.fail_after(30):
await main()
trio.run(with_timeout)
def test_mesh_urls_name_a_peer_and_a_service():
peer = "12D3KooWJ2Yhy3CKwVPDw7AnkxN5HbZbb65xDoRif54hdXXUzh1U"
assert split_mesh_url(httpx.URL(f"http://mesh/mesh/{peer}/a2a/agent")) == (peer, "a2a://agent", "/a2a/agent")
assert split_mesh_url(httpx.URL(f"http://anything:1/mesh/{peer}/inference/llm/v1/models?x=1")) == (peer, "inference://llm", "/inference/llm/v1/models?x=1")
for bad in ("http://mesh/a2a/agent", f"http://mesh/mesh/{peer}", f"http://mesh/mesh/{peer}/a2a", f"http://mesh/mesh//a2a/agent"):
with pytest.raises(httpx.UnsupportedProtocol):
split_mesh_url(httpx.URL(bad))
assert mesh_http_target("a2a://agent") == "/a2a/agent"
assert mesh_http_target("a2a://agent", "card") == "/a2a/agent/card"
assert mesh_http_target("egress://api.github.com", "/repos/acme/x") == "/egress/api.github.com/repos/acme/x"
with pytest.raises(ValueError):
mesh_http_target("ftp://agent", "/")
def test_a_reset_mid_body_is_an_error_and_a_close_is_the_end():
"""A body that arrives without a length (server-sent events) ends when
the peer closes its side. The same body cut by a reset must not pass for
one that ended: without a length there is nothing in HTTP to tell them
apart, only the stream knows."""
async def truncating(stream) -> None:
# Same framing as `closing`, reset instead of closed.
await stream.write(b"HTTP/1.1 200 OK\r\ncontent-type: text/event-stream\r\n\r\ndata: 1\n\n")
await stream.reset()
async def closing(stream) -> None:
# No length and no chunking: the close is the end of the body.
await stream.write(b"HTTP/1.1 200 OK\r\ncontent-type: text/event-stream\r\n\r\ndata: 1\n\ndata: 2\n\n")
await stream.close()
async def main():
async with trio.open_nursery() as nursery:
server = libp2p_host(Identity.generate())
handlers = {"/inference/cut": truncating, "/inference/end": closing}
async def route(stream) -> None:
request = b""
while b"\r\n\r\n" not in request:
request += await stream.read(1024)
path = request.split(b" ", 2)[1].decode()
await handlers[path](stream)
server.set_stream_handler(HTTP_PROTOCOL, route)
started = trio.Event()
addr_box = []
async def run():
async with server.run(listen_addrs=[multiaddr.Multiaddr("/ip4/127.0.0.1/tcp/0")]):
addr_box.append(multiaddr.Multiaddr(f"{server.get_addrs()[0]}"))
started.set()
await trio.sleep_forever()
nursery.start_soon(run)
await started.wait()
caller = libp2p_host(Identity.generate())
async with caller.run(listen_addrs=[]):
await caller.connect(info_from_p2p_addr(addr_box[0]))
pid = server.get_id()
with trio.fail_after(10):
ended = await open_http_request(caller, pid, b"x", "GET", "/inference/end")
assert ended.status == 200
assert (await ended.read()).decode().count("data:") == 2
await ended.aclose()
cut = await open_http_request(caller, pid, b"x", "GET", "/inference/cut")
assert cut.status == 200
with pytest.raises(ConnectionError, match="mid-response"):
await cut.read()
await cut.aclose()
nursery.cancel_scope.cancel()
trio.run(main)