Skip to main content
POST
/
api
/
v1
/
a2a
/
{agent_id}
curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "What is the A2A protocol?"
          }
        ],
        "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6"
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-456",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "The A2A (Agent-to-Agent) protocol is a standardized communication protocol developed by Google for enabling structured communication between AI agents. It uses JSON-RPC 2.0 over HTTP/HTTPS and supports features like multi-turn conversations, file uploads, and streaming responses."
          }
        ]
      }
    },
    "contextId": "ctx-abc123",
    "final": true
  },
  "id": "req-001"
}

​
Overview

The message/send method is the primary way to communicate with A2A agents synchronously. Send a message and receive a complete response in a single HTTP request.
Synchronous Communication: This method blocks until the agent provides a complete response. For streaming responses, use message/stream instead.

​
Request

​
Headers

​
Content-Type
string
required
Must be application/json
​
x-api-key
string
required
Your API key for authentication

​
Path Parameters

​
agent_id
string
required
Unique identifier of the target agent

​
Body Parameters

​
jsonrpc
string
required
JSON-RPC version, must be "2.0"
​
id
string
required
Unique identifier for this request (for response correlation)
​
method
string
required
Must be "message/send"
​
params
object
required
Message parameters object

​
Response

​
Success Response

​
jsonrpc
string
JSON-RPC version, always "2.0"
​
result
object
Result object containing the agent’s response
​
id
string
Request ID (matches the request ID)

​
Error Response

​
jsonrpc
string
JSON-RPC version, always "2.0"
​
error
object
Error information
​
id
string
Request ID (matches the request ID)

​
Examples

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "What is the A2A protocol?"
          }
        ],
        "messageId": "6dbc13b5-bd57-4c2b-b503-24e381b6c8d6"
      }
    }
  }'

{
  "jsonrpc": "2.0",
  "result": {
    "id": "task-456",
    "status": {
      "state": "completed",
      "message": {
        "role": "agent",
        "parts": [
          {
            "type": "text",
            "text": "The A2A (Agent-to-Agent) protocol is a standardized communication protocol developed by Google for enabling structured communication between AI agents. It uses JSON-RPC 2.0 over HTTP/HTTPS and supports features like multi-turn conversations, file uploads, and streaming responses."
          }
        ]
      }
    },
    "contextId": "ctx-abc123",
    "final": true
  },
  "id": "req-001"
}

​
Multi-turn Conversation Example

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "My name is John"}],
        "messageId": "msg-001"
      }
    }
  }'

​
File Upload Example

curl -X POST "http://localhost:8000/api/v1/a2a/my-agent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "jsonrpc": "2.0",
    "id": "req-003",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "Please analyze this document"
          },
          {
            "type": "file",
            "file": {
              "name": "report.pdf",
              "mimeType": "application/pdf",
              "bytes": "JVBERi0xLjQKJcOkw7zDtsO..."
            }
          }
        ],
        "messageId": "msg-003"
      }
    }
  }'

​
Best Practices

  • Always use UUID v4 for messageId fields
  • Keep request IDs unique for proper correlation
  • Store contextId from responses for multi-turn conversations
  • Use Base64 encoding without data URL prefix
  • Specify correct MIME types for proper handling
  • Keep files under 5MB for optimal performance
  • Always check for error field in responses
  • Implement retry logic for transient errors (5xx codes)
  • Validate JSON-RPC format before sending requests