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

任务的唯一标识符（例如 UUID），由服务器为新任务生成。
contextId

string

交互（任务和消息）上下文集合的唯一标识符（例如 UUID）。由 A2A 服务器创建。
status

object (TaskStatus)

任务的当前状态，包括状态和消息。
artifacts[]

object (Artifact)

任务的一组输出制品。
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED 任务的互动历史记录。
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 规范化（即转换为 UTC 零时区格式并在末尾附加 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

消息的唯一标识符（例如 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 表示一段通信内容的容器。内容可以是纯文本、某种类型的文件（图片、视频等）或结构化数据 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

相应制品的唯一标识符（例如 UUID）。在任务中必须至少是唯一的。
name

string

制品的人类可读名称。
description

string

制品的人类可读说明（可选）。
parts[]

object (Part)

制品的内容。
metadata

object (Struct format)

工件中包含的可选元数据。
extensions[]

string

相应制品中存在或贡献的扩展程序的 URI。

方法

cancel

 取消代理中的任务。

get

 从代理获取任务的当前状态。

subscribe

 TaskSubscription 是一种流式调用，可返回任务更新事件流。