message/send

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "req-001",
    method: "message/send",
    params: {
      message: {
        role: "user",
        parts: [
          {
            type: "text",
            text: "What is the A2A protocol?"
          }
        ],
        messageId: crypto.randomUUID()
      }
    }
  })
});

const result = await response.json();
console.log(result);

import requests
import uuid
import json

payload = {
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "parts": [
                {
                    "type": "text",
                    "text": "What is the A2A protocol?"
                }
            ],
            "messageId": str(uuid.uuid4())
        }
    }
}

response = requests.post(
    "http://localhost:8000/api/v1/a2a/my-agent",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

print(json.dumps(response.json(), indent=2))

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

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required field: messageId"
    }
  },
  "id": "req-001"
}

POST

api

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "req-001",
    method: "message/send",
    params: {
      message: {
        role: "user",
        parts: [
          {
            type: "text",
            text: "What is the A2A protocol?"
          }
        ],
        messageId: crypto.randomUUID()
      }
    }
  })
});

const result = await response.json();
console.log(result);

import requests
import uuid
import json

payload = {
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "parts": [
                {
                    "type": "text",
                    "text": "What is the A2A protocol?"
                }
            ],
            "messageId": str(uuid.uuid4())
        }
    }
}

response = requests.post(
    "http://localhost:8000/api/v1/a2a/my-agent",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

print(json.dumps(response.json(), indent=2))

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

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required field: messageId"
    }
  },
  "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

string

required

Must be application/json

string

required

Your API key for authentication

Path Parameters

string

required

Unique identifier of the target agent

Body Parameters

string

required

JSON-RPC version, must be "2.0"

string

required

Unique identifier for this request (for response correlation)

string

required

Must be "message/send"

object

required

Message parameters object

Show params properties

object

required

The message to send to the agent

Show message properties

string

required

Message role, must be "user"

string

required

UUID v4 identifier for this message

array

required

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

Show parts array items

string

required

Part type: "text" or "file"

string

Text content (required when type is “text”)

object

File object (required when type is “file”)

Show file properties

string

required

Original filename

string

required

MIME type of the file

string

required

Base64 encoded file content (without data URL prefix)

string

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

string

Optional session identifier for grouping related messages

string

Optional task ID for this operation

Response

Success Response

string

JSON-RPC version, always "2.0"

object

Result object containing the agent’s response

Show result properties

string

Task ID for this operation

object

Status information

Show status properties

string

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

object

Agent’s response message

Show message properties

string

Message role, always "agent"

array

Array of response parts

Show parts array items

string

Part type, typically "text"

string

Response text content

string

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

boolean

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

string

Request ID (matches the request ID)

Error Response

string

JSON-RPC version, always "2.0"

object

Error information

Show error properties

number

JSON-RPC error code

string

Human-readable error message

object

Additional error details

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

const response = await fetch('http://localhost:8000/api/v1/a2a/my-agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key'
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "req-001",
    method: "message/send",
    params: {
      message: {
        role: "user",
        parts: [
          {
            type: "text",
            text: "What is the A2A protocol?"
          }
        ],
        messageId: crypto.randomUUID()
      }
    }
  })
});

const result = await response.json();
console.log(result);

import requests
import uuid
import json

payload = {
    "jsonrpc": "2.0",
    "id": "req-001",
    "method": "message/send",
    "params": {
        "message": {
            "role": "user",
            "parts": [
                {
                    "type": "text",
                    "text": "What is the A2A protocol?"
                }
            ],
            "messageId": str(uuid.uuid4())
        }
    }
}

response = requests.post(
    "http://localhost:8000/api/v1/a2a/my-agent",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

print(json.dumps(response.json(), indent=2))

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

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required field: messageId"
    }
  },
  "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"
      }
    }
  }'

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-002",
    "method": "message/send",
    "params": {
      "contextId": "ctx-abc123",
      "message": {
        "role": "user",
        "parts": [{"type": "text", "text": "What is my name?"}],
        "messageId": "msg-002"
      }
    }
  }'

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

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

API Documentation

A2A Protocol Endpoints

Overview

Request

Headers

Path Parameters

Body Parameters

Response

Success Response

Error Response

Examples

Multi-turn Conversation Example

File Upload Example

Best Practices

​Overview

​Request

​Headers

​Path Parameters

​Body Parameters

​Response

​Success Response

​Error Response

​Examples

​Multi-turn Conversation Example

​File Upload Example

​Best Practices

Overview

Request

Headers

Path Parameters

Body Parameters

Response

Success Response

Error Response

Examples

Multi-turn Conversation Example

File Upload Example

Best Practices