通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

导入 A2A 代理 API （预览版）

适用于：基本 v2 |标准 v2 |高级 v2

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

注释

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

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

关键功能

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

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

先决条件

使用门户导入 A2A 代理 API

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

  1. 在 Azure 门户中，转到 API 管理实例。

  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. 在 “常规 API 设置”下，在 API 管理实例中输入所选的 显示名称 ，并根据需要输入 “说明”。
    3. 在 URL 下，输入 API 管理实例用于访问 A2A 代理 API 的基本 路径 。 API 管理会显示一个基本 URL，可供客户端用来访问 JSON-RPC API；它还会显示一个代理卡 URL，可供客户端用来通过 API 管理访问代理卡。

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

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

为 A2A 代理 API 配置策略

配置一个或多个 API 管理 策略 ，以帮助管理 A2A 代理 API。

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

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

注释

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

配置订阅密钥身份验证

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

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

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

测试 A2A 代理 API

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

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

小窍门

同样，通过 API 管理，向 A2A 代理 API 的“概述”页面上显示的“代理卡 URL”发出 GET 请求，即可访问代理卡。

局限性

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

相关内容

  • Last updated on