REST Resource: tasks

Recurso: Task

Task es la unidad de acción principal para A2A. Tiene un estado actual y, cuando se crean resultados para la tarea, se almacenan en el artefacto. Si hay varios turnos para una tarea, estos se almacenan en el historial.

Representación JSON 
{
  "id": string,
  "contextId": string,
  "status": {
    object (TaskStatus)
  },
  "artifacts": [
    {
      object (Artifact)
    }
  ],
  "history": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object
  }
}
Campos
id

string

Obligatorio. Es el identificador único (p.ej., UUID) de la tarea, que genera el servidor para una tarea nueva.
contextId

string

Identificador único (p.ej., UUID) para la colección contextual de interacciones (tareas y mensajes).
status

object (TaskStatus)

Obligatorio. Es el estado actual de un Task, incluidos state y un message.
artifacts[]

object (Artifact)

Es un conjunto de artefactos de salida para un Task.
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Es el historial de interacciones de un Task.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED Es un objeto clave/valor para almacenar metadatos personalizados sobre una tarea.

TaskStatus

Es un contenedor para el estado de una tarea.

Representación JSON 
{
  "state": enum (TaskState),
  "message": {
    object (Message)
  },
  "timestamp": string
}
Campos
state

enum (TaskState)

Obligatorio. Es el estado actual de esta tarea.
message

object (Message)

Es un mensaje asociado al estado.
timestamp

string (Timestamp format)

Es la marca de tiempo en formato ISO 8601 en la que se registró el estado. Ejemplo: "2023-10-27T10:00:00Z"

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

TaskState

Define los posibles estados del ciclo de vida de un Task.

Enums
TASK_STATE_UNSPECIFIED La tarea se encuentra en un estado desconocido o indeterminado.
TASK_STATE_SUBMITTED Indica que una tarea se envió y se confirmó correctamente.
TASK_STATE_WORKING Indica que el agente está procesando una tarea de forma activa.
TASK_STATE_COMPLETED Indica que una tarea finalizó correctamente. Este es un estado terminal.
TASK_STATE_FAILED Indica que una tarea finalizó con un error. Este es un estado terminal.
TASK_STATE_CANCELED Indica que se canceló una tarea antes de que se completara. Este es un estado terminal.
TASK_STATE_INPUT_REQUIRED Indica que el agente requiere información adicional del usuario para continuar. Este es un estado interrumpido.
TASK_STATE_REJECTED Indica que el agente decidió no realizar la tarea. Esto se puede hacer durante la creación inicial de la tarea o más adelante, una vez que un agente haya determinado que no puede o no quiere continuar. Este es un estado terminal.
TASK_STATE_AUTH_REQUIRED Indica que se requiere autenticación para continuar. Este es un estado interrumpido.

Mensaje

Message es una unidad de comunicación entre el cliente y el servidor. Se puede asociar con un contexto o una tarea. En el caso de los mensajes del servidor, se debe proporcionar contextId y taskId solo si se creó una tarea. En el caso de los mensajes del cliente, ambos campos son opcionales, con la advertencia de que, si se proporcionan ambos, deben coincidir (el contextId debe ser el que se establece en la tarea). Si solo se proporciona taskId, el servidor inferirá contextId a partir de él.

Representación JSON 
{
  "messageId": string,
  "contextId": string,
  "taskId": string,
  "role": enum (Role),
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ],
  "referenceTaskIds": [
    string
  ]
}
Campos
messageId

string

Obligatorio. Es el identificador único (p.ej., UUID) del mensaje. El creador del mensaje crea este elemento.
contextId

string

Es opcional. Es el ID de contexto del mensaje. Si se configura, el mensaje se asociará con el contexto determinado.
taskId

string

Es opcional. Es el ID de la tarea del mensaje. Si se configura, el mensaje se asociará con la tarea determinada.
role

enum (Role)

Obligatorio. Identifica al remitente del mensaje.
parts[]

object (Part)

Obligatorio. Parts es el contenedor del contenido del mensaje.
metadata

object (Struct format)

Es opcional. Son los metadatos que se proporcionan junto con el mensaje.
extensions[]

string

Son los URIs de las extensiones que están presentes en este mensaje o que contribuyeron a él.
referenceTaskIds[]

string

Es una lista de IDs de tareas a las que hace referencia este mensaje para proporcionar contexto adicional.

Rol

Define el remitente de un mensaje en la comunicación del protocolo A2A.

Enums
ROLE_UNSPECIFIED El rol no se especifica.
ROLE_USER El mensaje es del cliente al servidor.
ROLE_AGENT El mensaje se envía del servidor al cliente.

Parte

Part representa un contenedor para una sección de contenido de comunicación. Las partes pueden ser puramente textuales, algún tipo de archivo (imagen, video, etc.) o un blob de datos estructurados (es decir, JSON).

Representación JSON 
{
  "metadata": {
    object
  },
  "filename": string,
  "mediaType": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "text": string,
  "raw": string,
  "url": string,
  "data": value
  // End of mutually exclusive fields.
}
Campos
metadata

object (Struct format)

Opcional. Son los metadatos asociados a esta parte.
filename

string

Es un filename opcional para el archivo (p.ej., "document.pdf").
mediaType

string

El mediaType (tipo de MIME) del contenido de la parte (p.ej., "text/plain", "application/json", "image/png"). Este campo está disponible para todos los tipos de partes.
La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
text

string

Es el contenido de cadena de la parte text.
raw

string (bytes format)

Es el contenido de bytes raw de un archivo. En la serialización de JSON, se codifica como una cadena en base64.

Es una cadena codificada en Base64.
url

string

Es un url que apunta al contenido del archivo.
data

value (Value format)

data estructurado arbitrario como un valor JSON (objeto, array, cadena, número, booleano o nulo).
Fin de los campos mutuamente excluyentes.

Artefacto

Los artefactos representan los resultados de las tareas.

Representación JSON 
{
  "artifactId": string,
  "name": string,
  "description": string,
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
Campos
artifactId

string

Obligatorio. Es el identificador único (p.ej., UUID) del artefacto. Debe ser único dentro de una tarea.
name

string

Es un nombre legible para el artefacto.
description

string

Es opcional. Es una descripción del artefacto legible por humanos.
parts[]

object (Part)

Obligatorio. Es el contenido del artefacto. Debe contener al menos una parte.
metadata

object (Struct format)

Es opcional. Son los metadatos incluidos con el artefacto.
extensions[]

string

Son los URIs de las extensiones que están presentes en este artefacto o que contribuyeron a él.

Métodos

cancel

 Cancela una tarea en curso.

get

 Obtiene el estado más reciente de una tarea.

list

 Enumera las tareas que coinciden con el filtro especificado.

subscribe

 Se suscribe a las actualizaciones de tareas que no están en un estado terminal.