Raven-1/tests/test_a2a_client_tool.py
Dizhan Xue 7faa2060e2
feat(*): raven speaks Agent2Agent 1.0, inbound and outbound (#446)
## 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>
2026-09-20 14:58:15 +08:00

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"