Beépülő modulok hozzáadása OpenAPI-specifikációkból
Egy vállalatnál gyakran már rendelkezik olyan API-kkal, amelyek valós munkát végeznek. Ezeket más automatizálási szolgáltatások vagy az emberek által használt előtér-alkalmazások is használhatják. A Szemantic Kernelben pontosan ugyanazokat az API-kat veheti fel, mint a beépülő modulokat, így az ügynökök is használhatják őket.
Példa OpenAPI-specifikációra
Vegyünk például egy API-t, amely lehetővé teszi a villanykörte állapotának módosítását. Az API OpenAPI-specifikációja a következőképpen nézhet ki:
{
"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
}
}
}
}
Ez a specifikáció mindent biztosít, amire az AI-nek szüksége van az API megértéséhez és az azzal való interakcióhoz. Az API két végpontot tartalmaz: az egyiket az összes fény lekéréséhez, a másikat pedig a fény állapotának módosításához. Emellett a következőket is biztosítja:
- A végpontok és paramétereik szemantikai leírása
- A paraméterek típusai
- A várt válaszok
Mivel az AI-ügynök megérti ezt a specifikációt, beépülő modulként hozzáadhatja az ügynökhöz.
Tipp.
Ha rendelkezik meglévő OpenAPI-specifikációkkal, előfordulhat, hogy módosítania kell őket, hogy megkönnyítse az AI számára azok megértését. Előfordulhat például, hogy útmutatást kell adnia a leírásokban. További tippek az OpenAPI-specifikációk AI-baráttá alakításához: Tippek és trükkök OpenAPI beépülő modulok hozzáadásához.
Az OpenAPI beépülő modul hozzáadása
Néhány sornyi kóddal hozzáadhatja az OpenAPI beépülő modult az ügynökhöz. A következő kódrészlet bemutatja, hogyan adhatja hozzá a light beépülő modult a fenti OpenAPI-specifikációból:
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,
),
)
Ezt követően használhatja a beépülő modult az ügynökében, mintha natív beépülő modul lenne.
Tippek és trükkök OpenAPI beépülő modulok hozzáadásához
Mivel az OpenAPI-specifikációk általában emberek számára vannak kialakítva, előfordulhat, hogy módosítania kell őket, hogy könnyebben megérthesse az AI-t. Az alábbiakban néhány tippet és trükköt talál, amelyek segítenek ebben:
| Ajánlás | Leírás |
|---|---|
| Az API-specifikációk verziókövetése | Ahelyett, hogy élő API-specifikációra mutat, fontolja meg a Swagger-fájl beadását és verziószámozását. Ez lehetővé teszi az AI-kutatók számára az AI-ügynök által használt API-specifikáció tesztelését (és módosítását) anélkül, hogy az hatással van az élő API-ra, és fordítva. |
| Végpontok számának korlátozása | Próbálja meg korlátozni a végpontok számát az API-ban. A hasonló funkciók összevonása egyetlen végpontba opcionális paraméterekkel az összetettség csökkentése érdekében. |
| Leíró nevek használata végpontokhoz és paraméterekhez | Győződjön meg arról, hogy a végpontok és paraméterek neve leíró és magától értetődő. Ez segít az AI-nek megérteni a céljukat anélkül, hogy alapos magyarázatra van szüksége. |
| Konzisztens elnevezési konvenciók használata | Konzisztens elnevezési konvenciók fenntartása az API-ra. Ez csökkenti a félreértéseket, és segít az AI-nek könnyebben elsajátítani és előrejelezni az API szerkezetét. |
| Az API-specifikációk egyszerűsítése | Az OpenAPI-specifikációk gyakran nagyon részletesek, és sok olyan információt tartalmaznak, amelyek nem szükségesek ahhoz, hogy az AI-ügynök segítse a felhasználót. Minél egyszerűbb az API, annál kevesebb tokent kell költenie a leírásához, és annál kevesebb jogkivonatot kell küldenie az AI-nek. |
| Sztringparaméterek elkerülése | Ha lehetséges, kerülje a sztringparaméterek használatát az API-ban. Ehelyett használjon konkrétabb típusokat, például egész számokat, logikai értékeket vagy számokat. Ez segít az AI-nek jobban megérteni az API-t. |
| Példák megadása a leírásokban | Amikor az emberek Swagger-fájlokat használnak, általában a Swagger felhasználói felületén tesztelhetik az API-t, amely mintakéréseket és válaszokat tartalmaz. Mivel az AI-ügynök ezt nem tudja megtenni, érdemes lehet példákat megadni a paraméterek leírásában. |
| További végpontok hivatkozása a leírásokban | Az AI-k gyakran összekeverik a hasonló végpontokat. Annak érdekében, hogy az AI különbséget tegyen a végpontok között, érdemes lehet más végpontokra hivatkozni a leírásokban. Például azt mondhatja, hogy "Ez a végpont hasonló a get_all_lights végponthoz, de csak egyetlen fényt ad vissza." |
| Hasznos hibaüzenetek megadása | Bár nem tartozik az OpenAPI specifikációjához, érdemes lehet olyan hibaüzeneteket küldeni, amelyek segítenek az AI önhibájának javításában. Ha például egy felhasználó érvénytelen azonosítót ad meg, adjon meg egy hibaüzenetet, amely arra utal, hogy az AI-ügynök a megfelelő azonosítót kéri le a get_all_lights végpontról. |
Következő lépések
Most, hogy már tudja, hogyan hozhat létre beépülő modult, megtanulhatja, hogyan használhatja őket az AI-ügynökével. A beépülő modulokhoz hozzáadott függvények típusától függően különböző mintákat kell követnie. A lekérési függvényekkel kapcsolatban tekintse meg a lekérési függvények használatát ismertető cikket. Feladatautomatizálási függvények esetén tekintse meg a feladatautomatizálási függvények használatát ismertető cikket.