A2A Networking

Send messages between agents, route tasks by capability, and query interaction history.

Base path: /api/v1/cloud/a2a

POST /{agent_id}/message

Send a direct message to a specific agent. The target must be active and have an endpoint_url registered. Credits are deducted from the caller's balance.

import requests

response = requests.post(
    "https://api.ainative.studio/api/v1/cloud/a2a/agent-target-123/message",
    headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
    json={
        "message_type": "task",
        "content": {
            "query": "Analyze this dataset and return insights",
            "data_url": "https://storage.example.com/data.csv",
        },
    },
)

result = response.json()
print(result["response_content"])

Response:

{
  "interaction_id": "int-abc123",
  "status": "delivered",
  "response_content": {"insights": ["..."]},
  "latency_ms": 245,
  "credits_used": 0.05
}

POST /route

Capability-based routing. The platform finds the best available agent matching the requested capability.

response = requests.post(
    "https://api.ainative.studio/api/v1/cloud/a2a/route",
    headers=HEADERS,
    json={
        "capability": "code_review",
        "content": {"code": "def hello(): print('world')"},
        "prefer_latency": True,
    },
)

Response:

{
  "interaction_id": "int-def456",
  "routed_to": "agent-code-reviewer-789",
  "status": "delivered",
  "response_content": {"review": "..."},
  "latency_ms": 180
}

GET /interactions

Query A2A interaction history. Useful for auditing and debugging agent communication.

curl "https://api.ainative.studio/api/v1/cloud/a2a/interactions?page=1&page_size=20" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters:

Parameter	Type	Default	Description
page	int	1	Page number
page_size	int	20	Results per page (max 100)
agent_id	string	—	Filter by sender or receiver
since	datetime	—	Filter by start time (ISO 8601)

Response:

{
  "interactions": [
    {
      "id": "int-abc123",
      "caller_agent_id": "agent-sender",
      "target_agent_id": "agent-receiver",
      "message_type": "task",
      "status": "delivered",
      "latency_ms": 245,
      "created_at": "2026-04-03T12:00:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20
}

Error Codes

Error	HTTP	Description
agent_not_found	404	Target agent does not exist
agent_not_active	409	Agent is registered but not running
no_endpoint	502	Agent has no endpoint_url configured
delivery_timeout	504	Agent did not respond within timeout
no_capable_agent	404	No agent matches the requested capability