message/send

Send synchronous messages to A2A agents and receive immediate responses

POST /api/v1/a2a/{agent_id}

cURL

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"
      }
    }
  }'

Success Response

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

Show params properties

params.message · object · required

The message to send to the agent

Show message properties

params.message.role · string · required

Message role, must be "user"

params.message.messageId · string · required

UUID v4 identifier for this message

params.message.parts · array · required

Array of message parts (text, files, etc.)

Show parts array items

params.message.parts[].type · string · required

Part type: "text" or "file"

params.message.parts[].text · string

Text content (required when type is “text”)

params.message.parts[].file · object

File object (required when type is “file”)

Show file properties

params.message.parts[].file.name · string · required

Original filename

params.message.parts[].file.mimeType · string · required

MIME type of the file

params.message.parts[].file.bytes · string · required

Base64 encoded file content (without data URL prefix)

params.contextId · string

Context ID for multi-turn conversations (from previous response)

params.sessionId · string

Optional session identifier for grouping related messages

params.id · string

Optional task ID for this operation

Response

Success Response

jsonrpc · string

JSON-RPC version, always "2.0"

result · object

Result object containing the agent’s response

Show result properties

result.id · string

Task ID for this operation

result.status · object

Status information

Show status properties

result.status.state · string

Task state: "completed", "working", "failed", or "canceled"

result.status.message · object

Agent’s response message

Show message properties

result.status.message.role · string

Message role, always "agent"

result.status.message.parts · array

Array of response parts

Show parts array items

result.status.message.parts[].type · string

Part type, typically "text"

result.status.message.parts[].text · string

Response text content

result.contextId · string

Context ID for multi-turn conversations (save for subsequent messages)

result.final · boolean

Whether this is the final response (always true for message/send)

id · string

Request ID (matches the request ID)

Error Response

jsonrpc · string

JSON-RPC version, always "2.0"

error · object

Error information

Show error properties

error.code · number

JSON-RPC error code

error.message · string

Human-readable error message

error.data · object

Additional error details

id · string

Request ID (matches the request ID)

Examples

cURL

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"
      }
    }
  }'

Success Response

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

First Message

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

File Upload

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

Message IDs

• Always use UUID v4 for messageId fields
• Keep request IDs unique for proper correlation
• Store contextId from responses for multi-turn conversations

File Uploads

• Use Base64 encoding without data URL prefix
• Specify correct MIME types for proper handling
• Keep files under 5MB for optimal performance

Error Handling

• Always check for error field in responses
• Implement retry logic for transient errors (5xx codes)
• Validate JSON-RPC format before sending requests