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

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.

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).

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.

Methods

cancel

 Cancels a task in progress.

get

 Gets the latest state of a task.

list

 Lists tasks that match the specified filter.

subscribe

 Subscribes to task updates for tasks not in a terminal state.