Invoegtoepassingen toevoegen vanuit OpenAPI-specificaties
Vaak hebt u in een onderneming al een set API's die echt werken. Deze kunnen worden gebruikt door andere automatiseringsservices of krachtige front-endtoepassingen waarmee mensen communiceren. In Semantic Kernel kunt u dezelfde API's toevoegen als invoegtoepassingen, zodat uw agents ze ook kunnen gebruiken.
Een voorbeeld van een OpenAPI-specificatie
Neem bijvoorbeeld een API waarmee u de status van gloeilampen kunt wijzigen. De OpenAPI-specificatie voor deze API kan er als volgt uitzien:
{
"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
}
}
}
}
Deze specificatie biedt alles wat de AI nodig heeft om inzicht te hebben in de API en hoe u ermee kunt werken. De API bevat twee eindpunten: één om alle lichten op te halen en een andere om de status van een licht te wijzigen. Het biedt ook het volgende:
- Semantische beschrijvingen voor de eindpunten en hun parameters
- De typen parameters
- De verwachte antwoorden
Omdat de AI-agent deze specificatie kan begrijpen, kunt u deze als invoegtoepassing toevoegen aan de agent.
Tip
Als u bestaande OpenAPI-specificaties hebt, moet u mogelijk wijzigingen aanbrengen om deze eenvoudiger te maken voor een AI om ze te begrijpen. U moet bijvoorbeeld richtlijnen opgeven in de beschrijvingen. Zie Tips en trucs voor het toevoegen van OpenAPI-invoegtoepassingen voor meer tips over hoe u uw OpenAPI-specificaties AI-vriendelijk maakt.
De OpenAPI-invoegtoepassing toevoegen
Met een paar regels code kunt u de OpenAPI-invoegtoepassing toevoegen aan uw agent. In het volgende codefragment ziet u hoe u de light-invoegtoepassing toevoegt uit de Bovenstaande OpenAPI-specificatie:
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();
Daarna kunt u de invoegtoepassing in uw agent gebruiken alsof het een systeemeigen invoegtoepassing is.
Tips en trucs voor het toevoegen van OpenAPI-invoegtoepassingen
Omdat OpenAPI-specificaties doorgaans zijn ontworpen voor mensen, moet u mogelijk enkele wijzigingen aanbrengen om ze gemakkelijker te begrijpen voor een AI. Hier volgen enkele tips en trucs om u te helpen dit te doen:
| Aanbeveling | Beschrijving |
|---|---|
| Versiebeheer voor uw API-specificaties | In plaats van naar een live API-specificatie te verwijzen, kunt u overwegen om uw Swagger-bestand in te checken en versiebeheer uit te voeren. Hierdoor kunnen uw AI-onderzoekers de API-specificatie testen (en wijzigen) die door de AI-agent wordt gebruikt zonder dat dit van invloed is op de live-API en vice versa. |
| Het aantal eindpunten beperken | Probeer het aantal eindpunten in uw API te beperken. Voeg vergelijkbare functies samen in één eindpunt met optionele parameters om de complexiteit te verminderen. |
| Beschrijvende namen gebruiken voor eindpunten en parameters | Zorg ervoor dat de namen van uw eindpunten en parameters beschrijvend en verklarend zijn. Dit helpt de AI hun doel te begrijpen zonder uitgebreide uitleg nodig te hebben. |
| Consistente naamconventies gebruiken | Behoud consistente naamconventies in uw API. Dit vermindert verwarring en helpt de AI om de structuur van uw API gemakkelijker te leren en te voorspellen. |
| Vereenvoudig uw API-specificaties | OpenAPI-specificaties zijn vaak zeer gedetailleerd en bevatten veel informatie die niet nodig is voor de AI-agent om een gebruiker te helpen. Hoe eenvoudiger de API, hoe minder tokens u moet uitgeven om deze te beschrijven en hoe minder tokens de AI nodig heeft om er aanvragen naar te verzenden. |
| Tekenreeksparameters vermijden | Vermijd, indien mogelijk, het gebruik van tekenreeksparameters in uw API. Gebruik in plaats daarvan specifiekere typen, zoals gehele getallen, Booleaanse waarden of opsommingen. Dit helpt de AI de API beter te begrijpen. |
| Voorbeelden in beschrijvingen opgeven | Wanneer mensen Swagger-bestanden gebruiken, kunnen ze doorgaans de API testen met behulp van de Swagger-gebruikersinterface, waaronder voorbeeldaanvragen en antwoorden. Aangezien de AI-agent dit niet kan doen, kunt u overwegen voorbeelden op te geven in de beschrijvingen van de parameters. |
| Verwijzen naar andere eindpunten in beschrijvingen | Vaak verwarren AIs vergelijkbare eindpunten. Raadpleeg andere eindpunten in de beschrijvingen om de AI te helpen onderscheid te maken tussen eindpunten. U kunt bijvoorbeeld zeggen: 'Dit eindpunt is vergelijkbaar met het get_all_lights eindpunt, maar retourneert slechts één licht'. |
| Geef nuttige foutberichten op | Hoewel deze niet binnen de OpenAPI-specificatie valt, kunt u overwegen foutberichten op te geven die de AI zelf corrigeren. Als een gebruiker bijvoorbeeld een ongeldige id opgeeft, kunt u een foutbericht instellen dat aangeeft dat de AI-agent de juiste id van het get_all_lights eindpunt krijgt. |
Volgende stappen
Nu u weet hoe u een invoegtoepassing maakt, kunt u nu leren hoe u deze kunt gebruiken met uw AI-agent. Afhankelijk van het type functies dat u aan uw invoegtoepassingen hebt toegevoegd, zijn er verschillende patronen die u moet volgen. Raadpleeg het artikel over het ophalen van functies voor het ophalen van functies . Raadpleeg het artikel over het gebruik van taakautomatiseringsfuncties voor taakautomatiseringsfuncties .