通过

导入 A2A 代理 API （预览版）

API Management支持管理与 Agent2Agent （A2A） 协议规范兼容的 AI 代理 API。 A2A 协议是一种开放的客户端-服务器标准，它使不同的 AI 代理系统能够使用共享交互模型进行通信和协同工作。 借助 API Management 中的 A2A 代理 API 支持，可以与其他 API 类型一起管理和管理代理 API，包括 AI 模型 API、模型上下文协议 （MCP） 工具和传统 API，例如 REST、SOAP 和 GraphQL。

注释

此功能以预览版提供，存在一些 限制。

详细了解如何在 API Management 中管理 AI API：

关键功能

导入 A2A 代理 API 时，API Management提供以下功能：

  • 协调 JSON-RPC 运行时操作到 A2A 后端。
    • 使用策略来实现治理和流量控制。
    • 当启用 Application Insights 的可观测性时，将添加以下特定于 A2A 的属性，以符合 OpenTelemetry GenAI 语义约定：
      • genai.agent.id - 设置为 API 设置中配置的代理 ID
      • genai.agent.name- 在 API 设置中设置为 API 名称
  • 显示具有以下转换功能的 代理卡：
    • 将主机名替换为API Management实例的主机名。
    • 将首选传输协议设置为 JSON-RPC。
    • 删除 additionalInterfaces 中的所有其他接口。
    • 重写安全要求以包括API Management订阅密钥要求。

先决条件

使用门户导入 A2A 代理 API

使用以下步骤将 A2A 代理 API 导入到API Management。

  1. 在 Azure portal 中，转到API Management实例。

  2. 在左侧菜单中的 API 下，选择 API>+ 添加 API。

  3. 选择 A2A 代理 图块。

    在门户中选择 A2A API 代理磁贴的屏幕截图。

  4. 在 “代理卡”下，输入指向代理卡 JSON 文档的 URL 。 选择“下一步”。

  5. 在 “创建 A2A 代理 API ”页上，配置 API 设置。

    1. 如果未根据代理卡自动配置 运行时 URL 和 代理 ID ，则向代理提供 JSON-RPC 操作的运行时 URL，以及由代理发出的 OpenTelemetry 跟踪中使用的代理 ID（gen_ai.agent.id 属性）。
    2. 在 General API 设置下，在API Management实例中输入所选的 Display 名称，并根据需要输入 Description。
    3. 在 URL 下，输入您的 API 管理实例用于访问 A2A 代理 API 的 基础路径。 API 管理显示客户端可用于访问 JSON-RPC API 的 Base URL，以及通过 API 管理访问代理卡的 Agent 卡 URL。

  6. 选择 “创建 ”以创建 API。

在门户中创建 A2A 代理兼容的 API 的屏幕截图。

为 A2A 代理 API 配置策略

配置一个或多个 API Management policies 以帮助管理 A2A 代理 API。

若要为 A2A 代理 API 配置策略，请执行以下作：

  1. 在 Azure portal 中，转到API Management实例。
  2. 在左侧菜单中的 API 下，选择 A2A 代理 API。
  3. 在左侧菜单中的 A2A 下，选择“ 策略”。
  4. 在策略编辑器中，添加或编辑要应用于 A2A 代理 API 的策略。 这些策略以 XML 格式定义。

注释

API Management 会先评估在全局（所有 API）范围内配置的策略，然后再评估在 A2A 代理 API 范围内的策略。

配置订阅密钥身份验证

在 A2A API 设置中，可以选择通过API Management配置订阅密钥身份验证。 详细了解订阅密钥身份验证。

  1. 选择上一步中创建的 API。
  2. 在“设置”页面上的“订阅”下，选择（启用）“需要订阅”。

如果启用订阅密钥身份验证，客户端必须在调用 A2A 代理 API 或访问代理卡时在标头或Ocp-Apim-Subscription-Key查询参数中包含subscription-key有效的订阅密钥。

测试 A2A 代理 API

若要确保 A2A 代理 API 按预期工作，请通过API Management调用后端：

  1. 选择上一步中创建的 API。
  2. 在 “概述 ”页上，复制 运行时基 URL。 使用此 URL 通过 API Management 调用 A2A 代理 API。
  3. 配置测试客户端或使用 curl 等工具向代理发出 POST 请求。 如果启用了订阅密钥身份验证，请在请求中包含有效的订阅密钥标头或查询参数。

小窍门

同样，通过在 API Management 中向 A2A 代理 API 的 概览 页面上显示的 代理卡 URL 发出 GET 请求，访问代理卡。

局限性

  • 此功能目前仅在 v2 层中的API Management实例中可用。
  • 仅支持基于 JSON-RPC 的 A2A 代理程序 API。
  • 不支持对传出响应体进行反序列化。

相关内容

  • Last updated on