REST Resource: projects.locations.collections.engines.assistants.agents.tasks

Resource: 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

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). Created by the A2A server.
status

object (TaskStatus)

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)

The current state of this task
message

object (Message)

A message associated with the status.
timestamp

string (Timestamp format)

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

The set of states a Task can be in.

Enums
TASK_STATE_UNSPECIFIED
TASK_STATE_SUBMITTED Represents the status that acknowledges a task is created
TASK_STATE_WORKING Represents the status that a task is actively being processed
TASK_STATE_COMPLETED Represents the status a task is finished. This is a terminal state
TASK_STATE_FAILED Represents the status a task is done but failed. This is a terminal state
TASK_STATE_CANCELLED Represents the status a task was cancelled before it finished. This is a terminal state.
TASK_STATE_INPUT_REQUIRED Represents the status that the task requires information to complete. This is an interrupted state.
TASK_STATE_REJECTED Represents the status 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 Represents the state that some authentication is needed from the upstream client. Authentication is expected to come out-of-band thus this is not an interrupted or terminal state.

Message

Message is one unit of communication between client and server. It is associated with a context and optionally a task. Since the server is responsible for the context definition, it must always provide a contextId in its messages. The client can optionally provide the contextId if it knows the context to associate the message to. Similarly for taskId, except the server decides if a task is created and whether to include the taskId.

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

string

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

string

The context id of the message. This is optional and if set, the message will be associated with the given context.
taskId

string

The task id of the message. This is optional and if set, the message will be associated with the given task.
role

enum (Role)

A role for the message.
content[]

object (Part)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Content is the container of the message content.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED Any optional metadata to provide along with the message.
extensions[]

string

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

Role

Enums
ROLE_UNSPECIFIED
ROLE_USER USER role refers to communication from the client to the server.
ROLE_AGENT AGENT role refers to communication 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
  },

  // Union field part can be only one of the following:
  "text": string,
  "file": {
    object (FilePart)
  },
  "data": {
    object (DataPart)
  }
  // End of list of possible types for union field part.
}
Fields
metadata

object (Struct format)

Optional metadata associated with this part.

Union field part.

part can be only one of the following:
text

string
file

object (FilePart)
data

object (DataPart)

FilePart

FilePart represents the different ways files can be provided. If files are small, directly feeding the bytes is supported via fileWithBytes. If the file is large, the agent should read the content as appropriate directly from the fileWithUri source.

JSON representation 
{
  "mimeType": string,
  "name": string,

  // Union field file can be only one of the following:
  "fileWithUri": string,
  "fileWithBytes": string
  // End of list of possible types for union field file.
}
Fields
mimeType

string
name

string

Union field file.

file can be only one of the following:
fileWithUri

string
fileWithBytes

string (bytes format)

A base64-encoded string.

DataPart

DataPart represents a structured blob. This is most commonly a JSON payload.

JSON representation 
{
  "data": {
    object
  }
}
Fields
data

object (Struct format)

Artifact

Artifacts are the container for task completed results. These are similar to Messages but are intended to be the product of a task, as opposed to point-to-point communication.

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

string

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

string

A human readable name for the artifact.
description

string

A human readable description of the artifact, optional.
parts[]

object (Part)

The content of the artifact.
metadata

object (Struct format)

Optional metadata included with the artifact.
extensions[]

string

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

Methods

cancel

 Cancel a task from the agent.

get

 Get the current state of a task from the agent.

subscribe

 TaskSubscription is a streaming call that will return a stream of task update events.