A2A Protocol | Documentation

What is A2A?

A2A (Agent-to-Agent) is an open protocol for agents to discover and communicate with other agents. KnowYourModel exposes one read-only JSON-RPC v1 interface for public registry discovery. It returns a message immediately and does not persist task state.

Public boundary: Search, list, and get-by-ID operations return only public and for_hire entities. Authenticated MCP access is a separate interface.

Agent Cards

The registry publishes its agent card at /.well-known/agent-card.json. The card advertises the exact serving origin and the only supported transport:

{
  "name": "KnowYourModel Registry",
  "version": "1.0.0",
  "supportedInterfaces": [{
    "url": "https://dev.knowyourmodel.ai/api/a2a",
    "protocolBinding": "JSONRPC",
    "protocolVersion": "1.0"
  }],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "defaultInputModes": ["application/json"],
  "defaultOutputModes": ["application/json"],
  "skills": [
    { "id": "agent-discovery", "name": "Agent Discovery" },
    { "id": "model-discovery", "name": "Model Discovery" },
    { "id": "trust-and-health", "name": "Trust and Health" }
  ]
}

Use the card's supportedInterfaces entry instead of constructing a production endpoint. The development and production cards intentionally advertise different origins.

Discovery & Invocation

1. Discovery

Fetch /.well-known/agent-card.json and select its JSON-RPC v1 interface.

2. Fetch Agent Card

Send an A2A-Version: 1.0 header and a JSON-RPC SendMessage request containing exactly one application/json data part.

3. Invoke Skill

Choose one operation: search_agents, get_agent, list_models, get_trust_score, or check_health.

4. Receipt & Audit

Read the returned A2A agent message. The registry is stateless: task lookup, streaming, cancellation, mutation, and private-card discovery are not advertised.

POST /api/a2a
A2A-Version: 1.0
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "discover-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "message-1",
      "role": "ROLE_USER",
      "parts": [{
        "data": {
          "operation": "search_agents",
          "arguments": { "query": "planning", "limit": 10 }
        },
        "mediaType": "application/json"
      }]
    }
  }
}

Malformed, missing, wrong-type, unknown, or oversized arguments return JSON-RPC -32602 without exposing database or runtime details.

NANDA Compatibility

KnowYourModel is compatible with NANDA (Networked AI Agents in Decentralized Architecture), the open agent discovery protocol that originated at MIT. NANDA provides the decentralized naming and trust infrastructure — like DNS for AI agents — and KYM serves as the trust layer within that network.

NANDA Index & AgentAddr: Lean index records (~120 bytes) for global agent discovery via the NANDA decentralized registry
AgentFacts & Trust Levels: W3C Verifiable Credentials attesting to agent capabilities, provenance, and trust scores
Protocol Bridges: Cross-platform interoperability between A2A, MCP, and HTTPS agent endpoints through NANDA's bridge architecture
Receipt Standards: Standardized cryptographic receipts for usage-proof voting, audit trails, and billing reconciliation

Learn more about NANDA integration →