REST Resource: tasks

Risorsa: Task

Task è l'unità di azione principale per A2A. Ha uno stato attuale e quando vengono creati i risultati per l'attività, questi vengono archiviati nell'artefatto. Se un'attività prevede più turni, questi vengono memorizzati nella cronologia.

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

string

Obbligatorio. Identificatore univoco (ad es. UUID) per l'attività, generato dal server per una nuova attività.
contextId

string

Identificatore univoco (ad es. UUID) per la raccolta contestuale di interazioni (attività e messaggi).
status

object (TaskStatus)

Obbligatorio. Lo stato attuale di un Task, inclusi state e un message.
artifacts[]

object (Artifact)

Un insieme di artefatti di output per un Task.
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED La cronologia delle interazioni da un Task.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED Un oggetto chiave/valore per archiviare metadati personalizzati su un'attività.

TaskStatus

Un container per lo stato di un'attività

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

enum (TaskState)

Obbligatorio. Lo stato attuale di questa attività.
message

object (Message)

Un messaggio associato allo stato.
timestamp

string (Timestamp format)

Timestamp ISO 8601 della registrazione dello stato. Esempio: "2023-10-27T10:00:00Z"

Utilizza RFC 3339, in cui l'output generato è sempre con normalizzazione Z e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

TaskState

Definisce i possibili stati del ciclo di vita di un Task.

Enum
TASK_STATE_UNSPECIFIED L'attività è in uno stato sconosciuto o indeterminato.
TASK_STATE_SUBMITTED Indica che un'attività è stata inviata e confermata correttamente.
TASK_STATE_WORKING Indica che un'attività è in fase di elaborazione attiva da parte dell'agente.
TASK_STATE_COMPLETED Indica che un'attività è stata completata correttamente. Si tratta di uno stato terminale.
TASK_STATE_FAILED Indica che un'attività è stata completata con un errore. Si tratta di uno stato terminale.
TASK_STATE_CANCELED Indica che un'attività è stata annullata prima del completamento. Si tratta di uno stato terminale.
TASK_STATE_INPUT_REQUIRED Indica che l'agente richiede un input utente aggiuntivo per procedere. Si tratta di uno stato interrotto.
TASK_STATE_REJECTED Indica che l'agente ha deciso di non eseguire l'attività. Questa operazione può essere eseguita durante la creazione iniziale dell'attività o in un secondo momento, una volta che l'agente ha stabilito che non può o non vuole procedere. Si tratta di uno stato terminale.
TASK_STATE_AUTH_REQUIRED Indica che per procedere è necessaria l'autenticazione. Si tratta di uno stato interrotto.

Messaggio

Message è un'unità di comunicazione tra client e server. Può essere associato a un contesto e/o a un'attività. Per i messaggi del server, è necessario fornire contextId e taskId solo se è stata creata un'attività. Per i messaggi del cliente, entrambi i campi sono facoltativi, con l'avvertenza che, se vengono forniti entrambi, devono corrispondere (il contextId deve essere quello impostato nell'attività). Se viene fornito solo taskId, il server dedurrà contextId.

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

string

Obbligatorio. L'identificatore univoco (ad es. UUID) del messaggio. Viene creato dal creatore del messaggio.
contextId

string

Facoltativo. L'ID contesto del messaggio. Se impostato, il messaggio verrà associato al contesto specificato.
taskId

string

Facoltativo. L'ID attività del messaggio. Se impostato, il messaggio verrà associato all'attività specificata.
role

enum (Role)

Obbligatorio. Identifica il mittente del messaggio.
parts[]

object (Part)

Obbligatorio. Parts è il contenitore dei contenuti del messaggio.
metadata

object (Struct format)

Facoltativo. Eventuali metadati da fornire insieme al messaggio.
extensions[]

string

Gli URI delle estensioni presenti o che hanno contribuito a questo messaggio.
referenceTaskIds[]

string

Un elenco di ID attività a cui fa riferimento questo messaggio per un contesto aggiuntivo.

Ruolo

Definisce il mittente di un messaggio nella comunicazione del protocollo A2A.

Enum
ROLE_UNSPECIFIED Il ruolo non è specificato.
ROLE_USER Il messaggio viene inviato dal client al server.
ROLE_AGENT Il messaggio proviene dal server e viene inviato al client.

Parte

Part rappresenta un contenitore per una sezione di contenuti di comunicazione. Le parti possono essere puramente testuali, un tipo di file (immagine, video e così via) o un blob di dati strutturati (ad es. JSON).

Rappresentazione 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.
}
Campi
metadata

object (Struct format)

(Facoltativo) Metadati associati a questa parte.
filename

string

Un filename facoltativo per il file (ad es. "documento.pdf").
mediaType

string

Il mediaType (tipo MIME) dei contenuti della parte (ad es. "text/plain", "application/json", "image/png"). Questo campo è disponibile per tutti i tipi di componenti.
Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
text

string

Il contenuto della stringa della parte text.
raw

string (bytes format)

I contenuti in raw byte di un file. Nella serializzazione JSON, questo valore viene codificato come stringa base64.

Una stringa con codifica in base64.
url

string

Un url che punta ai contenuti del file.
data

value (Value format)

data strutturato arbitrario come valore JSON (oggetto, array, stringa, numero, booleano o null).
Fine dei campi che si escludono a vicenda.

Artefatto

Gli artefatti rappresentano gli output delle attività.

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

string

Obbligatorio. Identificatore univoco (ad es. UUID) dell'artefatto. Deve essere univoco all'interno di un'attività.
name

string

Un nome leggibile per l'artefatto.
description

string

Facoltativo. Una descrizione dell'artefatto leggibile da una persona.
parts[]

object (Part)

Obbligatorio. I contenuti dell'artefatto. Deve contenere almeno una parte.
metadata

object (Struct format)

Facoltativo. Metadati inclusi nell'artefatto.
extensions[]

string

Gli URI delle estensioni presenti o che hanno contribuito a questo artefatto.

Metodi

cancel

 Annulla un'attività in corso.

get

 Recupera l'ultimo stato di un'attività.

list

 Elenca le attività che corrispondono al filtro specificato.

subscribe

 Esegue la sottoscrizione agli aggiornamenti delle attività che non si trovano in uno stato terminale.