Přidání modulů plug-in ze specifikací OpenAPI
V podniku už máte sadu rozhraní API, která provádějí skutečnou práci. Ty můžou používat jiné automatizační služby nebo power front-endové aplikace, se kterými lidé pracují. V sémantickém jádru můžete přidat stejná rozhraní API jako moduly plug-in, aby je mohli používat i vaši agenti.
Příklad specifikace OpenAPI
Vezměte například rozhraní API, které umožňuje změnit stav žárovky. Specifikace OpenAPI pro toto rozhraní API může vypadat takto:
{
"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
}
}
}
}
Tato specifikace poskytuje vše, co AI potřebuje k pochopení rozhraní API a způsobu interakce s ním. Rozhraní API obsahuje dva koncové body: jeden pro získání všech světel a druhý pro změnu stavu světla. Poskytuje také následující:
- Sémantické popisy koncových bodů a jejich parametrů
- Typy parametrů
- Očekávané odpovědi
Vzhledem k tomu, že agent AI dokáže tuto specifikaci pochopit, můžete ho přidat jako modul plug-in do agenta.
Tip
Pokud máte existující specifikace OpenAPI, možná budete muset udělat změny, aby jim AI usnadnila pochopení. Možná budete muset poskytnout pokyny v popisech. Další tipy, jak nastavit specifikace OpenAPI, které jsou vhodné pro AI, najdete v tématu Tipy a triky pro přidávání modulů plug-in OpenAPI.
Přidání modulu plug-in OpenAPI
Pomocí několika řádků kódu můžete do svého agenta přidat modul plug-in OpenAPI. Následující fragment kódu ukazuje, jak přidat modul plug-in Light ze specifikace OpenAPI výše:
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,
),
)
Potom můžete modul plug-in použít ve svém agentu, jako by to byl nativní modul plug-in.
Tipy a triky pro přidávání modulů plug-in OpenAPI
Vzhledem k tomu, že specifikace OpenAPI jsou obvykle navrženy pro lidi, možná budete muset udělat některé změny, aby je AI snadněji porozuměla. Tady je několik tipů a triků, které vám pomůžou s tím:
| Doporučení | Popis |
|---|---|
| Specifikace rozhraní API pro správu verzí | Místo odkazování na specifikaci živého rozhraní API zvažte vrácení se sem a správu verzí souboru Swagger. To umožní výzkumníkům umělé inteligence testovat (a měnit) specifikaci rozhraní API používanou agentem AI, aniž by to mělo vliv na živé rozhraní API a naopak. |
| Omezení počtu koncových bodů | Zkuste omezit počet koncových bodů ve vašem rozhraní API. Sloučit podobné funkce do jednotlivých koncových bodů s volitelnými parametry, aby se snížila složitost. |
| Použití popisných názvů pro koncové body a parametry | Ujistěte se, že názvy koncových bodů a parametrů jsou popisné a vysvětlující. To pomáhá umělé inteligenci pochopit jejich účel, aniž by potřebovala rozsáhlé vysvětlení. |
| Použití konvencí konzistentního pojmenování | Udržujte konzistentní konvence vytváření názvů v celém rozhraní API. To snižuje nejasnosti a pomáhá umělé inteligenci učit se a předpovídat strukturu vašeho rozhraní API snadněji. |
| Zjednodušení specifikací rozhraní API | Specifikace OpenAPI jsou často velmi podrobné a obsahují mnoho informací, které nejsou nezbytné pro agenta AI, aby pomohl uživateli. Jednodušší rozhraní API, čím méně tokenů potřebujete k popisu, a tím méně tokenů, které AI potřebuje k odeslání požadavků. |
| Vyhněte se parametrům řetězce | Pokud je to možné, vyhněte se použití parametrů řetězce ve vašem rozhraní API. Místo toho použijte konkrétnější typy, jako jsou celá čísla, logická hodnota nebo výčty. To pomůže umělé inteligenci lépe porozumět rozhraní API. |
| Zadání příkladů v popisech | Když lidé používají soubory Swagger, obvykle můžou rozhraní API otestovat pomocí uživatelského rozhraní Swagger, které zahrnuje ukázkové požadavky a odpovědi. Vzhledem k tomu, že agent AI to nedokáže, zvažte poskytnutí příkladů v popisech parametrů. |
| Odkaz na další koncové body v popisech | AI často zaměňují podobné koncové body. Pokud chcete umělé inteligenci rozlišovat mezi koncovými body, zvažte odkazování na jiné koncové body v popisech. Můžete například říct, že "Tento koncový bod je podobný koncovému get_all_lights bodu, ale vrací pouze jedno světlo". |
| Poskytnutí užitečných chybových zpráv | I když není ve specifikaci OpenAPI, zvažte poskytnutí chybových zpráv, které umělé inteligenci pomáhají správně opravit. Pokud například uživatel zadá neplatné ID, zvažte poskytnutí chybové zprávy, která navrhuje, aby agent umělé inteligence získal správné ID z koncového get_all_lights bodu. |
Další kroky
Teď, když víte, jak vytvořit modul plug-in, se teď můžete naučit, jak je používat s vaším agentem AI. V závislosti na typu funkcí, které jste přidali do modulů plug-in, byste měli postupovat podle různých vzorů. Informace o funkcích načítání najdete v článku o funkcích načítání . Informace o funkcích automatizace úloh najdete v článku o funkcích automatizace úloh.