> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evo-ai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# A2A Protocol API Reference

> Complete API documentation for the Agent-to-Agent (A2A) Protocol implementation

## Overview

The **Agent-to-Agent (A2A) Protocol** API provides standardized communication between AI agents using JSON-RPC 2.0 over HTTP/HTTPS. This reference covers all available endpoints, methods, and implementation details for integrating with A2A-compatible agents.

<Note>
  **Official Protocol**: Based on Google's A2A specification available at [google.github.io/A2A](https://google.github.io/A2A/specification/).
  All endpoints follow JSON-RPC 2.0 standards for maximum interoperability.
</Note>

## Base URL Structure

All A2A endpoints follow this URL pattern:

```
POST {base_url}/api/v1/a2a/{agent_id}
```

Where:

* `{base_url}` is your Evo AI server URL (e.g., `http://localhost:8000`)
* `{agent_id}` is the unique identifier of the target agent

## Authentication

<Card title="API Key Authentication" icon="key">
  **Header:** `x-api-key`

  Standard API key authentication for secure agent access.

  ```http theme={null}
  x-api-key: your-api-key-here
  ```
</Card>

## Core Methods

The A2A Protocol supports the following core methods:

| Method                             | Purpose                   | Type               |
| ---------------------------------- | ------------------------- | ------------------ |
| `message/send`                     | Send synchronous messages | HTTP Request       |
| `message/stream`                   | Send streaming messages   | Server-Sent Events |
| `tasks/get`                        | Get task status           | HTTP Request       |
| `tasks/cancel`                     | Cancel running task       | HTTP Request       |
| `tasks/pushNotificationConfig/set` | Configure webhooks        | HTTP Request       |
| `tasks/pushNotificationConfig/get` | Get webhook config        | HTTP Request       |
| `tasks/resubscribe`                | Resubscribe to task       | HTTP Request       |
| `agent/authenticatedExtendedCard`  | Get agent metadata        | HTTP Request       |

## Request Structure

All A2A requests follow the JSON-RPC 2.0 format:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method-name",
  "params": {
    // Method-specific parameters
  }
}
```

### Required Fields

<AccordionGroup>
  <Accordion icon="code" title="Standard JSON-RPC Fields">
    * **jsonrpc**: Always `"2.0"` (string)
    * **id**: Unique request identifier (string/number)
    * **method**: A2A method name (string)
    * **params**: Method parameters (object)
  </Accordion>

  <Accordion icon="fingerprint" title="A2A-Specific IDs">
    * **messageId**: UUID v4 for message identification (required in message params)
    * **taskId**: Task identifier for task operations (optional/required based on method)
    * **sessionId**: Session identifier for multi-turn conversations (optional)
  </Accordion>
</AccordionGroup>

## Response Structure

A2A responses follow JSON-RPC 2.0 success/error patterns:

### Success Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-id",
    "status": {
      "state": "completed|working|failed|canceled",
      "message": {
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "Response content"
          }
        ]
      }
    },
    "contextId": "context-for-multi-turn",
    "final": true
  },
  "id": "request-id"
}
```

### Error Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Error description",
    "data": {
      "details": "Additional error information"
    }
  },
  "id": "request-id"
}
```

## Task Lifecycle States

<CardGroup cols={4}>
  <Card title="submitted" icon="clock">
    Task received and queued for processing
  </Card>

  <Card title="working" icon="gear">
    Task is currently being processed
  </Card>

  <Card title="completed" icon="check">
    Task completed successfully
  </Card>

  <Card title="failed" icon="x">
    Task failed during processing
  </Card>
</CardGroup>

## Multi-turn Conversations

A2A supports multi-turn conversations using `contextId`:

1. **First message**: Send without `contextId`
2. **Response**: Server returns `contextId` in result
3. **Subsequent messages**: Include `contextId` in params
4. **Context preservation**: Server maintains conversation history

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-002",
  "method": "message/send",
  "params": {
    "contextId": "ctx-from-previous-response",
    "message": {
      "role": "user",
      "parts": [{"type": "text", "text": "Continue our conversation"}],
      "messageId": "uuid-here"
    }
  }
}
```

## File Upload Support

A2A supports file uploads via Base64 encoding in message parts:

```json theme={null}
{
  "type": "file",
  "file": {
    "name": "document.pdf",
    "mimeType": "application/pdf",
    "bytes": "base64-encoded-content-without-header"
  }
}
```

<Warning>
  **File Encoding**: Use Base64 encoding **without** the `data:mime/type;base64,` header.
  Only include the pure Base64 content in the `bytes` field.
</Warning>

## Streaming with Server-Sent Events

For `message/stream` method, responses are delivered via Server-Sent Events:

```http theme={null}
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

data: {"jsonrpc":"2.0","result":{"id":"task-123","status":{"state":"working"},"final":false},"id":"req-001"}

data: {"jsonrpc":"2.0","result":{"id":"task-123","status":{"state":"completed","message":{"role":"agent","parts":[{"type":"text","text":"Final response"}]}},"final":true},"id":"req-001"}
```

## Push Notifications (Webhooks)

Configure webhooks for asynchronous task notifications:

### Set Webhook Configuration

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "req-webhook",
  "method": "tasks/pushNotificationConfig/set",
  "params": {
    "config": {
      "url": "https://your-server.com/webhook/a2a",
      "headers": {
        "Authorization": "Bearer webhook-token"
      }
    }
  }
}
```

### Webhook Payload

Your webhook endpoint will receive:

```json theme={null}
{
  "taskId": "task-123",
  "status": {
    "state": "completed",
    "message": {
      "role": "agent",
      "parts": [{"type": "text", "text": "Task completed"}]
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
```

## Error Codes

| Code     | Description      | Resolution                          |
| -------- | ---------------- | ----------------------------------- |
| `-32700` | Parse error      | Check JSON syntax                   |
| `-32600` | Invalid request  | Verify JSON-RPC 2.0 format          |
| `-32601` | Method not found | Check method name spelling          |
| `-32602` | Invalid params   | Verify parameter structure          |
| `-32603` | Internal error   | Server-side issue, retry later      |
| `-32000` | Agent error      | Agent-specific error, check message |

## Rate Limiting

<AccordionGroup>
  <Accordion icon="gauge" title="Default Limits">
    * **HTTP Requests**: 100 requests per minute per API key
    * **Streaming**: 10 concurrent streams per API key
    * **File Upload**: 5MB maximum file size
    * **Message Size**: 1MB maximum message payload
  </Accordion>

  <Accordion icon="clock" title="Rate Limit Headers">
    ```http theme={null}
    X-RateLimit-Limit: 100
    X-RateLimit-Remaining: 95
    X-RateLimit-Reset: 1642234567
    ```
  </Accordion>
</AccordionGroup>

## Testing Your Integration

<Card title="Interactive A2A Lab" icon="flask" href="/a2a-protocol#testing">
  Use our interactive testing environment to experiment with A2A methods and see real-time responses.
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Message Endpoints" icon="message" href="/api-reference/endpoint/message-send">
    Learn about synchronous and streaming message methods
  </Card>

  <Card title="Task Management" icon="tasks" href="/api-reference/endpoint/task-operations">
    Explore task lifecycle and management operations
  </Card>

  <Card title="Agent Metadata" icon="user" href="/api-reference/endpoint/webhooks-agent-info">
    Get agent information and capabilities
  </Card>

  <Card title="Webhook Configuration" icon="webhook" href="/api-reference/endpoint/webhooks-agent-info">
    Set up push notifications for asynchronous updates
  </Card>
</CardGroup>

***

**Ready to integrate?** Start with the [message/send endpoint](/api-reference/endpoint/message-send) for basic agent communication.