Adicionar plugins a partir de especificações OpenAPI
Muitas vezes, em uma empresa, você já tem um conjunto de APIs que executam trabalho real. Eles podem ser usados por outros serviços de automação ou aplicativos front-end de energia com os quais os humanos interagem. No Kernel Semântico, você pode adicionar exatamente essas mesmas APIs como plug-ins para que seus agentes também possam usá-las.
Um exemplo de especificação OpenAPI
Tomemos por exemplo uma API que permite alterar o estado das lâmpadas. A especificação OpenAPI para esta API pode ter esta aparência:
{
"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
}
}
}
}
Essa especificação fornece tudo o que a IA precisa para entender a API e como interagir com ela. A API inclui dois pontos de extremidade: um para obter todas as luzes e outro para alterar o estado de uma luz. Ele também fornece o seguinte:
- Descrições semânticas para os endpoints e seus parâmetros
- Os tipos dos parâmetros
- As respostas esperadas
Como o agente de IA pode entender essa especificação, você pode adicioná-la como um plug-in ao agente.
Dica
Se você tiver especificações OpenAPI existentes, talvez seja necessário fazer alterações para torná-las mais fáceis para uma IA entendê-las. Por exemplo, talvez seja necessário fornecer orientação nas descrições. Para obter mais dicas sobre como tornar suas especificações OpenAPI amigáveis à IA, consulte Dicas e truques para adicionar plug-ins OpenAPI.
Adicionando o plug-in OpenAPI
Com algumas linhas de código, você pode adicionar o plugin OpenAPI ao seu agente. O trecho de código a seguir mostra como adicionar o plug-in light da especificação OpenAPI acima:
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();
Depois, você pode usar o plugin em seu agente como se fosse um plugin nativo.
Dicas e truques para adicionar plugins OpenAPI
Como as especificações OpenAPI são normalmente projetadas para humanos, talvez seja necessário fazer algumas alterações para torná-las mais fáceis de entender para uma IA. Aqui estão algumas dicas e truques para ajudá-lo a fazer isso:
| Recomendação | Descrição |
|---|---|
| Controle de versão das especificações da API | Em vez de apontar para uma especificação de API em tempo real, considere fazer check-in e controle de versão do arquivo Swagger. Isso permitirá que seus pesquisadores de IA testem (e alterem) a especificação da API usada pelo agente de IA sem afetar a API ativa e vice-versa. |
| Limitar o número de pontos de extremidade | Tente limitar o número de pontos de extremidade em sua API. Consolide funcionalidades semelhantes em pontos de extremidade únicos com parâmetros opcionais para reduzir a complexidade. |
| Usar nomes descritivos para pontos de extremidade e parâmetros | Certifique-se de que os nomes de seus pontos de extremidade e parâmetros sejam descritivos e autoexplicativos. Isso ajuda a IA a entender seu propósito sem precisar de explicações extensas. |
| Usar convenções de nomenclatura consistentes | Mantenha convenções de nomenclatura consistentes em toda a sua API. Isso reduz a confusão e ajuda a IA a aprender e prever a estrutura de sua API com mais facilidade. |
| Simplifique suas especificações de API | Muitas vezes, as especificações OpenAPI são muito detalhadas e incluem muitas informações que não são necessárias para o agente de IA ajudar um usuário. Quanto mais simples a API, menos tokens você precisa gastar para descrevê-la e menos tokens a IA precisa enviar solicitações para ela. |
| Evitar parâmetros de cadeia de caracteres | Quando possível, evite usar parâmetros de cadeia de caracteres em sua API. Em vez disso, use tipos mais específicos, como inteiros, booleanos ou enums. Isso ajudará a IA a entender melhor a API. |
| Fornecer exemplos em descrições | Quando os humanos usam arquivos Swagger, eles normalmente são capazes de testar a API usando a interface do usuário do Swagger, que inclui solicitações e respostas de amostra. Como o agente de IA não pode fazer isso, considere fornecer exemplos nas descrições dos parâmetros. |
| Fazer referência a outros pontos de extremidade em descrições | Muitas vezes, as IAs confundem pontos de extremidade semelhantes. Para ajudar a IA a diferenciar entre pontos de extremidade, considere fazer referência a outros pontos de extremidade nas descrições. Por exemplo, você pode dizer "Este ponto de extremidade é semelhante ao get_all_lights ponto de extremidade, mas ele só retorna uma única luz". |
| Fornecer mensagens de erro úteis | Embora não esteja dentro da especificação OpenAPI, considere fornecer mensagens de erro que ajudem a IA a se autocorrigir. Por exemplo, se um usuário fornecer uma ID inválida, considere fornecer uma mensagem de erro que sugira que o agente de IA obtenha a ID correta do get_all_lights ponto de extremidade. |
Próximas etapas
Agora que você sabe como criar um plugin, agora você pode aprender a usá-los com seu agente de IA. Dependendo do tipo de funções que você adicionou aos seus plugins, existem diferentes padrões que você deve seguir. Para funções de recuperação, consulte o artigo Usando funções de recuperação. Para funções de automação de tarefas, consulte o artigo Usando funções de automação de tarefas.