Skip to main content

​
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-keyStandard API key authentication for secure agent access.
x-api-key: your-api-key-here

​
Core Methods

The A2A Protocol supports the following core methods:
MethodPurposeType
message/sendSend synchronous messagesHTTP Request
message/streamSend streaming messagesServer-Sent Events
tasks/getGet task statusHTTP Request
tasks/cancelCancel running taskHTTP Request
tasks/pushNotificationConfig/setConfigure webhooksHTTP Request
tasks/pushNotificationConfig/getGet webhook configHTTP Request
tasks/resubscribeResubscribe to taskHTTP Request
agent/authenticatedExtendedCardGet agent metadataHTTP 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

  • jsonrpc: Always "2.0" (string)
  • id: Unique request identifier (string/number)
  • method: A2A method name (string)
  • params: Method parameters (object)
  • 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

CodeDescriptionResolution
-32700Parse errorCheck JSON syntax
-32600Invalid requestVerify JSON-RPC 2.0 format
-32601Method not foundCheck method name spelling
-32602Invalid paramsVerify parameter structure
-32603Internal errorServer-side issue, retry later
-32000Agent errorAgent-specific error, check message

​
Rate Limiting

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