## Summary Raven speaks the Agent2Agent protocol, version 1.0, in both directions. The host agent is the peer: nothing here makes a sub-agent addressable from outside, and a raven launched as a sub-agent refuses to serve the face at all, because it is already reached over ACP by the host that started it. Inbound is an aiohttp face carrying the two cards and a JSON-RPC endpoint. It mounts on the gateway when `a2a.server.enabled` is set, and `raven a2a serve` runs it standalone for a headless deployment, where running the command is itself the opt-in. Outbound is a single tool, `a2a_send`, that takes a card URL and a message; it enters the tool list only when `a2a.peers` is non-empty, so a host with nowhere to send a message does not carry the schema. The two switches are deliberately independent: calling out and being called are separate deployments. Onboarding mints `a2a.server.token` and stops there. The face ships closed: finishing an unrelated install is not consent to open a second network surface, so `raven a2a enable` is what opens it, and it is the only writer of that flag. Enabling mints a missing token in the same command, because a face switched on with an empty token answers every caller with a 401 and reads as a broken deployment rather than the closed door it is. `raven a2a disable` closes it again and keeps the token, so reopening does not re-issue a credential callers already hold. The wizard never writes the flag at all, not even as false, so a repeat onboard leaves a face the operator opened by hand alone. A config nobody onboarded, and any `A2aConfig()` assembled in process, stays inert. What that opens is narrower than a network face. The app carrying it binds loopback at both call sites, hardcoded rather than read from config, and every request is checked against a freshly minted 256-bit bearer token. The minting write is also what fixes `config.json` to owner-only, from the temporary file's first byte rather than with a chmod afterwards; a later enable or disable adds no secret material, so it leaves whatever mode the operator chose. Nothing else narrows that file and it already held provider API keys, so the obligation predates this work and is merely discharged here. There are two cards because the protocol splits one description across two authentication states. The public card answers an unauthenticated GET, and has to: a caller reads it to learn which scheme to authenticate with, so requiring the credential first would be circular. It therefore names no installed agent. The extended card is a `GetExtendedAgentCard` RPC riding the same bearer check as every other method, and is the only one of the two that may say what this host can actually do. On that extended card the sub-agent roster rides `capabilities.extensions`, not `skills`. A skill is the protocol's word for something an agent can be asked to do, and a peer cannot ask for one named sub-agent: it can only send a message to this host, which then decides what to dispatch. One skill per sub-agent would advertise call targets that do not exist. What a peer can genuinely request is the orchestration, so that is a single skill, and the roster moves to the protocol's own extension point under a versioned URI. That is the only place a conformant card may carry a payload the spec does not define, because `AgentCard` is a closed set of fourteen protobuf fields: a custom top-level key is rejected by a strict parser and silently dropped by a lenient one. The entry declares `required` false, so a reader that has never heard of the URI ignores it and still talks to this host. Both cards derive `supportedInterfaces[].url` from the origin the caller arrived on. One face answers under every name that routes to it, and a URL fixed when the face is mounted is right for at most one of them. This matters more than it looks: a caller that finds an interface off the card's own origin must refuse it, since a card fetched from a trusted origin would otherwise redirect the credential elsewhere, and a relative URL reads as off-origin to that check. ## Type - [x] Feature ## Verification - `make test-python` at this head: 23729 passed, 112 skipped, 1 failed, in 288 s. The one failure is `tests/test_install_script.py::test_resolve_node_dir_answers_each_case_it_exists_for`, which fails with the same assertion on `origin/main` by itself; this branch changes no install or node file. - `uv run --frozen --all-extras pytest tests/integration/test_a2a_protocol_e2e.py -q`: 6 passed. That directory sits outside the default pytest scope, so it is run by hand rather than reached by the line above. - `make lint-imports`: 10 contracts kept, 0 broken. `make lint-types`: all checks passed. - `uv run ruff check raven/ tests/`: clean. `ruff format --check`: clean. - `make check-commits` over all 68 commits, `make check-source-language`, `make check-large-files`: all exit 0. - Live, over a real network boundary rather than in process: a raven in a Docker container and a raven on the host, each running this branch, called each other in both directions. Nineteen assertions per direction covering both cards, the four refusal paths, and a completed turn. The container publishes its face on a different port than it binds, so the card has to name the port the caller used and not the socket the server opened; both cards did, in both directions. That run predates the default-off change described above, which touches no file under `raven/a2a/` or `raven/a2a_client/`: both packages are byte-identical to the head it ran against. - Reverting each fix turns its own tests red, checked one fix at a time rather than all together, including the interface-URL fix mutated out inside the running container. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk Behaviour changes for an operator who runs `raven onboard` after this lands: a token is minted into `a2a.server.token`, and `config.json` is narrowed to owner-only. No listening face is opened. Opening one takes `raven a2a enable` and a gateway restart, so the second network surface only ever exists because somebody typed for it. Rolling an opened face back is `raven a2a disable` and a restart. The token stays in place and is never rotated, so callers already holding it keep working when the face is reopened, and a later onboard will not reopen it by itself. Nothing else in the install changes. Costs and limits, stated rather than left to be discovered: - A gateway that serves A2A imports `a2a-sdk`, measured at roughly 570 ms and 391 modules on top of the gateway's own stack, sqlalchemy and the OpenTelemetry api among them. It is paid once at mount, not per request, and an operator who switches the face off pays none of it. Moving it to the first request is recorded as deferred in the design note rather than done here. - `a2a_send` adds 157 tokens to the tool array of every turn, measured off a captured provider call, and only on a host with a peer configured. - The task store is in memory and unbounded, and inbound concurrency is not capped. A local face behind a bearer token is the deployment this is written for; a host exposed more widely should bound both first. - Pulling in `a2a-sdk` brings the OpenTelemetry api into the gateway's import graph. This is a trade accepted for the SDK's protocol types and handler, not an adoption of OpenTelemetry by this project. Checked during review and deliberately not fixed here: config validation accepts an agent row with an empty or whitespace name, which would reach the extended card's roster as an empty entry. It is not introduced by this work, the previous shape carried the same value, and closing it belongs with the agent schema rather than with the card. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: Claude (claude-opus-5) <noreply@anthropic.com>
244 lines
8.9 KiB
Python
244 lines
8.9 KiB
Python
"""The outbound tool: its schema, and that it never surfaces a credential."""
|
|
|
|
import json
|
|
|
|
import httpx
|
|
import pytest
|
|
|
|
from raven.a2a_client.client import send_message
|
|
from raven.a2a_client.tool import A2aTool
|
|
from raven.config.schema import A2aConfig
|
|
|
|
CONFIG = A2aConfig.model_validate(
|
|
{"peers": [{"origin": "https://peer.example.com", "authScheme": "bearer", "credential": "sekrit"}]}
|
|
)
|
|
|
|
|
|
def test_tool_name_is_stable():
|
|
assert A2aTool(CONFIG).name == "a2a_send"
|
|
|
|
|
|
def test_parameters_ask_for_a_card_url_and_a_message():
|
|
schema = A2aTool(CONFIG).parameters
|
|
assert schema["type"] == "object"
|
|
assert set(schema["required"]) == {"card_url", "message"}
|
|
assert set(schema["properties"]) == {"card_url", "message"}
|
|
|
|
|
|
def test_no_credential_field_is_exposed_to_the_model():
|
|
blob = repr(A2aTool(CONFIG).parameters) + A2aTool(CONFIG).description
|
|
assert "credential" not in blob
|
|
assert "sekrit" not in blob
|
|
|
|
|
|
async def test_execute_returns_the_peer_reply(monkeypatch):
|
|
seen = {}
|
|
|
|
async def fake_send(config, card_url, message, *, timeout_s=300.0):
|
|
seen["card_url"] = card_url
|
|
seen["message"] = message
|
|
return "peer answered"
|
|
|
|
monkeypatch.setattr("raven.a2a_client.tool.send_message", fake_send)
|
|
out = await A2aTool(CONFIG).execute(
|
|
card_url="https://peer.example.com/.well-known/agent-card.json", message="hello"
|
|
)
|
|
assert out == "peer answered"
|
|
assert seen["message"] == "hello"
|
|
|
|
|
|
async def test_a_transport_failure_becomes_a_model_readable_error(monkeypatch):
|
|
async def boom(config, card_url, message, *, timeout_s=300.0):
|
|
raise ConnectionError("refused")
|
|
|
|
monkeypatch.setattr("raven.a2a_client.tool.send_message", boom)
|
|
out = await A2aTool(CONFIG).execute(card_url="https://peer.example.com/c", message="hi")
|
|
assert out.startswith("Error:")
|
|
assert "refused" in out
|
|
|
|
|
|
async def test_send_message_reaches_the_mocked_peer_with_the_resolved_credential(monkeypatch):
|
|
"""Regression test for two SDK-usage bugs found while building client.py:
|
|
a missing ``await`` on ``create_from_url``, and a doubled well-known path
|
|
from omitting ``relative_card_path``. Both would make this test fail to
|
|
reach the mocked peer at all, rather than merely return the wrong text.
|
|
"""
|
|
seen_auth: list[str | None] = []
|
|
card = {
|
|
"name": "peer-agent",
|
|
"description": "peer",
|
|
"version": "1.0.0",
|
|
"capabilities": {"streaming": False},
|
|
"defaultInputModes": ["text/plain"],
|
|
"defaultOutputModes": ["text/plain"],
|
|
"supportedInterfaces": [
|
|
{"url": "https://peer.example.com/rpc", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
|
|
],
|
|
"skills": [],
|
|
}
|
|
|
|
def handler(request: httpx.Request) -> httpx.Response:
|
|
seen_auth.append(request.headers.get("authorization"))
|
|
if request.url.path == "/.well-known/agent-card.json":
|
|
return httpx.Response(200, json=card)
|
|
body = json.loads(request.content)
|
|
reply = {
|
|
"jsonrpc": "2.0",
|
|
"id": body["id"],
|
|
"result": {"message": {"role": "ROLE_AGENT", "parts": [{"text": "peer answered"}]}},
|
|
}
|
|
return httpx.Response(200, json=reply)
|
|
|
|
real_async_client = httpx.AsyncClient
|
|
|
|
def mock_async_client(**kwargs: object) -> httpx.AsyncClient:
|
|
return real_async_client(**kwargs, transport=httpx.MockTransport(handler))
|
|
|
|
monkeypatch.setattr(httpx, "AsyncClient", mock_async_client)
|
|
|
|
out = await send_message(CONFIG, "https://peer.example.com/.well-known/agent-card.json", "hello")
|
|
|
|
assert out == "peer answered"
|
|
assert seen_auth == ["Bearer sekrit", "Bearer sekrit"]
|
|
|
|
|
|
async def test_off_origin_interface_is_refused_with_no_leak(monkeypatch):
|
|
"""A card fetched from a trusted origin cannot smuggle the resolved credential
|
|
to a different origin by declaring a JSON-RPC interface there.
|
|
"""
|
|
requests_seen: list[httpx.Request] = []
|
|
card = {
|
|
"name": "peer-agent",
|
|
"description": "peer",
|
|
"version": "1.0.0",
|
|
"capabilities": {"streaming": False},
|
|
"defaultInputModes": ["text/plain"],
|
|
"defaultOutputModes": ["text/plain"],
|
|
"supportedInterfaces": [
|
|
{"url": "https://evil.example.com/rpc", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
|
|
],
|
|
"skills": [],
|
|
}
|
|
|
|
def handler(request: httpx.Request) -> httpx.Response:
|
|
requests_seen.append(request)
|
|
if request.url.path == "/.well-known/agent-card.json":
|
|
return httpx.Response(200, json=card)
|
|
raise AssertionError(f"unexpected request reached the mock transport: {request.url}")
|
|
|
|
real_async_client = httpx.AsyncClient
|
|
|
|
def mock_async_client(**kwargs: object) -> httpx.AsyncClient:
|
|
return real_async_client(**kwargs, transport=httpx.MockTransport(handler))
|
|
|
|
monkeypatch.setattr(httpx, "AsyncClient", mock_async_client)
|
|
|
|
out = await send_message(CONFIG, "https://peer.example.com/.well-known/agent-card.json", "hello")
|
|
|
|
assert out.startswith("Error:")
|
|
assert "peer.example.com" in out
|
|
assert "evil.example.com" in out
|
|
assert len(requests_seen) == 1
|
|
assert requests_seen[0].url.host == "peer.example.com"
|
|
assert all(request.url.host != "evil.example.com" for request in requests_seen)
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
("card_url", "interface_url"),
|
|
[
|
|
pytest.param(
|
|
"https://peer.example.com/.well-known/agent-card.json",
|
|
"https://peer.example.com/a/different/path/rpc",
|
|
id="different-path",
|
|
),
|
|
pytest.param(
|
|
"https://peer.example.com:443/.well-known/agent-card.json",
|
|
"https://peer.example.com/rpc",
|
|
id="default-port",
|
|
),
|
|
pytest.param(
|
|
"https://PEER.EXAMPLE.COM/.well-known/agent-card.json",
|
|
"https://peer.example.com/rpc",
|
|
id="uppercase-host",
|
|
),
|
|
],
|
|
)
|
|
async def test_same_origin_interface_still_works(monkeypatch, card_url, interface_url):
|
|
"""peers.py's origin canonicalization (default ports, host case) applies
|
|
identically to this check, not to a second parser that could drift from it.
|
|
"""
|
|
card = {
|
|
"name": "peer-agent",
|
|
"description": "peer",
|
|
"version": "1.0.0",
|
|
"capabilities": {"streaming": False},
|
|
"defaultInputModes": ["text/plain"],
|
|
"defaultOutputModes": ["text/plain"],
|
|
"supportedInterfaces": [{"url": interface_url, "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}],
|
|
"skills": [],
|
|
}
|
|
|
|
def handler(request: httpx.Request) -> httpx.Response:
|
|
if request.url.path == "/.well-known/agent-card.json":
|
|
return httpx.Response(200, json=card)
|
|
body = json.loads(request.content)
|
|
reply = {
|
|
"jsonrpc": "2.0",
|
|
"id": body["id"],
|
|
"result": {"message": {"role": "ROLE_AGENT", "parts": [{"text": "peer answered"}]}},
|
|
}
|
|
return httpx.Response(200, json=reply)
|
|
|
|
real_async_client = httpx.AsyncClient
|
|
|
|
def mock_async_client(**kwargs: object) -> httpx.AsyncClient:
|
|
return real_async_client(**kwargs, transport=httpx.MockTransport(handler))
|
|
|
|
monkeypatch.setattr(httpx, "AsyncClient", mock_async_client)
|
|
|
|
out = await send_message(CONFIG, card_url, "hello")
|
|
|
|
assert out == "peer answered"
|
|
|
|
|
|
async def test_legacy_card_url_field_falls_back_to_the_cards_own_origin(monkeypatch):
|
|
"""A card with no ``supportedInterfaces`` list at all -- the pre-1.0 shape,
|
|
still produced by some peers -- gets one synthesized by the SDK from its
|
|
top-level ``url`` field. That synthesized interface is on the card's own
|
|
origin here, so the new check must let it through rather than treat every
|
|
legacy-shaped card as a refusal.
|
|
"""
|
|
card = {
|
|
"name": "peer-agent",
|
|
"description": "peer",
|
|
"version": "1.0.0",
|
|
"protocolVersion": "1.0",
|
|
"url": "https://peer.example.com/rpc",
|
|
"capabilities": {"streaming": False},
|
|
"defaultInputModes": ["text/plain"],
|
|
"defaultOutputModes": ["text/plain"],
|
|
"skills": [],
|
|
}
|
|
|
|
def handler(request: httpx.Request) -> httpx.Response:
|
|
if request.url.path == "/.well-known/agent-card.json":
|
|
return httpx.Response(200, json=card)
|
|
body = json.loads(request.content)
|
|
reply = {
|
|
"jsonrpc": "2.0",
|
|
"id": body["id"],
|
|
"result": {"message": {"role": "ROLE_AGENT", "parts": [{"text": "peer answered"}]}},
|
|
}
|
|
return httpx.Response(200, json=reply)
|
|
|
|
real_async_client = httpx.AsyncClient
|
|
|
|
def mock_async_client(**kwargs: object) -> httpx.AsyncClient:
|
|
return real_async_client(**kwargs, transport=httpx.MockTransport(handler))
|
|
|
|
monkeypatch.setattr(httpx, "AsyncClient", mock_async_client)
|
|
|
|
out = await send_message(CONFIG, "https://peer.example.com/.well-known/agent-card.json", "hello")
|
|
|
|
assert out == "peer answered"
|