← 返回文章列表

调用网站 API 的 A2A 代理

A2A 代理让一个 AI 系统能够发现另一个 AI 系统，将任务交给它，并获得结构化结果。如果这种代理可以调用 网站 API，它就能参与真正的业务流程，例如检查库存、创建申请、计算报价、更新订单状态或收集报告数据。

  • A2A - 代理之间进行通信的协议
  • 网站 API - 访问数据和业务操作的受控入口
  • Agent Card - 代理能力和连接方式的说明
  • Task - 具有状态、结果和执行记录的任务
  • 核心原则 - 代理只能调用获准的业务操作，而不是任意 URL

什么是 A2A

A2A，也就是 Agent2Agent，用于连接相互独立的代理。一个代理作为客户端，另一个代理发布自己的能力并执行任务。它们可以使用不同的编程语言、模型和基础设施。

典型流程如下:

  1. 客户端代理接收用户请求。
  2. 它通过 Agent Card 找到合适的远程代理。
  3. 创建任务并传递上下文。
  4. 远程代理调用网站 API。
  5. 结果以消息或 artifact 的形式返回。

A2A 负责代理之间的通信，API 负责提供网站功能。这两个层次相互补充，但不能彼此替代。

为什么代理需要网站 API

没有 API 时，代理通常只能处理文本、搜索文档，或者使用不稳定的界面自动化。API 提供可预测的契约，让代理不需要模拟点击也能执行操作。

常见操作包括:

  • 搜索产品、服务和内容;
  • 计算价格、交付时间或套餐;
  • 创建线索、申请或订单;
  • 查询支付和配送状态;
  • 更新资料或预约;
  • 授权后获取个性化结果。

例如，咨询代理可以向网站代理提出任务: "为 20 人的团队查找可用套餐"。网站代理通过内部 API 检查当前规则，然后返回结构化选项。

集成架构

实用的架构包含五个部分:

组件 职责
客户端代理 理解用户意图并选择执行者
A2A 服务器 接收任务、消息和状态查询
工具层 将代理意图转换为具体调用
网站 API 检查权限、验证数据并执行操作
审计层 安全保存调用和结果记录

不要给模型提供 request(url, method, body) 这样的通用工具。更安全的方式是定义范围明确的函数:

search_products(query, filters)
calculate_quote(product_id, quantity)
create_lead(name, contact, consent)
get_order_status(order_id)

这样更容易限制权限、验证参数、测试功能和审计行为。

Agent Card 和能力说明

Agent Card 帮助客户端了解代理能够完成哪些任务。通常包含名称、说明、URL、支持的身份验证方式和 skills 列表。

skill 的描述应该具体。"可以操作网站"几乎没有参考价值。更好的说明是: "搜索商品目录、计算报价，并在用户确认后创建申请"。

不要在 Agent Card 中公开:

  • API key 或内部 token;
  • 私有服务地址;
  • 有助于绕过授权的细节;
  • 不向外部客户端开放的操作。

身份验证和权限

A2A 连接和网站 API 调用可以使用不同的凭据。代理需要证明自己的身份，API 则需要确定操作是代表谁执行的。

常见的三种模式:

  1. 服务账号 - 适合共享数据和后台操作。
  2. 用户委托访问 - 适合订单、个人资料和个人数据。
  3. 需要确认的操作 - 代理准备操作，用户确认后才写入。

权限应按照 endpoint、HTTP 方法、用户和数据类型进行限制。拥有商品目录读取权限，不应该自动获得修改价格或删除订单的权限。

调用安全

主要风险包括指令注入、错误参数、数据泄露和重复执行。

最低安全措施:

  • 使用严格 schema 验证输入;
  • 通过 allowlist 限制允许的操作;
  • 不在 prompt 和 A2A 消息中传递 secret;
  • 创建和支付操作使用 idempotency key;
  • 限制调用频率和成本;
  • 金融操作和不可逆操作需要确认;
  • 在日志中屏蔽个人数据和 token;
  • 只向代理返回必要的响应字段。

来自用户和其他代理的文本都应该被视为不可信输入。即使文档中的指令非常有说服力，也绝不能扩大工具的权限。

同步任务和长时间任务

搜索和计算通常可以立即返回。导入、大型报告或订单处理可能需要几分钟。此时可以使用 submitted、working、completed、failed 和 canceled 等状态。

客户端可以通过事件流、webhook 或轮询状态获得更新。重新连接时不能再次启动同一个业务操作。

错误和可观测性

代理需要清晰的结果，而不是原始 stack trace，例如服务暂时不可用、参数无效、访问被拒绝或需要确认。内部细节应保存在受保护的日志中。

诊断时建议记录:

  • task、session 和用户标识符;
  • 调用的工具名称;
  • 经过安全处理的参数副本;
  • API 响应 code 和执行时间;
  • 确认状态;
  • 代理和工具 schema 的版本。

这样可以区分模型错误、API 错误、网络问题和业务规则问题。

实施计划

  1. 选择一个价值可衡量的场景。
  2. 定义范围明确的 API 契约和数据 schema。
  3. 创建独立工具，而不是提供通用 HTTP 访问。
  4. 添加身份验证、限制和审计。
  5. 发布包含准确 skills 说明的 Agent Card。
  6. 测试错误、重试、取消和恶意输入。
  7. 先使用 read-only 或草稿模式。
  8. 分析真实日志后再开放写入操作。

总结

能够访问网站 API 的 A2A 代理 可以把外部 AI 系统连接到真实的业务服务。可靠的集成依赖范围明确的工具、严格的 schema、有限权限、操作确认和审计能力，而不是让模型拥有无限自由。

如果你希望将 A2A 代理连接到网站 API - 联系我。

常见问题

A2A 与普通 REST API 有什么区别？

REST API 描述应用程序的操作，而 A2A 负责代理之间的通信和任务生命周期。 A2A 可以使用 REST 或其他传输方式，之后代理再通过受控工具调用网站 API。

如果代理已经可以调用 API，还需要 A2A 吗？

不一定。 对于单个内部代理，直接调用 API 可能已经足够。当多个独立代理需要相互发现、委托任务并通过统一协议交换结果时，A2A 更有价值。

可以给代理一个通用 HTTP 客户端吗？

技术上可以，但在生产环境中风险很高。 具有 allowlist、schema 和独立权限的专用函数更容易保护、测试和审计。

如何避免重复创建订单？

使用 idempotency key，并保存 A2A task 与业务操作之间的关联。 使用相同 key 的重复请求应该返回之前的结果，而不是创建新记录。

哪些操作需要用户确认？

支付、发布、对外发送消息、修改个人数据以及其他高成本或不可逆操作都应该确认。 搜索、读取公开数据和准备草稿通常可以自动完成。

联系方式