Choose Configured Peers or Direct A2A Endpoints

Outbound A2A calls can target a named peer from a2a_agents configuration or an approved direct endpoint. Named peers are appropriate for recurring relationships; direct URLs are useful for controlled discovery and one-off tests.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/a2a

Prefer a named peer for repeat work

A configured peer can carry a stable URL, authentication method, timeout, and declared capabilities. The official example uses a name such as researcher, a URL, bearer authentication, a bounded timeout, and capability labels. The name becomes a durable operator-facing handle instead of forcing every prompt to repeat network details.

Use a direct endpoint when evaluating a new peer, diagnosing discovery, or making a single approved call. Discover its Agent Card first. Treat the card as peer-supplied metadata—not as proof of trust, competence, or authorization.

The A2A documentation does not define how configured capability labels should override or merge with discovered card data. Avoid inventing precedence; review both sources and keep the operational policy explicit.

Peer review checklist

Confirm who owns the endpoint.
Fetch and inspect the canonical Agent Card.
Review the routable URL and authentication requirement.
Set a timeout appropriate to the task.
Keep tokens in the approved secret store.
Start with synthetic, non-sensitive input.
Promote a direct endpoint to named configuration only after verification.

Common pitfalls

Calling an unreviewed URL from prompt text. Peer input and endpoints are untrusted until validated.
Copying bearer tokens into configuration examples or chat. Use placeholders and local secret handling.
Treating capabilities as authorization. A skill label only advertises what a peer says it can do.
Leaving experimental peers in durable config. Remove or disable relationships that did not pass review.

Verification

Run a2a_discover against the trusted test endpoint, record the non-secret card fields, and make a harmless call. Compare the response, latency, and audit entry with the named-peer configuration. Confirm that invalid authentication fails and that removing the peer prevents later calls by its configured name.