共用方式為

匯入 A2A 代理 API（預覽）

適用於：基本 v2 |標準 v2 |進階 v2

API 管理支援管理與 Agent2Agent（A2A）協定規範相容的 AI 代理 API。 A2A 協定是一種開放的客戶端-伺服器標準，使不同的 AI 代理系統能夠透過共享互動模型進行溝通與協作。 透過 API 管理中的 A2A 代理 API 支援，您可以與其他 API 類型（包括 AI 模型 API、模型上下文協定（MCP）工具，以及傳統 API（如 REST、SOAP 和 GraphQL）一同管理和管理代理 API。

備註

此功能目前仍處於預覽階段，且有一些 限制。

深入瞭解在 API 管理中管理 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 管理訂閱金鑰的要求。

先決條件

使用 Portal 匯入 A2A 代理 API

請依照以下步驟將 A2A 代理 API 匯入 API 管理。

  1. 在 Azure 入口網站中，移至您的 API 管理 實例。

  2. 在左側功能表 的 [API] 底下，選取 [API]>[+ 新增 API]。

  3. 選擇 A2A 代理人 圖塊。

    在入口網站中選擇 A2A agent API 磚塊的截圖。

  4. 在 代理人卡片中，輸入指向代理人卡片 JSON 文件的 網址 。 選取 下一步。

  5. 在 「建立 A2A 代理 API 」 頁面，設定 API 設定。

    1. 如果Runtime URL和Agent ID沒有根據代理卡自動配置，則為您的代理提供 JSON-RPC 操作的執行階段 URL，以及代理在 OpenTelemetry 追蹤中使用的代理 ID（gen_ai.agent.id屬性）。
    2. 在 一般 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 agent 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 Management 呼叫後端：

  1. 選取您在上一個步驟中建立的 API。
  2. 在概覽 頁面複製執行階段型 URL。 使用此網址透過 API Management 呼叫 A2A 代理 API。
  3. 設定測試客戶端或使用像 curl 這類工具向代理發送 POST 請求。 若啟用訂閱金鑰認證，請在請求中加入有效的訂閱金鑰標頭或查詢參數。

小提示

同樣地，透過 API 管理，透過對 A2A 代理 API 概GET頁面顯示的代理卡 URL 提出請求，存取代理卡。

局限性

  • 此功能目前僅在 v2 層級的 API 管理實例中提供。
  • 僅支援基於 JSON-RPC 的 A2A 代理 API。
  • 不支援對傳出回應主體的還原序列化。

相關內容

  • Last updated on