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.

Official Protocol: Based on Google’s A2A specification available at google.github.io/A2A. All endpoints follow JSON-RPC 2.0 standards for maximum interoperability.

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

API Key Authentication

Header: x-api-key

Standard API key authentication for secure agent access.

x-api-key: your-api-key-here

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:

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method-name",
  "params": {
    // Method-specific parameters
  }
}

Required Fields

Standard JSON-RPC Fields

• jsonrpc: Always "2.0" (string)
• id: Unique request identifier (string/number)
• method: A2A method name (string)
• params: Method parameters (object)

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)

Response Structure

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

Success Response

{
  "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

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

Task Lifecycle States

submitted

Task received and queued for processing

working

Task is currently being processed

completed

Task completed successfully

failed

Task failed during processing

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

{
  "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:

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

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

Streaming with Server-Sent Events

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

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

{
  "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:

{
  "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

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

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642234567

Testing Your Integration

Interactive A2A Lab

Use our interactive testing environment to experiment with A2A methods and see real-time responses.

Next Steps

Message Endpoints

Learn about synchronous and streaming message methods

Task Management

Explore task lifecycle and management operations

Agent Metadata

Get agent information and capabilities

Webhook Configuration

Set up push notifications for asynchronous updates

---

Ready to integrate? Start with the message/send endpoint for basic agent communication.