Ajouter des plug-ins à partir de spécifications OpenAPI
Souvent dans une entreprise, vous disposez déjà d’un ensemble d’API qui effectuent un travail réel. Ceux-ci peuvent être utilisés par d’autres services d’automatisation ou par des applications front-end avec lesquelles les humains interagissent. Dans le noyau sémantique, vous pouvez ajouter ces mêmes API que les plug-ins afin que vos agents puissent également les utiliser.
Exemple de spécification OpenAPI
Prenons un exemple d’API qui vous permet de modifier l’état des ampoules. La spécification OpenAPI pour cette API peut ressembler à ceci :
{
"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
}
}
}
}
Cette spécification fournit tout ce dont l’IA a besoin pour comprendre l’API et comment interagir avec elle. L’API inclut deux points de terminaison : un pour obtenir toutes les lumières et une autre pour changer l’état d’une lumière. Il fournit également les éléments suivants :
- Descriptions sémantiques des points de terminaison et de leurs paramètres
- Types des paramètres
- Réponses attendues
Étant donné que l’agent IA peut comprendre cette spécification, vous pouvez l’ajouter en tant que plug-in à l’agent.
Conseil
Si vous avez des spécifications OpenAPI existantes, vous devrez peut-être apporter des modifications pour faciliter leur compréhension d’une IA. Par exemple, vous devrez peut-être fournir des conseils dans les descriptions. Pour plus d’informations sur la façon de rendre vos spécifications OpenAPI conviviales pour l’IA, consultez conseils et astuces pour ajouter des plug-ins OpenAPI.
Ajout du plug-in OpenAPI
Avec quelques lignes de code, vous pouvez ajouter le plug-in OpenAPI à votre agent. L’extrait de code suivant montre comment ajouter le plug-in light à partir de la spécification OpenAPI ci-dessus :
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();
Ensuite, vous pouvez utiliser le plug-in dans votre agent comme s’il s’agissait d’un plug-in natif.
Conseils et astuces pour l’ajout de plug-ins OpenAPI
Étant donné que les spécifications OpenAPI sont généralement conçues pour les humains, vous devrez peut-être apporter certaines modifications pour faciliter leur compréhension d’une IA. Voici quelques conseils et astuces pour vous aider à le faire :
| Recommandation | Description |
|---|---|
| Contrôle de version de vos spécifications d’API | Au lieu de pointer vers une spécification d’API active, envisagez d’archiver et de gérer votre fichier Swagger. Cela permettra à vos chercheurs d’IA de tester (et de modifier) la spécification de l’API utilisée par l’agent IA sans affecter l’API active et vice versa. |
| Limiter le nombre de points de terminaison | Essayez de limiter le nombre de points de terminaison dans votre API. Regroupez des fonctionnalités similaires dans des points de terminaison uniques avec des paramètres facultatifs pour réduire la complexité. |
| Utiliser des noms descriptifs pour les points de terminaison et les paramètres | Vérifiez que les noms de vos points de terminaison et paramètres sont descriptifs et explicites. Cela aide l’IA à comprendre son objectif sans avoir besoin d’explications approfondies. |
| Utiliser des conventions d’affectation de noms cohérentes | Conservez des conventions d’affectation de noms cohérentes tout au long de votre API. Cela réduit la confusion et aide l’IA à apprendre et à prédire plus facilement la structure de votre API. |
| Simplifier vos spécifications d’API | Souvent, les spécifications OpenAPI sont très détaillées et incluent beaucoup d’informations qui ne sont pas nécessaires pour que l’agent IA aide un utilisateur. Plus l’API est simple, le moins de jetons que vous devez dépenser pour le décrire et le moins de jetons dont l’IA a besoin pour envoyer des demandes. |
| Éviter les paramètres de chaîne | Si possible, évitez d’utiliser des paramètres de chaîne dans votre API. Utilisez plutôt des types plus spécifiques tels que des entiers, des booléens ou des énumérations. Cela aidera l’IA à mieux comprendre l’API. |
| Fournir des exemples dans les descriptions | Lorsque les humains utilisent des fichiers Swagger, ils peuvent généralement tester l’API à l’aide de l’interface utilisateur Swagger, qui inclut des exemples de requêtes et de réponses. Étant donné que l’agent IA ne peut pas le faire, envisagez de fournir des exemples dans les descriptions des paramètres. |
| Référencer d’autres points de terminaison dans les descriptions | Souvent, les API confondent les points de terminaison similaires. Pour aider l’IA à différencier les points de terminaison, envisagez de référencer d’autres points de terminaison dans les descriptions. Par exemple, vous pouvez dire « Ce point de terminaison est similaire au get_all_lights point de terminaison, mais il ne retourne qu’une seule lumière ». |
| Fournir des messages d’erreur utiles | Bien qu’il ne se trouve pas dans la spécification OpenAPI, envisagez de fournir des messages d’erreur qui aident l’IA à corriger automatiquement. Par exemple, si un utilisateur fournit un ID non valide, envisagez de fournir un message d’erreur qui suggère que l’agent IA obtient l’ID correct à partir du get_all_lights point de terminaison. |
Étapes suivantes
Maintenant que vous savez comment créer un plug-in, vous pouvez maintenant apprendre à les utiliser avec votre agent IA. Selon le type de fonctions que vous avez ajoutées à vos plug-ins, vous devez suivre différents modèles. Pour les fonctions de récupération, reportez-vous à l’article sur l’utilisation des fonctions de récupération. Pour les fonctions d’automatisation des tâches, reportez-vous à l’article utilisation des fonctions d’automatisation des tâches .