REST Resource: tasks

Recurso: Task

Task é a unidade principal de ação para A2A. Ele tem um status atual e, quando os resultados são criados para a tarefa, eles são armazenados no artefato. Se houver várias etapas para uma tarefa, elas serão armazenadas no histórico.

Representação JSON 
{
  "id": string,
  "contextId": string,
  "status": {
    object (TaskStatus)
  },
  "artifacts": [
    {
      object (Artifact)
    }
  ],
  "history": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object
  }
}
Campos
id

string

Obrigatório. Identificador exclusivo (por exemplo, UUID) da tarefa, gerado pelo servidor para uma nova tarefa.
contextId

string

Identificador exclusivo (por exemplo, UUID) para a coleta contextual de interações (tarefas e mensagens).
status

object (TaskStatus)

Obrigatório. O status atual de um Task, incluindo state e um message.
artifacts[]

object (Artifact)

Um conjunto de artefatos de saída para um Task.
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED O histórico de interações de um Task.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED Um objeto de chave/valor para armazenar metadados personalizados sobre uma tarefa.

TaskStatus

Um contêiner para o status de uma tarefa

Representação JSON 
{
  "state": enum (TaskState),
  "message": {
    object (Message)
  },
  "timestamp": string
}
Campos
state

enum (TaskState)

Obrigatório. O estado atual da tarefa.
message

object (Message)

Uma mensagem associada ao status.
timestamp

string (Timestamp format)

Carimbo de data/hora ISO 8601 em que o status foi registrado. Exemplo: "2023-10-27T10:00:00Z"

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

TaskState

Define os possíveis estados do ciclo de vida de um Task.

Tipos enumerados
TASK_STATE_UNSPECIFIED A tarefa está em um estado desconhecido ou indeterminado.
TASK_STATE_SUBMITTED Indica que uma tarefa foi enviada e confirmada.
TASK_STATE_WORKING Indica que uma tarefa está sendo processada pelo agente.
TASK_STATE_COMPLETED Indica que uma tarefa foi concluída com sucesso. Esse é um estado terminal.
TASK_STATE_FAILED Indica que uma tarefa foi concluída com um erro. Esse é um estado terminal.
TASK_STATE_CANCELED Indica que uma tarefa foi cancelada antes da conclusão. Esse é um estado terminal.
TASK_STATE_INPUT_REQUIRED Indica que o agente requer entrada do usuário adicional para continuar. Esse é um estado interrompido.
TASK_STATE_REJECTED Indica que o agente decidiu não realizar a tarefa. Isso pode ser feito durante a criação inicial da tarefa ou depois que um agente determinar que não pode ou não vai continuar. Esse é um estado terminal.
TASK_STATE_AUTH_REQUIRED Indica que a autenticação é necessária para continuar. Esse é um estado interrompido.

Mensagem

Message é uma unidade de comunicação entre cliente e servidor. Ele pode estar associado a um contexto e/ou uma tarefa. Para mensagens do servidor, contextId precisa ser fornecido, e taskId apenas se uma tarefa foi criada. Para mensagens do cliente, os dois campos são opcionais, mas se ambos forem fornecidos, eles precisam corresponder (o contextId precisa ser o definido na tarefa). Se apenas taskId for fornecido, o servidor vai inferir contextId dele.

Representação JSON 
{
  "messageId": string,
  "contextId": string,
  "taskId": string,
  "role": enum (Role),
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ],
  "referenceTaskIds": [
    string
  ]
}
Campos
messageId

string

Obrigatório. O identificador exclusivo (por exemplo, UUID) da mensagem. Isso é criado pelo criador da mensagem.
contextId

string

Opcional. O ID do contexto da mensagem. Se definido, a mensagem será associada ao contexto especificado.
taskId

string

Opcional. O ID da tarefa da mensagem. Se definido, a mensagem será associada à tarefa especificada.
role

enum (Role)

Obrigatório. Identifica o remetente da mensagem.
parts[]

object (Part)

Obrigatório. "Parts" é o contêiner do conteúdo da mensagem.
metadata

object (Struct format)

Opcional. Todos os metadados a serem fornecidos com a mensagem.
extensions[]

string

Os URIs das extensões presentes ou que contribuíram para esta mensagem.
referenceTaskIds[]

string

Uma lista de IDs de tarefas que esta mensagem referencia para mais contexto.

Papel

Define o remetente de uma mensagem na comunicação do protocolo A2A.

Tipos enumerados
ROLE_UNSPECIFIED A função não foi especificada.
ROLE_USER A mensagem é do cliente para o servidor.
ROLE_AGENT A mensagem é do servidor para o cliente.

Parte

Part representa um contêiner para uma seção de conteúdo de comunicação. As partes podem ser puramente textuais, algum tipo de arquivo (imagem, vídeo etc.) ou um blob de dados estruturados (ou seja, JSON).

Representação 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. Metadados associados a esta parte.
filename

string

Um filename opcional para o arquivo (por exemplo, "document.pdf").
mediaType

string

O mediaType (tipo MIME) do conteúdo da parte (por exemplo, "text/plain", "application/json", "image/png"). Esse campo está disponível para todos os tipos de peças.
Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
text

string

O conteúdo da string da parte text.
raw

string (bytes format)

O conteúdo de bytes raw de um arquivo. Na serialização JSON, isso é codificado como uma string base64.

Uma string codificada em base64.
url

string

Um url que aponta para o conteúdo do arquivo.
data

value (Value format)

data estruturado arbitrário como um valor JSON (objeto, matriz, string, número, booleano ou nulo).
Fim dos campos mutuamente exclusivos.

Artefato

Os artefatos representam as saídas das tarefas.

Representação JSON 
{
  "artifactId": string,
  "name": string,
  "description": string,
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
Campos
artifactId

string

Obrigatório. Identificador exclusivo (por exemplo, UUID) do artefato. Ele precisa ser exclusivo em uma tarefa.
name

string

Um nome legível para o artefato.
description

string

Opcional. Uma descrição legível por humanos do artefato.
parts[]

object (Part)

Obrigatório. O conteúdo do artefato. Precisa conter pelo menos uma parte.
metadata

object (Struct format)

Opcional. Metadados incluídos no artefato.
extensions[]

string

Os URIs das extensões presentes ou que contribuíram para este artefato.

Métodos

cancel

 Cancela uma tarefa em andamento.

get

 Recebe o estado mais recente de uma tarefa.

list

 Lista as tarefas que correspondem ao filtro especificado.

subscribe

 Inscreve-se em atualizações de tarefas que não estão em um estado terminal.