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

資源：Task

工作是 A2A 的核心動作單元，具有目前狀態，且工作結果會儲存在構件中。如果工作有多個回合，這些回合會儲存在記錄中。

JSON 表示法 
{
  "id": string,
  "contextId": string,
  "status": {
    object (TaskStatus)
  },
  "artifacts": [
    {
      object (Artifact)
    }
  ],
  "history": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object
  }
}
欄位
id

string

工作專屬 ID (例如 UUID)，由伺服器為新工作產生。
contextId

string

互動 (工作和訊息) 脈絡集合的專屬 ID (例如 UUID)。由 A2A 伺服器建立。
status

object (TaskStatus)

工作目前的狀態，包括狀態和訊息。
artifacts[]

object (Artifact)

工作的一組輸出構件。
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 鍵/值物件，用於儲存工作相關的自訂中繼資料。

TaskStatus

工作狀態的容器

JSON 表示法 
{
  "state": enum (TaskState),
  "message": {
    object (Message)
  },
  "timestamp": string
}
欄位
state

enum (TaskState)

這項工作的目前狀態
message

object (Message)

與狀態相關聯的訊息。
timestamp

string (Timestamp format)

記錄狀態的時間戳記。例如：「2023-10-27T10:00:00Z」

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

TaskState

工作可處於的狀態組合。

列舉
TASK_STATE_UNSPECIFIED
TASK_STATE_SUBMITTED 代表確認工作已建立的狀態
TASK_STATE_WORKING 代表工作正在處理中的狀態
TASK_STATE_COMPLETED 表示工作已完成的狀態。這是終端狀態
TASK_STATE_FAILED 表示工作已完成但失敗的狀態。這是終端狀態
TASK_STATE_CANCELLED 表示工作在完成前取消的狀態。這是終端機狀態。
TASK_STATE_INPUT_REQUIRED 表示工作需要資訊才能完成的狀態。這是中斷狀態。
TASK_STATE_REJECTED 代表代理程式已決定不執行工作。這可能是在工作建立初期完成，也可能是在代理程式判斷無法或不會繼續執行工作時完成。這是終止狀態。
TASK_STATE_AUTH_REQUIRED 表示上游用戶端需要進行驗證的狀態。驗證作業應會透過頻外方式進行，因此這並非中斷或終端狀態。

訊息

訊息是用戶端與伺服器之間的通訊單位，與內容和 (選用) 工作相關聯。由於伺服器負責定義內容，因此必須一律在訊息中提供 contextId。如果用戶端知道要將訊息與哪個內容建立關聯，可以選擇提供 contextId。taskId 也是如此，但伺服器會決定是否建立工作，以及是否要加入 taskId。

JSON 表示法 
{
  "messageId": string,
  "contextId": string,
  "taskId": string,
  "role": enum (Role),
  "content": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
欄位
messageId

string

訊息的專屬 ID (例如 UUID)。這是必要資訊，由訊息建立者提供。
contextId

string

訊息的內容 ID。這是選用項目，如果設定，訊息會與指定內容建立關聯。
taskId

string

訊息的工作 ID。這是選用設定，如果設定，系統會將訊息與指定工作建立關聯。
role

enum (Role)

訊息的角色。
content[]

object (Part)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Content 是訊息內容的容器。
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED 隨訊息提供的任何選用中繼資料。
extensions[]

string

存在於或貢獻給這個訊息的擴充功能 URI。

角色

列舉
ROLE_UNSPECIFIED
ROLE_USER 「USER」角色是指從用戶端到伺服器的通訊。
ROLE_AGENT 「AGENT」角色是指從伺服器到用戶端的通訊。

Part

Part 代表通訊內容區段的容器。部分可以是純文字、某種檔案 (圖片、影片等)，或結構化資料 Blob (即 JSON)。

JSON 表示法 
{
  "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.
}
欄位
metadata

object (Struct format)

與這個部分相關聯的選填中繼資料。

聯集欄位 part。

part 只能是下列其中一項：
text

string
file

object (FilePart)
data

object (DataPart)

FilePart

FilePart 代表檔案的各種提供方式。如果檔案很小，系統支援透過 fileWithBytes 直接提供位元組。如果檔案很大，代理程式應直接從 fileWithUri 來源適當讀取內容。

JSON 表示法 
{
  "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.
}
欄位
mimeType

string
name

string

聯集欄位 file。

file 只能是下列其中一項：
fileWithUri

string
fileWithBytes

string (bytes format)

Base64 編碼字串。

DataPart

DataPart 代表結構化 blob。最常見的是 JSON 酬載。

JSON 表示法 
{
  "data": {
    object
  }
}
欄位
data

object (Struct format)

構件

構件是工作完成結果的容器，類似於訊息，但目的是做為工作產品，而非點對點通訊。

JSON 表示法 
{
  "artifactId": string,
  "name": string,
  "description": string,
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
欄位
artifactId

string

構件的專屬 ID (例如 UUID)。至少在工作內不得重複。
name

string

構件的人類可讀名稱。
description

string

構件的說明，可供使用者閱讀，為選用項目。
parts[]

object (Part)

構件內容。
metadata

object (Struct format)

隨附於構件的選用中繼資料。
extensions[]

string

存在於或貢獻給這個構件的擴充功能 URI。

方法

cancel

 取消代理程式中的工作。

get

 從代理程式取得工作目前的狀態。

subscribe

 TaskSubscription 是串流呼叫，會傳回工作更新事件串流。