Send a message to an agent

This guide shows you how to send a message to an agent and handle the response. You will learn about blocking vs. non-blocking requests, context management, and error handling.

Prerequisites

An existing agent (see Create an agent)
An access token or client credentials
Your tenant name

Send a message

Use the HTTP+JSON binding to send a message:

# Replace these with your values
AGENT_ID="<your-agent-id>"
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}/a2a/message:send" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [{ "text": "What is the ICD-10 code for asthma?" }]
    }
  }'

Message structure

A message contains:

Field	Required	Description
`role`	yes	`ROLE_USER` or `ROLE_AGENT`
`parts`	yes	Ordered content parts (text, file, or data)
`messageId`	no	Message identifier (UUID); server generates one if omitted
`contextId`	no	Context ID for conversation continuity
`referenceTaskIds`	no	Task IDs this message references
`extensions`	no	URIs of A2A extensions
`metadata`	no	Free-form metadata

The request body also accepts an optional configuration object:

Field	Default	Description
`returnImmediately`	`false`	If `true`, return as soon as the task is submitted. If `false` (default), wait until the task reaches a terminal or interrupted state.
`historyLength`	unset	Cap the number of history messages returned per task
`acceptedOutputModes`	unset	Output media types the client accepts

Blocking vs. non-blocking

By default, message:send is blocking: the server waits for the task to complete before returning. Set configuration.returnImmediately to true to return as soon as the task is submitted:

curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}/a2a/message:send" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [{ "text": "Generate a full clinical note for this encounter." }]
    },
    "configuration": {
      "returnImmediately": true
    }
  }'

With returnImmediately: true, the response returns immediately with the task in TASK_STATE_SUBMITTED or TASK_STATE_WORKING state. Poll the task endpoint or subscribe via SSE to get updates.

Handling the response

The response contains either a task or a message object:

task: The agent is performing long-running work. Check task.status.state for the current state. When TASK_STATE_COMPLETED, the agent’s response is in task.history (the last ROLE_AGENT message). Artifacts are in task.artifacts.
message: The agent responded directly with a message. The text is in message.parts[0].text.

{
  "task": {
    "id": "task.0192f4c8-...",
    "contextId": "ctx.0192f4c8-...",
    "status": {
      "state": "TASK_STATE_COMPLETED",
      "timestamp": "2026-05-19T12:00:01Z"
    },
    "history": [
      {"role": "ROLE_USER", "messageId": "msg.0192f4c8-...", "parts": [{"text": "What is the ICD-10 code for asthma?"}]},
      {"role": "ROLE_AGENT", "messageId": "msg.0192f4c8-...", "parts": [{"text": "J45.909"}]}
    ]
  }
}

Context management

The server automatically creates a context if you don’t provide a contextId. The response includes the contextId in the task object. To continue a conversation, include that contextId in subsequent messages:

CONTEXT_ID="ctx.0192f4c8-..."

curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}/a2a/message:send" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [{ "text": "What about the code for acute exacerbation?" }],
      "contextId": "'"$CONTEXT_ID"'"
    }
  }'

See Context and memory for details on how context works.

Using data parts for structured context

Pass structured data alongside text using data parts:

curl -X POST "https://api.${ENVIRONMENT}.corti.app/v2/agentic/agents/${AGENT_ID}/a2a/message:send" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        { "text": "Code this encounter:" },
        { "data": {
            "chiefComplaint": "Acute asthma exacerbation",
            "patientAge": 45,
            "vitalSigns": {"heartRate": 110, "respiratoryRate": 28}
          }
        }
      ]
    }
  }'

Error handling

Errors follow the A2A google.rpc.Status error format:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Message must include at least one part.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_REQUEST",
        "domain": "a2a-protocol.org",
        "metadata": {
          "timestamp": "2026-05-19T12:00:00Z"
        }
      }
    ]
  }
}

Common error codes:

HTTP status	`status`	Description
400	`INVALID_ARGUMENT`	Invalid request (malformed message)
401	`UNAUTHENTICATED`	Unauthorized (missing or invalid token)
404	`NOT_FOUND`	Agent not found

Next steps

Learn how to stream responses via SSE
Understand the task lifecycle for long-running work
Read about contexts for conversation management

Quickstart

Concepts

Guides

Reference

Registry Connectors

Agent SDK

v1 Documentation (archived)

Prerequisites

Send a message

Message structure

Blocking vs. non-blocking

Handling the response

Context management

Using data parts for structured context

Error handling

Next steps

​Prerequisites

​Send a message

​Message structure

​Blocking vs. non-blocking

​Handling the response

​Context management

​Using data parts for structured context

​Error handling

​Next steps

Prerequisites

Send a message

Message structure

Blocking vs. non-blocking

Handling the response

Context management

Using data parts for structured context

Error handling

Next steps