AP2 的 A2A 扩展

!!! info

这是 [Agent2Agent (A2A) 扩展](https://a2a-protocol.org/latest/topics/extensions/)，实现了代理支付协议（AP2）。

`v0.1-alpha`（参见[路线图](roadmap.md)）

扩展 URI

本扩展的 URI 为
https://github.com/google-agentic-commerce/ap2/tree/v0.1。

支持 AP2 扩展的代理必须使用该 URI。

代理 AP2 角色

任何支持 AP2 扩展的代理必须至少承担 AP2 规范中的一种角色。该角色在 AgentCard 中声明。

AgentCard 扩展对象

支持 AP2 扩展的代理必须通过上述扩展 URI 在 AgentCard 中声明其支持。

AgentExtension 中的 params 必须符合以下 JSON 模式：

{
  "type": "object",
  "name": "AP2ExtensionParameters",
  "description": "AP2 A2A 扩展中 AgentExtension.params 的参数模式。",
  "properties": {
    "roles": {
      "type": "array",
      "name": "AP2 角色",
      "description": "该代理在 AP2 模型中承担的角色。",
      "minItems": 1,
      "items": {
        "enum": ["merchant", "shopper", "credentials-provider", "payment-processor"]
      }
    }
  },
  "required": ["roles"]
}

该模式也可由以下 Pydantic 类型定义表示：

AP2Role = "merchant" | "shopper" | "credentials-provider" | "payment-processor"

class AP2ExtensionParameters(BaseModel):
  # 该代理在 AP2 模型中承担的角色，至少需要一个值。
  roles: list[AP2Role] = Field(..., min_length=1)

承担 "merchant" 角色的代理应将 AP2 扩展设为必需，表明客户端必须能够使用 AP2 扩展来支付该代理提供的服务。

以下示例展示了一个声明支持 AP2 扩展的 AgentCard：

{
  "name": "Travel Agent",
  "description": "该代理可为用户预订度假所需的所有环节",
  "capabilities": {
    "extensions": [
      {
        "uri": "https://github.com/google-agentic-commerce/ap2/tree/v0.1",
        "description": "该代理可代用户支付预订费用",
        "params": {
          "roles": ["shopper"]
        }
      }
    ]
  },
  "skills": [
    {
      "id": "plan_vacation",
      "name": "Plan Vacation",
      "description": "规划一次有趣的度假，生成完整行程",
      "tags": []
    },
    {
      "id": "book_itinerary",
      "name": "Book Itinerary",
      "description": "为行程中的所有环节（航班、酒店、租车、餐厅等）下单预订",
      "tags": []
    }
  ]
}

AP2 数据类型容器

以下各节说明如何将 AP2 数据类型封装进 A2A 数据类型。

IntentMandate 消息

要提供 IntentMandate，代理必须创建一条 IntentMandate 消息。IntentMandate 消息是 A2A Message 的一种配置文件，需满足以下要求：

消息必须包含一个 DataPart，其键为 ap2.mandates.IntentMandate，值符合 IntentMandate 模式。

消息可包含一个 DataPart，其键为 risk_data，值包含实现自定义的风险信号。

以下示例展示了 IntentMandate 消息的 JSON 表示：

{
  "messageId": "e0b84c60-3f5f-4234-adc6-91f2b73b19e5",
  "contextId": "sample-payment-context",
  "taskId": "sample-payment-task",
  "role": "user",
  "parts": [
    {
      "kind": "data",
      "data": {
        "ap2.mandates.IntentMandate": {
          "user_cart_confirmation_required": false,
          "natural_language_description": "I'd like some cool red shoes in my size",
          "merchants": null,
          "skus": null,
          "required_refundability": true,
          "intent_expiry": "2025-09-16T15:00:00Z"
        }
      }
    }
  ]
}

CartMandate 工件

要发起支付请求，商户代理必须生成一个 CartMandate 工件。Cart