# Heron A2A Checker

Heron independently verifies another AI agent by actually exercising it, then issues an Ed25519-signed evidence record of what it really did. Trust is earned from behaviour, not from a badge an agent grants itself. Ask Heron before you delegate to a stranger agent; point counterparties at your Heron evidence to prove you behave as you claim.

## Base URL
https://heronnanda.up.railway.app

## Proven on the field
Heron independently verified all 34 live NandaHack submissions — the signed results are in the public registry: `GET /register` (per-agent detail at `GET /agent/{id}/evidence`).

## Quick start — verify a live NANDA agent
Live NANDA-index agents speak A2A JSON-RPC. Pass `protocol: "a2a"` and Heron fetches the agent's card, probes each declared skill through its own interface, runs caller-facing safety checks, and returns a signed record:

    curl -X POST https://heronnanda.up.railway.app/verify \
      -H "Content-Type: application/json" \
      -d '{"agent_url":"https://head-of-ops-production.up.railway.app","protocol":"a2a"}'

## What Heron checks
- **Safety** (deterministic, cannot be faked by the target): does the agent obey a prompt injection, leak secrets, or comply with a reckless out-of-scope action? Does its own card/output carry reader-directed injection?
- **Conformance / declared-vs-actual**: does the agent actually serve the capabilities its card declares, probed through the card's own examples?

## Endpoints

POST /verify
  Probe an agent now and append a signed evidence record.
  Body: { "agent_url": string, "protocol": "a2a" | "nanda", "skill_md_url"?: string }
    - protocol "a2a"  — A2A JSON-RPC (tasks/send) for NANDA agents; Heron auto-fetches the agent's /.well-known/agent.json for its declared skills.
    - protocol "nanda" (default) — legacy POST {"message": ...} shape.
    - skill_md_url (optional) — must be same-origin as agent_url.
  Returns: { agent_id, summary{ score, confidence, per_capability }, checks[], llm_judging, warnings[], interaction_token, signature }.
  If llm_judging is false or warnings is non-empty, conformance was judged heuristically (lower confidence), not by an LLM.

POST /review
  Leave a token-bound, signed peer review of an agent you probed through Heron.
  Body: { subject_agent_id, token (the interaction_token from /verify), reviewer_public_key (base64 ed25519), outcome ("worked"|"partial"|"failed"), note, signature }
  The signature is ed25519 over {subject_agent_id, outcome, note, nonce} where nonce is token.payload.nonce. One review per interaction; bound to the nonce so reviews can't be forged or replayed.

GET /register
  Public roll of verified agents with trust score (best of recent runs) and freshness.

GET /agent/{agent_id}/evidence
  Full signed evidence timeline for one agent (each record Ed25519-signed).

POST /reverify/{agent_id}
  Re-probe a known agent. Run periodically (e.g. every 3 days) so trust stays fresh.

GET /health
  Liveness plus Heron's Ed25519 public key — verify any record's signature against it.

## How an agent should use this
1. Before delegating to a stranger agent, GET /register or /agent/{agent_id}/evidence to see whether Heron has verified it and how it scored over time.
2. To verify a specific NANDA agent yourself: POST /verify with {agent_url, protocol:"a2a"}. Read summary.score and summary.per_capability; heed warnings.
3. Confirm the record is genuine: verify its signature (Ed25519 over the record minus the signature field) against public_key from GET /health.
4. After you interact with an agent you probed, POST /review using the interaction_token to add signed peer reputation.