Method: projects.locations.apps.message.send

Sends a message to an agent.

HTTP request

POST https://ces.googleapis.com/v1beta/{tenant=projects/*/locations/*/apps/*}/message:send

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
tenant

string

Optional. Tenant ID, provided as a path parameter.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "message": {
    object (Message)
  },
  "configuration": {
    object (SendMessageConfiguration)
  },
  "metadata": {
    object
  }
}
Fields
message

object (Message)

Required. The message to send to the agent.
configuration

object (SendMessageConfiguration)

Configuration for the send request.
metadata

object (Struct format)

A flexible key-value map for passing additional context or parameters.

Response body

Represents the response for the message.send method.

If successful, the response body contains data with the following structure:

JSON representation 
{

  // Union field payload can be only one of the following:
  "task": {
    object (Task)
  },
  "message": {
    object (Message)
  }
  // End of list of possible types for union field payload.
}
Fields
Union field payload. The payload of the response. payload can be only one of the following:
task

object (Task)

The task created or updated by the message.
message

object (Message)

A message from the agent.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/ces

For more information, see the Authentication Overview.

Message

Message is one unit of communication between client and server. It can be associated with a context and/or a task. For server messages, contextId must be provided, and taskId only if a task was created. For client messages, both fields are optional, with the caveat that if both are provided, they have to match (the contextId has to be the one that is set on the task). If only taskId is provided, the server will infer contextId from it.

JSON representation 
{
  "messageId": string,
  "contextId": string,
  "taskId": string,
  "role": enum (Role),
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ],
  "referenceTaskIds": [
    string
  ]
}
Fields
messageId

string

Required. The unique identifier (e.g. UUID) of the message. This is created by the message creator.
contextId

string

Optional. The context id of the message. If set, the message will be associated with the given context.
taskId

string

Optional. The task id of the message. If set, the message will be associated with the given task.
role

enum (Role)

Required. Identifies the sender of the message.
parts[]

object (Part)

Required. Parts is the container of the message content.
metadata

object (Struct format)

Optional. Any metadata to provide along with the message.
extensions[]

string

The URIs of extensions that are present or contributed to this Message.
referenceTaskIds[]

string

A list of task IDs that this message references for additional context.

Role

Defines the sender of a message in A2A protocol communication.

Enums
ROLE_UNSPECIFIED The role is unspecified.
ROLE_USER The message is from the client to the server.
ROLE_AGENT The message is from the server to the client.

Part

Part represents a container for a section of communication content. Parts can be purely textual, some sort of file (image, video, etc) or a structured data blob (i.e. JSON).

JSON representation 
{
  "metadata": {
    object
  },
  "filename": string,
  "mediaType": string,

  // Union field content can be only one of the following:
  "text": string,
  "raw": string,
  "url": string,
  "data": value
  // End of list of possible types for union field content.
}
Fields
metadata

object (Struct format)

Optional. metadata associated with this part.
filename

string

An optional filename for the file (e.g., "document.pdf").
mediaType

string

The mediaType (MIME type) of the part content (e.g., "text/plain", "application/json", "image/png"). This field is available for all part types.

Union field content.

content can be only one of the following:
text

string

The string content of the text part.
raw

string (bytes format)

The raw byte content of a file. In JSON serialization, this is encoded as a base64 string.

A base64-encoded string.
url

string

A url pointing to the file's content.
data

value (Value format)

Arbitrary structured data as a JSON value (object, array, string, number, boolean, or null).

SendMessageConfiguration

Configuration of a send message request.

JSON representation 
{
  "acceptedOutputModes": [
    string
  ],
  "taskPushNotificationConfig": {
    object (TaskPushNotificationConfig)
  },
  "returnImmediately": boolean,
  "historyLength": integer
}
Fields
acceptedOutputModes[]

string

A list of media types the client is prepared to accept for response parts. Agents SHOULD use this to tailor their output.
taskPushNotificationConfig

object (TaskPushNotificationConfig)

Configuration for the agent to send push notifications for task updates. Task id should be empty when sending this configuration in a message.send request.
returnImmediately

boolean

If true, the operation returns immediately after creating the task, even if processing is still in progress. If false (default), the operation MUST wait until the task reaches a terminal (COMPLETED, FAILED, CANCELED, REJECTED) or interrupted (INPUT_REQUIRED, AUTH_REQUIRED) state before returning.
historyLength

integer

The maximum number of most recent messages from the task's history to retrieve in the response. An unset value means the client does not impose any limit. A value of zero is a request to not include any messages. The server MUST NOT return more messages than the provided value, but MAY apply a lower limit.

TaskPushNotificationConfig

A container associating a push notification configuration with a specific task.

JSON representation 
{
  "tenant": string,
  "id": string,
  "taskId": string,
  "url": string,
  "token": string,
  "authentication": {
    object (AuthenticationInfo)
  }
}
Fields
tenant

string

Optional. Tenant ID.
id

string

The push notification configuration details. A unique identifier (e.g. UUID) for this push notification configuration.
taskId

string

The ID of the task this configuration is associated with.
url

string

Required. The URL where the notification should be sent.
token

string

A token unique for this task or session.
authentication

object (AuthenticationInfo)

Authentication information required to send the notification.

AuthenticationInfo

Defines authentication details, used for push notifications.

JSON representation 
{
  "scheme": string,
  "credentials": string
}
Fields
scheme

string

Required. HTTP Authentication Scheme from the IANA registry. Examples: Bearer, Basic, Digest. Scheme names are case-insensitive per RFC 9110 Section 11.1.
credentials

string

Push Notification credentials. Format depends on the scheme (e.g., token for Bearer).

Task

Task is the core unit of action for A2A. It has a current status and when results are created for the task they are stored in the artifact. If there are multiple turns for a task, these are stored in history.

JSON representation 
{
  "id": string,
  "contextId": string,
  "status": {
    object (TaskStatus)
  },
  "artifacts": [
    {
      object (Artifact)
    }
  ],
  "history": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object
  }
}
Fields
id

string

Required. Unique identifier (e.g. UUID) for the task, generated by the server for a new task.
contextId

string

Unique identifier (e.g. UUID) for the contextual collection of interactions (tasks and messages).
status

object (TaskStatus)

Required. The current status of a Task, including state and a message.
artifacts[]

object (Artifact)

A set of output artifacts for a Task.
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED The history of interactions from a Task.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED A key/value object to store custom metadata about a task.

TaskStatus

A container for the status of a task

JSON representation 
{
  "state": enum (TaskState),
  "message": {
    object (Message)
  },
  "timestamp": string
}
Fields
state

enum (TaskState)

Required. The current state of this task.
message

object (Message)

A message associated with the status.
timestamp

string (Timestamp format)

ISO 8601 Timestamp when the status was recorded. Example: "2023-10-27T10:00:00Z"

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

TaskState

Defines the possible lifecycle states of a Task.

Enums
TASK_STATE_UNSPECIFIED The task is in an unknown or indeterminate state.
TASK_STATE_SUBMITTED Indicates that a task has been successfully submitted and acknowledged.
TASK_STATE_WORKING Indicates that a task is actively being processed by the agent.
TASK_STATE_COMPLETED Indicates that a task has finished successfully. This is a terminal state.
TASK_STATE_FAILED Indicates that a task has finished with an error. This is a terminal state.
TASK_STATE_CANCELED Indicates that a task was canceled before completion. This is a terminal state.
TASK_STATE_INPUT_REQUIRED Indicates that the agent requires additional user input to proceed. This is an interrupted state.
TASK_STATE_REJECTED Indicates that the agent has decided to not perform the task. This may be done during initial task creation or later once an agent has determined it can't or won't proceed. This is a terminal state.
TASK_STATE_AUTH_REQUIRED Indicates that authentication is required to proceed. This is an interrupted state.

Artifact

Artifacts represent task outputs.

JSON representation 
{
  "artifactId": string,
  "name": string,
  "description": string,
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
Fields
artifactId

string

Required. Unique identifier (e.g. UUID) for the artifact. It must be unique within a task.
name

string

A human readable name for the artifact.
description

string

Optional. A human readable description of the artifact.
parts[]

object (Part)

Required. The content of the artifact. Must contain at least one part.
metadata

object (Struct format)

Optional. Metadata included with the artifact.
extensions[]

string

The URIs of extensions that are present or contributed to this Artifact.