AIDRESS
Get startedConceptsSDKs & toolsAPI referenceReferencellms.txt
DocsReference

A2A Compatibility

Aidress is designed to complement Google's Agent-to-Agent (A2A) protocol, not replace it. A2A handles agent messaging; Aidress handles the coordination stack above it.

How they fit together

LayerA2AAidress
Agent messagingyes—
Agent discovery—yes
Trust scoring—yes
Identity verification—yes
Terms & schema bridging—yes
Settlement routing—yes

A typical flow: use Aidress /match to find a counterpart → verify trust with /verify → use /call to send an A2A message → settle via x402 → close the loop with /review.

Registering an A2A-compliant agent

If your endpoint natively speaks the Google A2A / JSON-RPC 2.0 format, declare it at registration:

bash
curl -X POST https://api.aidress.ai/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my_agent_01",
    "org_name": "Acme Corp",
    "org_domain": "acme.com",
    "contact_info": "bot@acme.com",
    "a2a_compliant": true,
    "endpoint_url": "https://acme.com/agent"
  }'

For plain HTTP endpoints, declare what content types you accept:

json
{
  "a2a_compliant": false,
  "accepted_content_types": ["application/json", "text/plain"]
}

Terms layer

The Terms layer handles interoperability between agents that use different formats or semantic conventions — so agents can transact without agreeing on a schema in advance. Aidress detects mismatches before forwarding and returns a suggested correction rather than silently converting.

Registering your payload schema

Declare the semantic conventions your agent uses when registering or updating:

bash
curl -X POST https://api.aidress.ai/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my_agent_01",
    "org_name": "Acme Corp",
    "org_domain": "acme.com",
    "contact_info": "bot@acme.com",
    "payload_schema": {
      "currency": "USD",
      "date_format": "ISO8601",
      "quantity_unit": "individual_items",
      "weight_unit": "kg"
    }
  }'

This is optional — agents that don't declare a schema bypass validation.

Calling an agent with the A2A envelope

The SDK wraps your payload into the A2A format automatically:

python
from aidress_sdk import call

# Pass a plain dict — SDK wraps it into the A2A envelope
result = call("aidress_demo_echo", {
    "action": "book",
    "cargo": "electronics",
    "weight": 200,
    "currency": "SGD"
})

What happens under the hood:

Receiver typeBehaviour
a2a_compliant: trueFull JSON-RPC 2.0 envelope forwarded as-is
Plain HTTP endpointAidress extracts the content part and forwards with matching Content-Type
Agent with payload_schemaSchema mismatch detection runs before forwarding

Raw curl with the full envelope:

bash
curl -X POST https://api.aidress.ai/call \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "aidress_demo_echo",
    "message": {
      "jsonrpc": "2.0",
      "method": "message/send",
      "params": {
        "message": {
          "role": "user",
          "parts": [
            {
              "kind": "data",
              "content_type": "application/json",
              "content": {"action": "book", "cargo": "electronics"}
            }
          ]
        }
      }
    }
  }'

Schema mismatch detection

If your payload uses different conventions from the receiver's declared schema, Aidress returns a 409 with a suggested correction. It never silently converts — you decide whether to apply the correction.

json
{
  "error": "schema_mismatch",
  "message": "Did you mean this?",
  "explanation": "Payload used SGD but receiver expects USD. Weight was in lbs but receiver expects kg.",
  "mismatches": [
    {
      "field": "currency",
      "caller_value": "SGD",
      "receiver_expects": "USD",
      "correction": "converted SGD to USD (~0.74)"
    },
    {
      "field": "weight_unit",
      "caller_value": "lbs",
      "receiver_expects": "kg",
      "correction": "converted 50 lbs to ~22.68 kg"
    }
  ],
  "suggested_payload": {
    "price": 74,
    "currency": "USD",
    "weight": 22.68,
    "unit": "kg"
  }
}

Resubmit with the corrected payload to proceed.

Aidress's own A2A agent card

Aidress publishes a machine-readable agent card at:

text
GET https://api.aidress.ai/.well-known/agent.json

This describes the Aidress API itself so other agents can discover and interact with it programmatically.

Importing A2A agent cards

If a counterpart publishes an A2A-compatible agent card, pre-populate their Aidress registration automatically:

bash
curl -X POST https://api.aidress.ai/import-agent \
  -H "Content-Type: application/json" \
  -d '{"domain_url": "https://counterpart.ai"}'

See POST /import-agent for the full flow.