A2A Protocol (Agent-to-Agent)

Sertone supports Google's A2A protocol natively. Every service in the catalog auto-generates an agent card. AI agents discover and call any service programmatically — payment settles automatically in USDC.

Overview

A2A (Agent-to-Agent) is an open protocol by Google that lets AI agents communicate with each other in a standard way. An agent advertises what it can do via an agent card — a JSON document describing its capabilities, endpoints, and pricing. Other agents discover this card and call the agent using JSON-RPC 2.0.

On Sertone, every registered service automatically gets an A2A agent card. No extra setup is required. The card is generated from the service's catalog metadata and is always in sync.

What Sertone adds on top of the base A2A spec:

• Automatic USDC payment — each call is billed and paid automatically, transparently
• Discovery search — find agents by capability, price, or keyword across the entire catalog
• Quality metadata — uptime, success rate, and average latency exposed in the agent card

Discovery

Three endpoints let agents find services programmatically:

Discovery query parameters

Agent Card Format

Each agent card follows the A2A specification with Sertone-specific extensions in the x_sertone field:

{
  "schema_version": "1.0",
  "name": "Earthquake Data API",
  "description": "Real-time global earthquake data from USGS. Filter by magnitude, region, and time range.",
  "url": "https://<node-address>:3000/a2a/message",
  "version": "1.0.0",
  "capabilities": {
    "streaming": false,
    "push_notifications": false,
    "state_transition_history": false
  },
  "authentication": {
    "schemes": ["bearer"],
    "credentials": "X-Consumer-Secret header"
  },
  "skills": [
    {
      "id": "query_earthquakes",
      "name": "Query Earthquakes",
      "description": "Fetch recent earthquake events filtered by magnitude and region",
      "input_modes": ["application/json"],
      "output_modes": ["application/json"],
      "tags": ["earthquake", "seismic", "usgs", "geo"]
    }
  ],
  "x_sertone": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "price_usdc": "0.001",
    "settlement": "on-chain USDC, Base",
    "quality": {
      "uptime_pct": 99.7,
      "success_rate_pct": 98.2,
      "avg_latency_ms": 320
    }
  }
}

Calling Services (JSON-RPC 2.0)

Send a POST request to /a2a/message with a JSON-RPC 2.0 payload:

Request format

{
  "jsonrpc": "2.0",
  "method": "message/send",
  "params": {
    "api_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": "{\"path\":\"/v1/earthquakes/recent\",\"method\":\"GET\",\"params\":{\"minMagnitude\":4.5}}"
  },
  "id": 1
}

Response format

{
  "jsonrpc": "2.0",
  "result": {
    "task_id": "tsk_9f3a2b1c",
    "status": "completed",
    "output": {
      "status": 200,
      "data": { ... }
    }
  },
  "id": 1
}

Code Examples

Python

import requests

# Discover earthquake services
agents = requests.get(
    'https://<node-address>:3000/a2a/discover',
    params={'capability': 'earthquake', 'limit': 3},
    verify=False
).json()

# Call via A2A
response = requests.post(
    'https://<node-address>:3000/a2a/message',
    headers={'X-Consumer-Secret': 'YOUR_SECRET'},
    json={
        'jsonrpc': '2.0',
        'method': 'message/send',
        'params': {
            'api_uuid': agents['agents'][0]['x_sertone']['uuid'],
            'content': '{"path":"/v1/earthquakes/recent","method":"GET"}'
        },
        'id': 1
    },
    verify=False
).json()

print(response['result']['output']['data'])

JavaScript

// Discover earthquake services
const agents = await fetch(
  'https://<node-address>:3000/a2a/discover?capability=earthquake'
).then(r => r.json());

// Call via A2A
const result = await fetch('https://<node-address>:3000/a2a/message', {
  method: 'POST',
  headers: {
    'X-Consumer-Secret': 'YOUR_SECRET',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'message/send',
    params: {
      api_uuid: agents.agents[0].x_sertone.uuid,
      content: '{"path":"/v1/earthquakes/recent","method":"GET"}'
    },
    id: 1
  })
}).then(r => r.json());

console.log(result.result.output.data);

Registering an External A2A Agent

You can register an external A2A-compatible agent in the Sertone catalog so other participants can discover and call it through the network:

1. Get the agent card URL from the external agent (e.g. https://example.com/.well-known/agent-card.json)
2. Go to the web console and click Register
3. Select A2A Agent as the service type
4. Paste the agent card URL
5. Sertone fetches and parses the card automatically
6. The agent appears in the catalog and is discoverable by other participants

Once registered, the external agent is callable through the standard A2A message endpoint on your node, with Sertone handling authentication and USDC billing.

A2A vs MCP

Sertone supports both A2A and MCP (Model Context Protocol). They serve different purposes and complement each other:

Use MCP when you want an LLM (like Claude or GPT) to use Sertone services as tools. Use A2A when building multi-agent systems where autonomous agents need to find and call each other. Both work on Sertone simultaneously with no extra configuration.