使用 API 外掛程式建立宣告式代理程式

7 分鐘

藉由將動作新增至宣告式代理程式，您可以讓它擷取和更新儲存在外部系統中的數據。將代理程式連線到您在組織中使用的外部系統，可讓您使用代理程式來支援您的商務程式。下列各節說明使用動作擴充宣告式代理程式時所涉及的不同元素。

宣告式代理程式

宣告式代理程式可以包含一或多個動作，讓它們能夠即時與外部系統互動。透過動作，代理程式可以讀取和修改儲存在外部應用程式中的數據。動作會透過 API 外掛程式連線到 API。代理程式會使用動作陣列，在指令清單中定義其動作：

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
  "version": "v1.0",
  "name": "Il Ristorante",
  "description": "Order the most delicious Italian dishes and drinks from the comfort of your desk.",
  "instructions": "$[file('instruction.txt')]",
  "actions": [
    {
      "id": "menuPlugin",
      "file": "ai-plugin.json"
    }
  ]
}

您可以藉由將元素新增至動作陣列來定義動作。每個元素都會使用識別碼唯一識別動作，並使用檔案屬性來參照專案中描述 API 外掛程式的個別外掛程式定義檔案。

外掛程式定義

外掛程式定義檔案描述宣告式代理程式用來與 API 通訊的 API 外掛程式。外掛程式定義包含數個區段，例如基本資訊、函式和運行時間。

基本資訊

每個外掛程式定義檔案都包含外掛程式的基本資訊，例如其名稱和描述。下列代碼段顯示基本外掛程式資訊的範例：

{
  "$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.1/schema.json",
  "schema_version": "v2.1",
  "namespace": "ilristorante",
  "name_for_human": "Il Ristorante",
  "description_for_human": "See the today's menu and place orders",
  "description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
  "functions": [
  ],
  "runtimes": [
  ],
  "capabilities": {
    "localization": {},
    "conversation_starters": []
  }
}

name_for_human的內容和description_for_human屬性純粹是具資訊性的。 description_for_model屬性很重要，因為代理程式會使用它來決定是否應針對使用者的提示叫用外掛程式。如果您看到代理程式未針對特定提示叫用外掛程式，您應該檢查模型的描述是否包含代理程式考慮其相關性所需的資訊。

另一個重要的屬性是需要的 命名空間 ，以及代理程式用來釐清不同外掛程式的動作。如果您移除它，或提供不符合架構的無效值，可能會防止代理程式使用您的外掛程式。命名空間必須符合下列正則表示 ^[A-Za-z0-9_]+式，這表示它必須包含至少一個字元，例如 A-Z、 a-z、 0-9或 _。任何其他字元都無效。

函式

外掛程式定義的下一個區段是函式。函式會定義 API 外掛程式可以執行的一或多個 API 作業，並指示代理程式如何顯示它從 API 接收的數據。下列代碼段顯示範例函式：

{
  "functions": [
    {
      "name": "getDishes",
      "description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
      "capabilities": {
        "response_semantics": {
          "data_path": "$.dishes",
          "properties": {
            "title": "$.name",
            "subtitle": "$.description"
          },
          "static_template": {
            ...trimmed for brevity
          }
        }
      }
    }
  ]
}

每個函式都包含數個元素。

名稱

名稱可唯一識別 API 外掛程式中的作業，而且必須完全符合相關 API 規格中的 operationId。如果您指定的名稱不符合任何作業，Microsoft 365 Agents Toolkit 會在建置項目時擲回錯誤。如果您部署名稱不符合 operationId 的函式，代理程式就無法叫用該函式。

描述

代理程式會使用描述來比對函式與使用者的提示。描述函式時，請務必說明其完成的工作，包括任何變化，例如篩選或排序資訊。如果描述不正確或不完整，代理程式就無法與特定提示進行比對，而且無法叫用函式。

回應語意

response_semantics屬性會指示代理程序應該如何顯示它從API接收的數據。它包含三個屬性： data_path、屬性和 static_template。

如果您的 API 傳回複雜的數據結構，而且您希望代理程式只顯示其特定部分，您可以使用 data_path 屬性來指定指向 API 回應相關部分的 JSON 路徑表示式。請考慮下列 API 回應：

{
  "dishes": [
    {
      "id": 1,
      "name": "Classic Italian Frittata",
      "description": "A fluffy omelette filled with sautéed mushrooms, onions, and melted pecorino, served with a side of roasted cherry tomatoes.",
      "image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/frittata.jpeg",
      "price": 8.99,
      "allergens": [
        "eggs",
        "dairy"
      ],
      "course": "breakfast",
      "type": "dish"
    },
    ...trimmed for brevity
  ]
}

您想要代理程式顯示的數據是在值屬性中，這就是為什麼您將data_path屬性設定為 $.dishes JSONPath 運算式，而 JSONPath 表達式會參考所$表示之根物件的值屬性。

回應語意的下一個部分是屬性。使用屬性時，您會告訴代理程式來自 API 回應的數據屬性代表項目的屬性，例如標題、描述或 URL。當您的 API 傳回多個專案時，代理程式會使用語意對應，在回復中包含最相關的資訊。請考慮下列語意對應：

{
  "response_semantics": {
    "properties": {
      "title": "$.name",
      "subtitle": "$.description"
    }
  }
}

當代理程序回應時，它會產生如下的答案：

針對每道菜，代理程式會以粗體加上標題，後面接著描述。因為對應不包含 URL 或敏感度標籤，所以代理程式不會將它們包含在其回應中。

回應語意的最後一個部分是 static_template。您可以使用靜態範本來定義調適型卡片範本，代理程式應該使用該範本來顯示來自 API 的數據。

提示

若要深入瞭解如何搭配 API 外掛程式使用調適型卡片範本，請參閱本學習課程模組結尾的一節 中的使用調適型卡片在宣告式代理程式的 API 外掛程式中顯示數據 學習課程模組。

運行時間

外掛程式定義的最後一個部分是 運行時間。運行時間描述外掛程式使用的 API，以及哪些函式屬於哪個 API。下列代碼段顯示執行時間定義：

{
  "type": "OpenApi",
  "auth": {
    "type": "None"
  },
  "spec": {
    "url": "apiSpecificationFile/ristorante.yml"
  },
  "run_for_functions": [
    "getDishes",
    "placeOrder"
  ]
}

您會從定義 API 描述的類型開始。目前，API 外掛程式僅支援 OpenAPI。

接下來，您要定義 API 是否為匿名或需要驗證。驗證類型 None 表示代理程式可以匿名呼叫 API。如果您需要與安全的 API 通訊，請據以更新值，以符合 API 的驗證機制。如需支援之驗證機制的詳細資訊，請參閱檔。

提示

若要深入瞭解如何將 API 外掛程式連線到安全的 API，請參閱本學習課程模組結尾的一節中的使用 安全 API 驗證宣告式代理程式的 API 外掛程式 學習課程模組。

在名為 spec的下一節中，您會提供本機 API 規格檔的參考，以描述 API 外掛程式可以使用的 API。使用 url 屬性，您可以指定項目中檔案的相對路徑。

最後一個部分是 run_for_functions 屬性，指定哪些指定的函式屬於此 API。

提示

建置專案時，Microsoft 365 代理程式工具組會確認此屬性中指定的函式符合函式區段中定義的函式，如果沒有，則會失敗併發生錯誤。 Microsoft 365 代理程式工具組檢查您的專案是否一致，可提供您早期的意見反應，並協助您避免難以偵錯錯誤。

API 規格

每個 API 外掛程式的一個重要部分是 API 規格，其提供有關 API 的重要資訊，包括：

API 所在的位置。
如果 API 需要驗證，如果需要，請以何種方式進行。
API 支援哪些作業。
針對每個作業，其預期的數據，以及其回應方式。

當代理程式載入 API 外掛程式時，它會使用所有這些資訊來建置 API 要求、呼叫 API 並處理其回應。因此，請務必清楚描述所有參數和屬性，讓代理程序瞭解如何使用它們來滿足使用者的要求。

如果您打算使用現有的 API，請務必只包含您打算在 API 外掛程式中使用的 API 規格部分。如果您包含整個 API 規格，但假設只使用一或兩個作業，則代理程式會更難以剖析大型 API 規格的相關信息。

提示

如果您需要使用現有 API 規格的一部分，請考慮使用 Hidi。這是Microsoft所建置的工具，可讓您輕鬆地擷取 API 規格的相關部分以及所有相關實體。在本學習課程模組結束時，尋找詳細資訊。

代理程式同時支援 YAML 和 JSON 中的 OpenAPI API 規格。

提示

當您建置供 API 外掛程式使用的自訂 API，並從本機電腦執行它時，您必須將它公開至因特網，代理程式才能呼叫它。您可以使用開發者隧道公開您的 API ，這是Microsoft建立的工具，可透過因特網共用本機服務。如果您使用 Microsoft 365 代理程式工具組來建置具有 API 外掛程式的代理程式，它不僅會自動啟動開發通道，也會在 API 規格中自動更新 API 的 URL，讓您專注於建置解決方案。

它如何結合在一起

既然您知道具有 API 外掛程式的宣告式代理程式包含哪些不同的元素，讓我們看看它們如何一起配合。下圖顯示不同元素之間的關聯性。

您可以使用 Microsoft Teams 應用程式來封裝及散發您的代理程式。每個 Teams 應用程式都可以包含一或多個宣告式代理程式，每個代理程式都已針對特定案例優化。代理程式可以包含零個或多個可讓它與外部系統通訊的 API 外掛程式。外掛程式會定義一或多個函式。每個函式都會執行特定工作，並只參考一個 API 作業。在函式旁邊，API 外掛程式指的是一或多個 API 規格，描述其所使用的 API。在其回合中，每個 API 規格都會定義外掛程式可以透過其函式使用的一或多個作業。

意見反應

此頁面對您有幫助嗎？