[A2A协议与实现-03]从Protobuf消息详解A2A协议四大核心操作

接下来我们将介绍A2A协议中定义的核心操作列表。这些操作构成了Agent之间交互的基础每个操作都对应一个特定的功能允许Agent以标准化的方式进行通信和协作。之前已经说过A2A协议的所有操作定义在A2AService这个gRPC服务中。我们将逐一介绍这些操作的功能和使用场景。1. Agent执行如下这两个方法SendMessage/SendStreamingMessage定义了A2A协议中最基本的通信机制。它们允许Agent之间以同步或流式的方式交换消息满足不同的响应速度和交互需求。service A2AService { rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) rpc SendStreamingMessage(SendMessageRequest) returns (stream StreamResponse)它们虽然请求参数相同SendMessageRequest但代表了两种完全不同的交互范式SendMessage: 同步请求-响应模式这是最基础的原子操作类似于我们平常使用的RESTful API调用。客户端发送一个请求服务器处理完成后一次性返回完整结果。适用场景低延迟指令比如查询当前天气非生成式任务不需要长时间等待的操作触发式逻辑仅仅是告知另一个Agent一个事实不需要后续复杂的对话SendStreamingMessage: 采用服务器流式响应这是针对LLM环境设计的关键接口。客户端发送一个请求单次但服务器会建立一个长连接持续不断地推送多个StreamResponse包直到任务结束。适用场景生成式LLM大模型逐个Token输出时用户需要实时看到文字蹦出来打字机效果而不是等30秒才看到整段话进度观察执行一个复杂任务如“分析这10个网页”每分析完一个就推送一条状态更新1.1 SendMessageRequest如下所示的SendMessageRequest作为两个操作的共同输入它定义了发送消息时需要提供的关键信息。这个请求对象不仅包含了消息的内容还包括了与租户、配置和元数据相关的信息以支持多租户环境下的安全通信和个性化交互。message SendMessageRequest { string tenant 1; Message message 2 [(google.api.field_behavior) REQUIRED]; SendMessageConfiguration configuration 3; google.protobuf.Struct metadata 4; }消息成员说明如下tenant可选字段表示发送消息的租户Tenant。在多租户环境中这个字段对于实现租户隔离和访问控制非常重要message必填字段包含了要发送的消息内容。这个Message对象定义了消息的结构包括消息ID、角色、内容部分等是整个通信的核心载体configuration可选字段包含了发送消息时的配置选项。这些配置可能包括优先级设置、超时设置、重试策略等允许发送方根据具体需求调整消息的处理方式metadata一个结构化的键值对集合用于携带与这个消息相关的上下文信息。这些信息可以用于路由、优先级设置、调试等目的增强消息的可用性和灵活性configuration字段的类型为SendMessageConfiguration它定义了A2A协议中发送消息时的配置参数。它不承载具体的聊天内容而是告诉接收Agent“我希望你怎么处理这个请求”以及“我希望返回什么样的结果”。message SendMessageConfiguration { repeated string accepted_output_modes 1; TaskPushNotificationConfig task_push_notification_config 2; optional int32 history_length 3; bool return_immediately 4; }消息成员说明如下accepted_output_modes一个字符串列表指明发送方希望接收的输出媒体类型。例如如果发送方只想要文本响应它可能会设置为[text/plain]如果它也能处理图像响应则可能设置为[text/plain, image/png]。这有助于接收Agent根据发送方的能力和偏好来生成适当格式的响应task_push_notification_config如果发送方希望在任务完成时接收推送通知可以通过这个字段提供相关配置。这允许Agent在处理完任务后主动通知发送方而不需要发送方一直等待连接history_length一个整数指明发送方希望接收的消息历史记录的长度。比如如果设置为5接收方在响应时会附带最近5条相关的消息历史这对于需要上下文理解的交互非常有用return_immediately一个布尔值指示发送方是否希望接收方立即返回响应而不是等待整个处理过程完成。如果设置为true接收方可以先返回一个确认消息例如任务已接受然后在后续的消息中提供处理结果。这对于需要快速反馈的交互非常有用基于任务的通知推送配置消息TaskPushNotificationConfig定义了当Agent完成一个任务时如何向发送方推送通知的相关信息。这使得Agent能够在处理完任务后主动通知发送方而不需要发送方一直等待连接。这个配置包含了必要的认证信息以确保推送通知的安全性和可靠性。message TaskPushNotificationConfig { string tenant 1; string id 2; string task_id 3; string url 4 [(google.api.field_behavior) REQUIRED]; string token 5; AuthenticationInfo authentication 6; }消息成员说明如下tenant可选字段表示接收推送通知的租户。在多租户环境中这个字段对于实现租户隔离和访问控制非常重要id推送通知配置的唯一标识符通常由发送方生成。它对于跟踪和管理推送通知非常重要task_id与推送通知相关联的任务ID。这允许发送方将收到的通知与特定的任务关联起来便于跟踪和管理url接收推送通知的URL。当Agent完成任务时它将向这个URL发送HTTP POST请求通知发送方任务的完成情况token用于验证推送通知的安全令牌。Agent在发送通知时会包含这个令牌接收方可以使用它来验证通知的真实性防止伪造的通知攻击authentication一个AuthenticationInfo对象包含了用于认证推送通知的相关信息。这可以包括认证方案如Bearer Token、OAuth2等和相关的凭证信息确保推送通知的安全传输AuthenticationInfo消息定义如下它包含了用于认证推送通知的相关信息。这可以包括认证方案如Bearer Token、OAuth2等和相关的凭证信息确保推送通知的安全传输。message AuthenticationInfo { string scheme 1 [(google.api.field_behavior) REQUIRED]; string credentials 2; }1.2 SendMessageResponse我们前面重点讨论过A2A服务端是返回Message还是Task对象的设计选择这体现在SendMessage方法的返回类型SendMessageResponse上。SendMessageResponse的核心是一个oneof字段允许它在同一结构中返回两种完全不同类型的结果一个是Task对象另一个是Message对象。这种设计使得A2A协议能够适应不同的交互需求无论是简单的消息回复还是复杂的任务管理。message SendMessageResponse { oneof payload { Task task 1; Message message 2; } }1.3 StreamResponse采用流式响应的SendStreamingMessage方法返回一个针对StreamResponse对象的异步生成器。从这个Protobuf消息的定义上看响应的内容四种形式Message、Task和针对Task状态和Artifact更新的事件。message StreamResponse { oneof payload { Task task 1; Message message 2; TaskStatusUpdateEvent status_update 3; TaskArtifactUpdateEvent artifact_update 4; } }消息成员说明如下task发送当前任务的全量状态。通常在流开始时发送一次或在任务发生重大变更时发送让客户端同步整个任务对象的最新信息message发送一条完整的消息。例如Agent的一句回答或者一个最终生成的文本段落status_update当任务的状态发生变化时Agent会发送一个TaskStatusUpdateEvent事件。这允许发送方实时跟踪任务的进展例如从pending到in_progress再到completedartifact_update当任务生成新的产出物Artifact时Agent会发送一个TaskArtifactUpdateEvent事件。这使得发送方能够及时获取任务的中间结果或最终成果TaskStatusUpdateEvent消息定义如下它表示当任务的状态发生变化时Agent会发送一个事件这是任务的进度条和信号灯。message TaskStatusUpdateEvent { string task_id 1 [(google.api.field_behavior) REQUIRED]; string context_id 2 [(google.api.field_behavior) REQUIRED]; TaskStatus status 3 [(google.api.field_behavior) REQUIRED]; google.protobuf.Struct metadata 4; }消息成员说明如下context_id与任务相关联的上下文标识符。这允许多个任务共享相同的上下文信息促进协作和状态管理final一个布尔值指示这个状态更新是否是最终的状态更新。如果为true表示任务已经进入了一个终止状态如completed、failed、canceled等后续不会再有状态更新kind一个字符串常量指明这个事件的类型。在这里它被设置为status-update以便接收方能够识别这是一个任务状态更新事件metadata一个结构化的键值对集合用于携带与这个状态更新相关的上下文信息。这些信息可以用于分类、搜索、调试等目的增强事件的可用性和灵活性status一个TaskStatus对象包含了任务当前的状态信息。这是事件的核心内容接收方可以通过这个字段了解任务的最新状态task_id与这个状态更新相关联的任务ID。这允许发送方将收到的状态更新与特定的任务关联起来便于跟踪和管理TaskArtifactUpdateEvent消息定义如下它表示当任务生成新的产出物Artifact时Agent会发送一个事件它实现了产出物增量交付这是任务的成果展示。message TaskArtifactUpdateEvent { string task_id 1 [(google.api.field_behavior) REQUIRED]; string context_id 2 [(google.api.field_behavior) REQUIRED]; Artifact artifact 3 [(google.api.field_behavior) REQUIRED]; bool append 4; bool last_chunk 5; google.protobuf.Struct metadata 6; }消息成员说明如下append一个可选的布尔值指示这个Artifact是否应该被追加到之前发送的Artifact上。如果为True表示这是一个增量更新接收方应该将这个Artifact与之前的Artifact合并如果为false或未设置表示这是一个新的Artifact接收方可以替换之前的Artifactartifact一个Artifact对象包含了任务生成的新的产出物。这是事件的核心内容接收方可以通过这个字段获取任务的最新成果context_id与任务相关联的上下文标识符。这允许多个任务共享相同的上下文信息促进协作和状态管理kind一个字符串常量指明这个事件的类型。在这里它被设置为artifact-update以便接收方能够识别这是一个任务产出物更新事件last_chunk一个可选的布尔值指示这个Artifact是否是最后一块数据。当Agent分块发送一个大型Artifact时这个字段可以帮助接收方知道何时已经接收完全部数据metadata一个结构化的键值对集合用于携带与这个Artifact更新相关的上下文信息。这些信息可以用于分类、搜索、调试等目的增强事件的可用性和灵活性task_id与这个Artifact更新相关联的任务ID。这允许发送方将收到的Artifact更新与特定的任务关联起来便于跟踪和管理2. 任务管理由于Agent执行大概率下是一个长耗时任务所以当我们以A2A协议执行目标Agent时基本会返回一个Task对象。这个Task对象会有一个唯一的ID客户端可以通过这个ID来跟踪任务的状态、获取任务的产出物甚至在必要时取消任务。A2A协议定义了一套完整的任务管理操作允许客户端对任务进行全面的控制和监控。这些操作包括service A2AService { rpc GetTask(GetTaskRequest) returns (Task) rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) rpc CancelTask(CancelTaskRequest) returns (Task) rpc SubscribeToTask(SubscribeToTaskRequest) returns (stream StreamResponse) }四个方法的功能如下GetTask根据任务ID获取当前任务的详细信息包括状态、产出物和历史记录等。这对于跟踪任务进展和获取结果非常重要ListTasks列出与特定上下文相关的所有任务。这对于管理和监控多个任务非常有用尤其是在复杂的工作流中CancelTask取消一个正在执行的任务。这对于处理错误、调整计划或响应用户的取消请求非常重要SubscribeToTask订阅一个任务的状态和产出物更新。这是一个流式接口允许客户端实时接收任务的进度和结果更新非常适合长时间运行的任务2.1 提取任务用于提取指定任务的GetTask方法的请求对象GetTaskRequest定义如下。除了指定租户和任务ID之外它还包含一个可选的history_length字段允许客户端指定希望获取的消息历史记录的长度。这对于需要上下文理解的交互非常有用。message GetTaskRequest { string tenant 1; string id 2 [(google.api.field_behavior) REQUIRED]; optional int32 history_length 3; }2.2 任务检索ListTasks方法的请求对象ListTasksRequest定义如下。它允许客户端根据上下文ID和可选的状态过滤条件来检索相关的任务列表。这对于管理和监控多个任务非常有用尤其是在复杂的工作流中。message ListTasksRequest { string tenant 1; string context_id 2; TaskState status 3; optional int32 page_size 4; string page_token 5; optional int32 history_length 6; google.protobuf.Timestamp status_timestamp_after 7; optional bool include_artifacts 8; }消息成员说明如下tenant可选字段表示检索任务的租户。在多租户环境中这个字段对于实现租户隔离和访问控制非常重要context_id可选字段表示与任务相关联的上下文标识符。这允许客户端根据特定的上下文来过滤任务便于管理和监控相关的任务集合status可选字段表示任务的状态过滤条件。客户端可以指定一个TaskState来检索处于特定状态的任务例如pending、in_progress、completed等page_size可选字段表示每页返回的任务数量。这对于分页显示任务列表非常有用尤其是在任务数量较多的情况下page_token可选字段表示分页的标记。客户端可以使用这个字段来请求下一页的任务列表以实现分页浏览history_length可选字段表示希望获取的消息历史记录的长度。这对于需要上下文理解的交互非常有用允许客户端在检索任务时同时获取相关的消息历史status_timestamp_after可选字段表示只检索状态更新时间在指定时间之后的任务。这对于监控最近发生状态变化的任务非常有用include_artifacts可选字段表示是否在响应中包含任务的产出物Artifact。如果设置为true响应将包含与每个任务相关联的产出物信息如果设置为false或未设置响应将不包含产出物信息这可以减少响应的大小和复杂性作为ListTasks的响应消息ListTasksResponse除了包含一个Task对象的列表之外还包含了分页相关的信息如下一页的token、当前页的大小以及总任务数量等。这些信息对于客户端实现分页浏览和管理大量任务非常有用。message ListTasksResponse { repeated Task tasks 1 [(google.api.field_behavior) REQUIRED]; string next_page_token 2 [(google.api.field_behavior) REQUIRED]; int32 page_size 3 [(google.api.field_behavior) REQUIRED]; int32 total_size 4 [(google.api.field_behavior) REQUIRED]; }2.3 任务取消客户端Agent可以通过调用CancelTask方法来取消一个正在执行的任务。这是A2A协议中用于干预任务生命周期的关键方法。它不仅是一个简单的停止信号在分布式Agent协作中还承载着状态一致性的职责。CancelTask方法的请求对象CancelTaskRequest定义如下。它包含了租户信息和要取消的任务ID。message CancelTaskRequest { string tenant 1; string id 2 [(google.api.field_behavior) REQUIRED]; google.protobuf.Struct metadata 3; }CancelTask方法的响应类型是Task对象表示取消操作后的任务状态。通常情况下任务的状态会变为canceled但具体行为可能因Agent的实现而异例如有些Agent可能会在取消后执行一些清理工作或发送通知。2.4 任务订阅SubscribeToTask方法允许客户端Agent订阅一个任务的状态和产出物更新。这是A2A协议中实现实时异步监控的核心方法。它的作用是让客户端能够重新挂接到一个正在进行的任务上实时接收进度更新。这是一个流式接口客户端发送一个订阅请求后服务器会持续推送与该任务相关的更新直到任务完成或订阅被取消。SubscribeToTaskRequest定义如下。它包含了租户信息、要订阅的任务ID。message SubscribeToTaskRequest { string tenant 1; string id 2 [(google.api.field_behavior) REQUIRED]; }订阅的效果体现在方法返回的针对StreamResponse对象的异步生成器上。意味着它和前面介绍SendStreamingMessage方法一样可以实时获得如下四种响应结果task发送当前任务的全量状态。通常在流开始时发送一次或在任务发生重大变更时发送让客户端同步整个任务对象的最新信息message发送一条完整的消息。例如Agent的一句回答或者一个最终生成的文本段落status_update当任务的状态发生变化时Agent会发送一个TaskStatusUpdateEvent事件。这允许发送方实时跟踪任务的进展例如从pending到in_progress再到completedartifact_update当任务生成新的产出物Artifact时Agent会发送一个TaskArtifactUpdateEvent事件。这使得发送方能够及时获取任务的中间结果或最终成果3. 推送通知配置管理由于Agent执行是一个长耗时任务执行几小时设置几天都有可能所以采用长连接来等待任务完成的结果并不现实。A2A协议提供了推送通知机制允许Agent在任务完成时主动通知发送方而不需要发送方一直等待连接。在这种情况下我们需要提供一个用于接收和处理的Endpoint并通过TaskPushNotificationConfig对象与任务关联起来。除了提供作为Webhook的URL之外这个TaskPushNotificationConfig还提供认证信息以确保推送通知的安全性和可靠性。同一个任务可以关联多个TaskPushNotificationConfig对象以支持向多个Endpoint发送通知。对于两个核心方法SendMessage/SendStreamingMessage公共的请求类型SendMessageRequest它的configuration字段返回的SendMessageConfiguration配置就包含一个TaskPushNotificationConfig对象。如果没有通过这两个方法任务的TaskPushNotificationConfig进行设置我们也可以事后补救——通过调用CreateTaskPushNotificationConfig方法来创建一个新的推送通知配置并将其关联到一个特定的任务上。除了这个CreateTaskPushNotificationConfig方法之外A2A协议还定义了GetTaskPushNotificationConfig、ListTaskPushNotificationConfigs和DeleteTaskPushNotificationConfig方法允许客户端Agent对推送通知配置进行全面的管理。service A2AService { rpc CreateTaskPushNotificationConfig(TaskPushNotificationConfig) returns (TaskPushNotificationConfig) rpc GetTaskPushNotificationConfig(GetTaskPushNotificationConfigRequest) returns (TaskPushNotificationConfig) rpc ListTaskPushNotificationConfigs(ListTaskPushNotificationConfigsRequest) returns (ListTaskPushNotificationConfigsResponse) rpc DeleteTaskPushNotificationConfig(DeleteTaskPushNotificationConfigRequest) returns (google.protobuf.Empty) }3.1 创建推送通知配置我们在调用CreateTaskPushNotificationConfig方法时需要提供一个TaskPushNotificationConfig对象作为请求参数。这个对象包含了推送通知的相关配置例如接收通知的URL、认证信息等。服务器会根据这个配置创建一个新的推送通知配置并返回给我们一个完整的TaskPushNotificationConfig对象其中包含了服务器生成的唯一ID等信息。message TaskPushNotificationConfig { string tenant 1; string id 2; string task_id 3; string url 4 [(google.api.field_behavior) REQUIRED]; string token 5; AuthenticationInfo authentication 6; }3.2 获取推送通知配置虽然每个TaskPushNotificationConfig对象都有一个唯一的ID但由于该对象是附加到一个具体的Task的配置所以具体的实现一般会基于Task进行存储当我们调用GetTaskPushNotificationConfig方法时指定的GetTaskPushNotificationConfigRequest请求对象中既包含了推送通知配置的ID也包含了与该配置相关联的任务ID。方法返回的TaskPushNotificationConfig对象则包含了完整的推送通知配置信息。message GetTaskPushNotificationConfigRequest { string tenant 1; string task_id 2 [(google.api.field_behavior) REQUIRED]; string id 3 [(google.api.field_behavior) REQUIRED]; }3.3 推送通知配置的检索我们可以调用ListTaskPushNotificationConfigs方法列出某个Task关联的所有推送通知配置。作为该方法输入的ListTaskPushNotificationConfigsRequest请求对象中包含了与推送通知配置相关的任务ID以及分页相关的信息如page_size和page_token。方法返回一个ListTaskPushNotificationConfigsResponse对象其中包含了与该任务关联的所有推送通知配置的列表以及分页信息。message ListTaskPushNotificationConfigsRequest { string tenant 4; string task_id 1 [(google.api.field_behavior) REQUIRED]; int32 page_size 2; string page_token 3; } message ListTaskPushNotificationConfigsResponse { repeated TaskPushNotificationConfig configs 1; string next_page_token 2; }3.4 删除推送通知配置如果我们不再需要某个推送通知配置可以调用DeleteTaskPushNotificationConfig方法来删除它。作为该方法输入的DeleteTaskPushNotificationConfigRequest与GetTaskPushNotificationConfigRequest具有相同的结构包含了与推送通知配置相关的任务ID和配置ID。方法执行成功后该推送通知配置将被删除并且服务器会返回一个空响应。message DeleteTaskPushNotificationConfigRequest { string tenant 1; string task_id 2 [(google.api.field_behavior) REQUIRED]; string id 3 [(google.api.field_behavior) REQUIRED]; }4. AgentCard扩展我们在前面介绍A2A协议的AgentCard消息类型时提到过它有一个重要的字段capabilities返回一个AgentCapabilities对象。AgentCapabilities定义了Agent的功能清单后者的extended_agent_card字段则表明该Agent是否支持在身份验证后提供扩展AgentCard片。扩展AgentCard片通常用于展示更详细的身份信息、专有工具集或品牌展示。为了隐私保护这些丰富的信息只有在对方通过身份验证后才会展示。message AgentCard { ... AgentCapabilities capabilities 7 ; ... } message AgentCapabilities { ... optional bool extended_agent_card 4; }如果一个Agent的AgentCard中capabilities字段的extended_agent_card为true那么在身份验证成功后另一个Agent就可以通过调用GetAgentCard方法来获取这个Agent的扩展AgentCard信息。扩展AgentCard的内容可以根据具体实现而有所不同但通常会包含更丰富的描述、工具列表、联系方式等信息以便于增强Agent之间的协作和信任建立。作为输入的GetExtendedAgentCardRequest请求对象中包含了租户信息以确保只有经过适当认证的Agent才能访问扩展AgentCard的信息。service A2AService { rpc GetExtendedAgentCard(GetExtendedAgentCardRequest) returns (AgentCard) } message GetExtendedAgentCardRequest { string tenant 1; }