← All documentation

A2A peer examples

These configurations require your own running A2A 0.3.0 JSON-RPC peer. Adjust the endpoint and expected health skill ID to match its agent card. They do not start a server. Run the commands from the repository root with AgentHealth v0.3.0 or newer.

Passive discovery

The standard card location is /.well-known/agent-card.json at the configured origin. The card's url must point to a JSON-RPC endpoint on that same origin. Authentication/protocol checks use read-only tasks/get lookups with fresh IDs; a valid task-not-found response passes without creating a task.

agenthealth ping a2a http://localhost:9000
agenthealth doctor a2a http://localhost:9000
agenthealth check examples/a2a-check/agenthealth.yaml --format json
agenthealth doctor examples/a2a-check/agenthealth.yaml
agenthealth check examples/a2a-check/custom-card.yaml --format yaml

The custom-card example expects /metadata/agent-card.json. Change both URLs when moving to a different origin. A missing required health skill yields DEGRADED and exit code 1. The capability check inspects metadata; it does not execute that skill. See capability expectations for optional boolean capability requirements.

Bearer credentials

Set AGENT_TOKEN in the process environment before running the bearer example; keep the credential value out of configuration files. Replace its HTTPS endpoint with the origin of your authenticated peer. Missing/empty references fail configuration before networking; HTTP 401/403 yields MISCONFIGURED and exit code 4. These checks validate acceptance for the passive lookup.

agenthealth check examples/a2a-check/bearer.yaml --format json

Minimal interaction

Use the functional example with a peer supporting default text/plain input and output. Confirm its prompt is non-destructive for your agent before using safe: true; the declaration is an operator assertion. The probe sends one blocking message/send request and never retries it. Add the same auth block as the bearer example if your peer requires a token.

agenthealth check examples/a2a-check/functional.yaml --format json

Valid agent text replies or completed tasks pass. Failed/rejected/canceled tasks are UNHEALTHY (exit 2); pending tasks and input requirements are UNKNOWN (exit 5). The adapter does not poll, continue, or automatically cancel tasks, and does not expose the reply body. A successful interaction validates completion, not answer semantics. See the adapter guide for the full supported scope, limits, and classifications.

For a current v1 peer, use the v1 configuration. Legacy examples explicitly select 0.3.0. Unconfigured ping/doctor now select v1.

Phase 10 compatibility

This nested example remains valid. To share a backend across paths, give that node an explicit id and use ref edges. Each communication path keeps a distinct node and its own checks; edge policy remains independent. See the graph example. Graph fields require v0.8.0 or newer; v0.7.0 binaries reject them.

version: v1
targets:
  - name: peer
    type: a2a
    endpoint: http://localhost:9000
    a2a:
      protocol_version: '0.3.0'
      required_skills: [health]
    thresholds:
      latency_ms: 1000

version: v1
targets:
  - name: authenticated-peer
    type: a2a
    endpoint: https://agent.example.com
    auth:
      bearer_env: AGENT_TOKEN
    a2a:
      protocol_version: '0.3.0'
      required_skills: [health]
    thresholds:
      latency_ms: 1000

version: v1
targets:
  - name: peer-with-custom-card
    type: a2a
    endpoint: http://localhost:9000
    a2a:
      card_url: http://localhost:9000/metadata/agent-card.json
      protocol_version: '0.3.0'
      required_skills: [health]

version: v1
targets:
  - name: peer-interaction
    type: a2a
    endpoint: http://localhost:9000
    checks: [reachability, protocol, authentication, capability, functional, latency]
    a2a:
      protocol_version: '0.3.0'
      required_skills: [health]
      functional:
        safe: true
        text: 'Report your readiness as text without invoking tools or making external changes.'
    thresholds:
      latency_ms: 1000

version: v1
targets:
  - name: current-peer
    type: a2a
    endpoint: https://agent.example.com
    a2a:
      protocol_version: '1.0'
      required_skills: [health]
    thresholds:
      latency_ms: 1000