---
title: "Send A2A v0.3 message"
method: POST
path: "/v2/agents/{agent_key}/v1/message:send"
tags: ["A2A Protocol"]
---

# Send A2A v0.3 message

`POST /v2/agents/{agent_key}/v1/message:send`

Sends a message to the agent. Blocks until the agent reaches a terminal or interrupted state. Returns the resulting `task`, or a direct `message` reply for stateless interactions.

To continue an existing conversation, set `message.contextId` to the prior task's id.

## Path parameters

- `agent_key` string, required — A unique key that identifies an agent.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- A2aV03SendMessageRequest — Body of `POST /v1/message:send` and `POST /v1/message:stream`.
  - `message` A2aV03Message, required — A v0.3 unit of communication between client and agent. The `content` field carries the message parts.
    - `messageId` string, required — Unique identifier for this message, set by the sender.
    - `contextId` string, nullable — Identifier of the conversation context this message belongs to.
    - `taskId` string, nullable — Identifier of the task this message is associated with.
    - `role` 'ROLE_UNSPECIFIED' | 'ROLE_USER' | 'ROLE_AGENT', required — The sender role in an A2A v0.3 message.
    - `content` A2aV03Part[], required — Message content parts.
      - `text` string, nullable — Plain-text content.
      - `file` A2aV03FilePart — A v0.3 file attachment. Exactly one of `fileWithUri` or `fileWithBytes` is populated.
        - `fileWithUri` string, nullable — URI to the file's content.
        - `fileWithBytes` string, byte, nullable — Inline base64-encoded file bytes.
        - `mimeType` string, nullable — Media type of the file content.
      - `data` A2aV03DataPart — A v0.3 structured-data part. The `data` field is an arbitrary JSON object.
        - `data` object, required — Arbitrary structured JSON object payload.
    - `metadata` object, nullable — Arbitrary sender-supplied metadata.
    - `extensions` string[], nullable — URIs of A2A extensions this message activates.
  - `configuration` A2aV03SendMessageConfiguration — Optional settings that control how the agent processes and responds to a v0.3 message.
    - `acceptedOutputModes` string[], nullable — Media types the client accepts for the agent's output.
    - `pushNotification` A2aV03PushNotificationConfig — Webhook configuration for receiving v0.3 task updates out-of-band.
      - `id` string, nullable — Server-assigned identifier for this push notification configuration.
      - `url` string, required — Webhook URL the agent posts task updates to.
      - `token` string, nullable — Optional token included in update requests so the receiver can validate the caller.
      - `authentication` A2aV03AuthenticationInfo — Authentication parameters for the agent to use when pushing task updates to a webhook.
        - `schemes` string[], required — Supported authentication scheme names the agent may use.
        - `credentials` string, nullable — Optional credentials passed to the webhook for the listed schemes.
    - `historyLength` integer, nullable — Maximum number of recent history messages to include in the response.
    - `blocking` boolean, nullable — When true, the call blocks until the task reaches a terminal state.
    - `returnImmediately` boolean, nullable — Inverse-semantics alias for `blocking`. If both are provided, `blocking` wins.
  - `metadata` object, nullable — Arbitrary client-supplied metadata for the request.

## Response `200`

The send-message response — exactly one of `task` or `message`.

- A2aV03SendMessageResponse — Response of `POST /v1/message:send`. Exactly one of `task` or `message` is populated.
  - `task` A2aV03Task — A v0.3 unit of work executed by the agent on behalf of a user.
    - `id` string, required — Unique identifier of the task.
    - `contextId` string — Identifier of the conversation context the task belongs to.
    - `status` A2aV03TaskStatus, required — Current status of a v0.3 task.
      - `state` 'TASK_STATE_UNSPECIFIED' | 'TASK_STATE_SUBMITTED' | 'TASK_STATE_WORKING' | 'TASK_STATE_COMPLETED' | 'TASK_STATE_FAILED' | 'TASK_STATE_CANCELLED' | 'TASK_STATE_INPUT_REQUIRED' | 'TASK_STATE_REJECTED' | 'TASK_STATE_AUTH_REQUIRED', required — The A2A v0.3 task lifecycle state. `TASK_STATE_CANCELLED` uses the UK spelling, as defined in the A2A v0.3 specification.
      - `message` A2aV03Message — A v0.3 unit of communication between client and agent. The `content` field carries the message parts.
        - `messageId` string, required — Unique identifier for this message, set by the sender.
        - `contextId` string, nullable — Identifier of the conversation context this message belongs to.
        - `taskId` string, nullable — Identifier of the task this message is associated with.
        - `role` 'ROLE_UNSPECIFIED' | 'ROLE_USER' | 'ROLE_AGENT', required — The sender role in an A2A v0.3 message.
        - `content` A2aV03Part[], required — Message content parts.
          - `text` string, nullable — Plain-text content.
          - `file` A2aV03FilePart — A v0.3 file attachment. Exactly one of `fileWithUri` or `fileWithBytes` is populated.
            - `fileWithUri` string, nullable — URI to the file's content.
            - `fileWithBytes` string, byte, nullable — Inline base64-encoded file bytes.
            - `mimeType` string, nullable — Media type of the file content.
          - `data` A2aV03DataPart — A v0.3 structured-data part. The `data` field is an arbitrary JSON object.
            - `data` object, required — Arbitrary structured JSON object payload.
        - `metadata` object, nullable — Arbitrary sender-supplied metadata.
        - `extensions` string[], nullable — URIs of A2A extensions this message activates.
      - `timestamp` string, date-time, nullable — ISO 8601 timestamp of the transition into this state.
    - `artifacts` A2aV03Artifact[], nullable — Artifacts produced by the task.
      - `artifactId` string, required — Unique identifier for this artifact, stable across appended updates.
      - `name` string, nullable — Human-readable name of the artifact.
      - `description` string, nullable — Human-readable description of the artifact's contents.
      - `parts` A2aV03Part[], required — The content parts that make up this artifact.
        - `text` string, nullable — Plain-text content.
        - `file` A2aV03FilePart — A v0.3 file attachment. Exactly one of `fileWithUri` or `fileWithBytes` is populated.
          - `fileWithUri` string, nullable — URI to the file's content.
          - `fileWithBytes` string, byte, nullable — Inline base64-encoded file bytes.
          - `mimeType` string, nullable — Media type of the file content.
        - `data` A2aV03DataPart — A v0.3 structured-data part. The `data` field is an arbitrary JSON object.
          - `data` object, required — Arbitrary structured JSON object payload.
      - `metadata` object, nullable — Arbitrary agent-supplied metadata for the artifact.
      - `extensions` string[], nullable — URIs of A2A extensions associated with this artifact.
    - `history` A2aV03Message[], nullable — Conversation messages exchanged during the task.
      - `messageId` string, required — Unique identifier for this message, set by the sender.
      - `contextId` string, nullable — Identifier of the conversation context this message belongs to.
      - `taskId` string, nullable — Identifier of the task this message is associated with.
      - `role` 'ROLE_UNSPECIFIED' | 'ROLE_USER' | 'ROLE_AGENT', required — The sender role in an A2A v0.3 message.
      - `content` A2aV03Part[], required — Message content parts.
        - `text` string, nullable — Plain-text content.
        - `file` A2aV03FilePart — A v0.3 file attachment. Exactly one of `fileWithUri` or `fileWithBytes` is populated.
          - `fileWithUri` string, nullable — URI to the file's content.
          - `fileWithBytes` string, byte, nullable — Inline base64-encoded file bytes.
          - `mimeType` string, nullable — Media type of the file content.
        - `data` A2aV03DataPart — A v0.3 structured-data part. The `data` field is an arbitrary JSON object.
          - `data` object, required — Arbitrary structured JSON object payload.
      - `metadata` object, nullable — Arbitrary sender-supplied metadata.
      - `extensions` string[], nullable — URIs of A2A extensions this message activates.
    - `metadata` object, nullable — Arbitrary agent-supplied metadata for the task.
  - `message` A2aV03Message — A v0.3 unit of communication between client and agent. The `content` field carries the message parts.
    - `messageId` string, required — Unique identifier for this message, set by the sender.
    - `contextId` string, nullable — Identifier of the conversation context this message belongs to.
    - `taskId` string, nullable — Identifier of the task this message is associated with.
    - `role` 'ROLE_UNSPECIFIED' | 'ROLE_USER' | 'ROLE_AGENT', required — The sender role in an A2A v0.3 message.
    - `content` A2aV03Part[], required — Message content parts.
      - `text` string, nullable — Plain-text content.
      - `file` A2aV03FilePart — A v0.3 file attachment. Exactly one of `fileWithUri` or `fileWithBytes` is populated.
        - `fileWithUri` string, nullable — URI to the file's content.
        - `fileWithBytes` string, byte, nullable — Inline base64-encoded file bytes.
        - `mimeType` string, nullable — Media type of the file content.
      - `data` A2aV03DataPart — A v0.3 structured-data part. The `data` field is an arbitrary JSON object.
        - `data` object, required — Arbitrary structured JSON object payload.
    - `metadata` object, nullable — Arbitrary sender-supplied metadata.
    - `extensions` string[], nullable — URIs of A2A extensions this message activates.

## Other responses

- `400` — The request was malformed.
- `404` — Agent or referenced context not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/revisions/fca567a46b3a/schema)