從 OpenAPI 規格新增外掛程式

發行項
07/02/2024

在企業中，您通常已經有一組執行實際工作的 API。這些可由人類互動的其他自動化服務或電源前端應用程式使用。在語意核心中，您可以新增這些與外掛程式完全相同的 API，讓代理程式也可以使用它們。

OpenAPI 規格範例

例如，可讓您改變燈泡狀態的 API。此 API 的 OpenAPI 規格可能如下所示：

{
   "openapi": "3.0.1",
   "info": {
      "title": "Light API",
      "version": "v1"
   },
   "paths": {
      "/Light": {
         "get": {
            "tags": [
               "Light"
            ],
            "summary": "Retrieves all lights in the system.",
            "operationId": "get_all_lights",
            "responses": {
               "200": {
                  "description": "Returns a list of lights with their current state",
                  "application/json": {
                     "schema": {
                        "type": "array",
                        "items": {
                              "$ref": "#/components/schemas/LightStateModel"
                        }
                     }
                  }
               }
            }
         }
      },
      "/Light/{id}": {
         "post": {
               "tags": [
                  "Light"
               ],
               "summary": "Changes the state of a light.",
               "operationId": "change_light_state",
               "parameters": [
                  {
                     "name": "id",
                     "in": "path",
                     "description": "The ID of the light to change from the get_all_lights tool.",
                     "required": true,
                     "style": "simple",
                     "schema": {
                           "type": "string"
                     }
                  }
               ],
               "requestBody": {
                  "description": "The new state of the light and change parameters.",
                  "content": {
                     "application/json": {
                           "schema": {
                              "$ref": "#/components/schemas/ChangeStateRequest"
                           }
                     }
                  }
               },
               "responses": {
                  "200": {
                     "description": "Returns the updated light state",
                     "content": {
                           "application/json": {
                              "schema": {
                                 "$ref": "#/components/schemas/LightStateModel"
                              }
                           }
                     }
                  },
                  "404": {
                     "description": "If the light is not found"
                  }
               }
         }
      }
   },
   "components": {
      "schemas": {
         "ChangeStateRequest": {
               "type": "object",
               "properties": {
                  "isOn": {
                     "type": "boolean",
                     "description": "Specifies whether the light is turned on or off.",
                     "nullable": true
                  },
                  "hexColor": {
                     "type": "string",
                     "description": "The hex color code for the light.",
                     "nullable": true
                  },
                  "brightness": {
                     "type": "integer",
                     "description": "The brightness level of the light.",
                     "format": "int32",
                     "nullable": true
                  },
                  "fadeDurationInMilliseconds": {
                     "type": "integer",
                     "description": "Duration for the light to fade to the new state, in milliseconds.",
                     "format": "int32",
                     "nullable": true
                  },
                  "scheduledTime": {
                     "type": "string",
                     "description": "Use ScheduledTime to synchronize lights. It's recommended that you asynchronously create tasks for each light that's scheduled to avoid blocking the main thread.",
                     "format": "date-time",
                     "nullable": true
                  }
               },
               "additionalProperties": false,
               "description": "Represents a request to change the state of the light."
         },
         "LightStateModel": {
               "type": "object",
               "properties": {
                  "id": {
                     "type": "string",
                     "nullable": true
                  },
                  "name": {
                     "type": "string",
                     "nullable": true
                  },
                  "on": {
                     "type": "boolean",
                     "nullable": true
                  },
                  "brightness": {
                     "type": "integer",
                     "format": "int32",
                     "nullable": true
                  },
                  "hexColor": {
                     "type": "string",
                     "nullable": true
                  }
               },
               "additionalProperties": false
         }
      }
   }
}

此規格提供 AI 所需的一切，以瞭解 API 以及如何與其互動。 API 包含兩個端點：一個用來取得所有燈光，另一個用來變更光線的狀態。它也提供下列專案：

端點及其參數的語意描述
參數的類型
預期的回應

由於 AI 代理程式可以瞭解此規格，因此您可以將它新增為代理程式的外掛程式。

提示

如果您有現有的 OpenAPI 規格，您可能需要進行變更，讓 AI 更容易了解它們。例如，您可能需要在描述中提供指引。如需如何讓您的 OpenAPI 規格 AI 方便使用的秘訣，請參閱新增 OpenAPI 外掛程式的秘訣和訣竅。

新增 OpenAPI 外掛程式

使用幾行程式代碼，您可以將 OpenAPI 外掛程式新增至代理程式。下列代碼段示範如何從上述 OpenAPI 規格新增淺色外掛程式：

await kernel.ImportPluginFromOpenApiAsync(
   pluginName: "lights",
   uri: new Uri("https://example.com/v1/swagger.json"),
   executionParameters: new OpenApiFunctionExecutionParameters()
   {
      // Determines whether payload parameter names are augmented with namespaces.
      // Namespaces prevent naming conflicts by adding the parent parameter name
      // as a prefix, separated by dots
      EnablePayloadNamespacing = true
   }
);

await kernel.add_plugin_from_openapi(
   plugin_name="lights",
   openapi_document_path="https://example.com/v1/swagger.json",
   execution_settings=OpenAPIFunctionExecutionParameters(
         # Determines whether payload parameter names are augmented with namespaces.
         # Namespaces prevent naming conflicts by adding the parent parameter name
         # as a prefix, separated by dots
         enable_payload_namespacing=True,
   ),
)

String yaml = EmbeddedResourceLoader.readFile("petstore.yaml", ExamplePetstoreImporter.class);

KernelPlugin plugin = SemanticKernelOpenAPIImporter
   .builder()
   .withPluginName("petstore")
   .withSchema(yaml)
   .withServer("http://localhost:8090/api/v3")
   .build();

Kernel kernel = ExampleOpenAPIParent.kernelBuilder()
   .withPlugin(plugin)
   .build();

之後，您可以在代理程式中使用外掛程式，就像是原生外掛程式一樣。

新增 OpenAPI 外掛程式的秘訣和訣竅

由於 OpenAPI 規格通常是針對人類所設計，因此您可能需要進行一些變更，讓 AI 更容易瞭解。以下是協助您執行此動作的一些秘訣和訣竅：

建議	描述
版本控制您的 API 規格	請考慮簽入和版本設定 Swagger 檔案的版本，而不是指向即時 API 規格。這可讓 AI 研究人員測試 AI 代理程式所使用的 API 規格，而不會影響即時 API，反之亦然。
限制端點數目	嘗試限制 API 中的端點數目。將類似的功能合併到具有選擇性參數的單一端點，以減少複雜性。
使用端點和參數的描述性名稱	請確定端點和參數的名稱具有描述性和自我說明性。這有助於 AI 瞭解其用途，而不需要大量的說明。
使用一致的命名慣例	在整個 API 中維護一致的命名慣例。這可減少混淆，並協助 AI 更輕鬆地學習和預測 API 的結構。
簡化 API 規格	OpenAPI 規格通常非常詳細，並包含許多 AI 代理程式不需要的信息來協助使用者。 API 越簡單，您需要花費較少的令牌來描述 API，而 AI 需要傳送要求給它的令牌就越少。
避免字串參數	可能的話，請避免在 API 中使用字串參數。請改用更特定的類型，例如整數、布爾值或列舉。這有助於 AI 進一步瞭解 API。
提供描述中的範例	當人類使用 Swagger 檔案時，他們通常可以使用 Swagger UI 來測試 API，其中包括範例要求和回應。由於 AI 代理程式無法執行此動作，請考慮在參數的描述中提供範例。
參考描述中的其他端點	通常，AIS 會混淆類似的端點。為了協助 AI 區分端點，請考慮參考描述中的其他端點。例如，您可以說「此端點類似於 `get_all_lights` 端點，但只會傳回單一光線」。
提供實用的錯誤訊息	雖然不在 OpenAPI 規格內，但請考慮提供可協助 AI 自我更正的錯誤訊息。例如，如果使用者提供無效的標識碼，請考慮提供錯誤訊息，建議 AI 代理程式從 `get_all_lights` 端點取得正確的識別碼。

下一步

既然您已瞭解如何建立外掛程式，您現在可以瞭解如何將其與 AI 代理程式搭配使用。根據您新增至外掛程式的函式類型而定，您應該遵循不同的模式。如需擷取函式，請參閱使用擷取函式一文。如需工作自動化函式，請參閱使用工作自動化函式一文。

瞭解如何使用擷取函式

共用方式為

從 OpenAPI 規格新增外掛程式

OpenAPI 規格範例

新增 OpenAPI 外掛程式

新增 OpenAPI 外掛程式的秘訣和訣竅

下一步

其他資源