AI Agent协议A2A交互细节详解

概要

谷歌面向多Agent场景，发布了A2A协议（Agent2Agent），该协议将使 AI Agents 能够相互通信，安全地交换信息，并在各种企业平台或应用程序之上协调行动。本文是之前一篇文章的细节补充。

示例方法和 JSON 响应

以下是整个交互过程的详细示例说明。

AgentCard

{
"name":"谷歌地图代理",
"description":"规划路线、记住地点并生成导航",
"url":"https://maps-agent.google.com",
"provider":{
    "organization":"Google",
    "url":"https://google.com"
},
"version":"1.0.0",
"authentication":{
    "schemes":"OAuth2"
},
"defaultInputModes":["text/plain"],
"defaultOutputModes":["text/plain","application/html"],
"capabilities":{
    "streaming":true,
    "pushNotifications":false
},
"skills":[
    {
      "id":"route-planner",
      "name":"路线规划",
      "description":"帮助规划两个地点之间的路线",
      "tags":["地图","路线","导航"],
      "examples":[
        "规划从桑尼维尔到山景城的路线",
        "上午9点从桑尼维尔到旧金山的通勤时间是多少",
        "创建从桑尼维尔到山景城的逐转导航"
      ],
      "outputModes":["application/html","video/mp4"]
    },
    {
      "id":"custom-map",
      "name":"我的地图",
      "description":"管理带有您保存地点的自定义地图",
      "tags":["自定义地图","保存地点"],
      "examples":[
        "在地图上显示我最喜欢的餐厅",
        "创建我过去一年访问过的所有地点的可视化"
      ],
      "outputModes":["application/html"]
    }
]
}

发送任务

允许客户端向远程代理发送内容以启动新任务、恢复中断的任务或重新打开已完成的任务。任务中断可能是由于代理需要额外用户输入或运行时错误导致。

// 请求
{
"jsonrpc":"2.0",
"id":1,
"method":"tasks/send",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "message":{
      "role":"user",
      "data":[{
        "type":"text",
        "text":"告诉我一个笑话"
      }]
    },
    "metadata":{}
}
}
// 响应
{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"completed"
    },
    "artifacts":[{
      "name":"joke",
      "parts":[{
        "type":"text",
        "text":"为什么鸡要过马路？因为想到另一边去！"
      }]
    }],
    "metadata":{}
}
}

获取任务

客户端可以使用此方法检索任务生成的产物。代理决定先前提交任务的保留窗口。代理可能对超过保留窗口的任务或代理未持久化的短暂任务返回错误代码。
客户端还可以请求任务的最后 N 项历史记录，包括客户端和服务器按顺序发送的所有消息。默认值为 0（无历史）。

// 请求
{
"jsonrpc":"2.0",
"id":1,
"method":"tasks/get",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "historyLength":10,
    "metadata":{}
}
}
// 响应
{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"completed"
    },
    "artifacts":[{
      "parts":[{
        "type":"text",
        "text":"为什么鸡要过马路？因为想到另一边去！"
      }]
    }],
    "history":[
      {
        "role":"user",
        "parts":[
          {
            "type":"text",
            "text":"告诉我一个笑话"
          }
        ]
      }
    ],
    "metadata":{}
}
}

取消任务

客户端可以选择取消先前提交的任务，如下所示。

// 请求
{
"jsonrpc":"2.0",
"id":1,
"method":"tasks/cancel",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "metadata":{}
}
}
// 响应
{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"canceled"
    },
    "metadata":{}
}
}

设置任务推送通知

客户端可以为任务状态更改配置推送通知 URL 以接收更新。

// 请求
{
"jsonrpc":"2.0",
"id":1,
"method":"tasks/pushNotification/set",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "pushNotificationConfig":{
      "url":"https://example.com/callback",
      "authentication":{
        "schemes":["jwt"]
      }
    }
}
}
// 响应
{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "pushNotificationConfig":{
      "url":"https://example.com/callback",
      "authentication":{
        "schemes":["jwt"]
      }
    }
}
}

获取任务推送通知

客户端可以使用此方法检索任务当前配置的推送通知配置。

// 请求
{
"jsonrpc":"2.0",
"id":1,
"method":"tasks/pushNotification/get",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64"
}
}
// 响应
{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "pushNotificationConfig":{
      "url":"https://example.com/callback",
      "authentication":{
        "schemes":["jwt"]
      }
    }
}
}

多轮对话

如果远程代理需要额外的用户输入，任务可能会暂停执行。当任务处于“需要输入”状态时，客户端需要提供额外输入以使任务在远程代理上恢复处理。
“需要输入”状态中包含的消息必须包括指示客户端必须执行的操作的细节。例如“填写表格”或“登录到 SaaS 服务 foo”。如果包括结构化数据，指令应作为一个部分发送，结构化数据作为第二个部分发送。

// 请求 - 序列 1
{
"jsonrpc":"2.0",
"id":1,
"method":"tasks/send",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "message":{
      "role":"user",
      "parts":[{
        "type":"text",
        "text":"为我购买一部新手机"
      }]
    },
    "metadata":{}
}
}
// 响应 - 序列 2
{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"input-required",
      "message":{
        "parts":[{
          "type":"text",
          "text":"选择手机类型（iPhone/Android）"
        }]
      }
    },
    "metadata":{}
}
}
// 请求 - 序列 3
{
"jsonrpc":"2.0",
"id":2,
"method":"tasks/send",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "message":{
      "role":"user",
      "parts":[{
        "type":"text",
        "text":"Android"
      }]
    },
    "metadata":{}
}
}
// 响应 - 序列 4
{
"jsonrpc":"2.0",
"id":2,
"result":{
    "id":1,
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"completed"
    },
    "artifacts":[{
      "name":"order-confirmation",
      "parts":[{
        "type":"text",
        "text":"我已经为您订购了一台新的 Android 设备。您的请求编号是 R12443"
      }],
      "metadata":{}
    }],
    "metadata":{}
}
}

流式支持

对于能够通过 HTTP 使用 SSE 通信的客户端和远程代理，客户端可以在创建新任务时发送带有方法 tasks/sendSubscribe 的 RPC 请求。远程代理可以响应一系列 TaskStatusUpdateEvents（用于传达状态更改或指令/请求）和 TaskArtifactUpdateEvents（用于流式传输生成的结果）。注意，TaskArtifactUpdateEvents 可以将新部分附加到现有产物上。客户端可以使用 task/get 在流式传输之外检索整个产物。代理必须在流结束时或代理中断并需要额外用户输入时设置 final: true 属性。

// 请求
{
"method":"tasks/sendSubscribe",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "message":{
      "role":"user",
      "parts":[{
        "type":"text",
        "text":"写一篇长文描述附带的图片"
      },{
        "type":"file",
        "file":{
          "mimeType":"image/png",
          "data":"<base64-encoded-content>"
        }
      }]
    },
    "metadata":{}
}
}

// 响应
data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "status":{
      "state":"working",
      "timestamp":"2025-04-02T16:59:25.331844"
    },
    "final":false
}
}

data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "artifact":[
      "parts":[
        {"type":"text","text":"<section 1...>"}
      ],
      "index":0,
      "append":false,
      "lastChunk":false
    ]
}
}
data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "artifact":[
      "parts":[
        {"type":"text","text":"<section 2...>"}
      ],
      "index":0,
      "append":true,
      "lastChunk":false
    ]
}
}
data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "artifact":[
      "parts":[
        {"type":"text","text":"<section 3...>"}
      ],
      "index":0,
      "append":true,
      "lastChunk":true
    ]
}
}

data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "status":{
      "state":"completed",
      "timestamp":"2025-04-02T16:59:35.331844"
    },
    "final":true
}
}

重新订阅任务

断开连接的客户端可以重新订阅支持流式传输的远程代理，以通过 SSE 接收任务更新。

// 请求
{
"method":"tasks/resubscribe",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "metadata":{}
}
}
// 响应
data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "artifact":[
      "parts":[
        {"type":"text","text":"<section 2...>"}
      ],
      "index":0,
      "append":true,
      "lastChunk":false
    ]
}
}
data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "artifact":[
      "parts":[
        {"type":"text","text":"<section 3...>"}
      ],
      "index":0,
      "append":true,
      "lastChunk":true
    ]
}
}

data:{
"jsonrpc":"2.0",
"id":1,
"result":{
    "id":1,
    "status":{
      "state":"completed",
      "timestamp":"2025-04-02T16:59:35.331844"
    },
    "final":true
}
}

非文本媒体

以下是客户端与代理之间使用非文本数据的示例交互。

// 请求 - 序列 1
{
"jsonrpc":"2.0",
"id":9,
"method":"tasks/send",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "message":{
      "role":"user",
      "parts":[{
        "type":"text",
        "text":"分析附带的报告并生成高级概述"
      },{
        "type":"file",
        "file":{
          "mimeType":"application/pdf",
          "data":"<base64-encoded-content>"
        }
      }]
    },
    "metadata":{}
}
}
// 响应 - 序列 2
{
"jsonrpc":"2.0",
"id":9,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"working",
      "message":{
        "role":"agent",
        "parts":[{
          "type":"text",
          "text":"分析进行中，请稍候"
        }],
        "metadata":{}
      }
    },
    "metadata":{}
}
}
// 请求 - 序列 3
{
"jsonrpc":"2.0",
"id":10,
"method":"tasks/get",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "metadata":{}
}
}
// 响应 - 序列 4
{
"jsonrpc":"2.0",
"id":9,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"completed"
    },
    "artifacts":[{
      "parts":[{
        "type":"text",
        "text":"<生成分析内容>"
      }],
      "metadata":{}
    }],
    "metadata":{}
}
}

结构化输出

客户端或代理都可以请求对方的结构化输出。

// 请求
{
"jsonrpc":"2.0",
"id":9,
"method":"tasks/send",
"params":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "message":{
      "role":"user",
      "parts":[{
        "type":"text",
        "text":"显示我未关闭的 IT 工单列表",
        "metadata":{
          "mimeType":"application/json",
          "schema":{
            "type":"array",
            "items":{
              "type":"object",
              "properties":{
                "ticketNumber":{"type":"string"},
                "description":{"type":"string"}
              }
            }
          }
        }
      }]
    },
    "metadata":{}
}
}
// 响应
{
"jsonrpc":"2.0",
"id":9,
"result":{
    "id":"de38c76d-d54c-436c-8b9f-4c2703648d64",
    "sessionId":"c295ea44-7543-4f78-b524-7a38915ad6e4",
    "status":{
      "state":"working",
      "message":{
        "role":"agent",
        "parts":[{
          "type":"text",
          "text":"[{\"ticketNumber\":\"REQ12312\",\"description\":\"请求 VPN 访问权限\"},{\"ticketNumber\":\"REQ23422\",\"description\":\"添加到 DL - team-gcp-onboarding\"}]"
        }],
        "metadata":{}
      }
    },
    "metadata":{}
}
}

错误处理

以下是服务器在处理客户端请求时遇到错误时响应客户端的错误消息格式。

interface ErrorMessage {
  code: number;
  message: string;
  data?: any;
}

以下是服务器在错误场景下可以响应的标准 JSON-RPC 错误代码：