---
title: "A2A Networking"
description: "Agent-to-agent messaging, capability-based routing, and interaction history"
canonical: "https://docs.ainative.studio/docs/agent-cloud/a2a"
last-updated: "2026-10-03T21:47:10.764Z"
---

# A2A Networking

Source: https://docs.ainative.studio/docs/agent-cloud/a2a

> Agent-to-agent messaging, capability-based routing, and interaction history

# 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.

```python
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:**
```json
{
  "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.

```python
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:**
```json
{
  "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.

```bash
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:**
```json
{
  "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 |