Verify and Troubleshoot Hermes A2A End to End

A2A failures are easiest to solve as a layered path: discover the Agent Card, prove network reachability, authenticate, send valid JSON-RPC, observe task state, and only then debug the local Hermes agent. Changing several layers at once can hide the actual fault.

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

Use the canonical v1.0 path first

Fetch GET /.well-known/agent-card.json. Confirm the advertised URL is reachable from the caller's network and that its auth requirements match the configured peer. The legacy agent.json route exists for compatibility, but new verification should use the canonical card.

Send a synthetic SendMessage request to POST / with JSON-RPC 2.0 framing. Check the HTTP response and the JSON-RPC result or error separately. A 401 Unauthorized points to token configuration; a card that advertises an unreachable host points to A2A_PUBLIC_URL or proxy routing; a long task that times out may require polling or push delivery rather than a longer synchronous reply timeout.

Hermes reports interoperability testing with the official Python A2A SDK for card resolution, SendMessage, and streaming. Do not turn that into a claim that every method has been certified against every framework.

Diagnostic checklist

• Fetch the canonical Agent Card.
• Verify the advertised URL from the real peer network.
• Test a valid token and an invalid token that should receive 401 Unauthorized.
• When an allowlist is configured, verify a valid-but-untrusted identity receives the expected authorization rejection.
• Send one minimal canonical SendMessage request.
• Inspect JSON-RPC errors before local agent logs.
• Test streaming with a current compliant client where required.
• Review gateway and A2A audit records without exposing secrets.

Common pitfalls

• Testing only from localhost. Proxy and advertised-URL failures appear only from the peer side.
• Using legacy aliases as the primary example. Start with the v1.0 contract.
• Raising timeouts before checking task state. Longer waiting can hide a lifecycle-design issue.
• Retrying with broader access. Authentication or routing failures should not be “fixed” by allowing everyone.

Verification

Build a small matrix covering card retrieval, valid call, invalid token, untrusted peer, streaming, and a bounded long task. Record HTTP status, JSON-RPC outcome, task identifier, and terminal state. The release gate is a successful harmless request plus expected rejection behavior—not merely an open port.