Aggiungere plug-in dalle specifiche OpenAPI

  • Articolo

Spesso in un'azienda si dispone già di un set di API che eseguono un lavoro reale. Questi possono essere usati da altri servizi di automazione o da applicazioni front-end che interagiscono con gli esseri umani. Nel kernel semantico è possibile aggiungere queste API identiche ai plug-in in modo che gli agenti possano usarle anche.

Specifica OpenAPI di esempio

Si prenda ad esempio un'API che consente di modificare lo stato delle lampadine. La specifica OpenAPI per questa API potrebbe essere simile alla seguente:

{
   "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
         }
      }
   }
}

Questa specifica fornisce tutto ciò che serve all'intelligenza artificiale per comprendere l'API e come interagire con esso. L'API include due endpoint: uno per ottenere tutte le luci e un altro per modificare lo stato di una luce. Fornisce anche quanto segue:

  • Descrizioni semantiche per gli endpoint e i relativi parametri
  • Tipi di parametri
  • Risposte previste

Poiché l'agente di intelligenza artificiale può comprendere questa specifica, è possibile aggiungerlo come plug-in all'agente.

Suggerimento

Se sono presenti specifiche OpenAPI, potrebbe essere necessario apportare modifiche per semplificarne la comprensione da parte di un'intelligenza artificiale. Ad esempio, potrebbe essere necessario fornire indicazioni nelle descrizioni. Per altri suggerimenti su come rendere le specifiche OpenAPI compatibili con l'intelligenza artificiale, vedere Suggerimenti e consigli per l'aggiunta di plug-in OpenAPI.

Aggiunta del plug-in OpenAPI

Con alcune righe di codice, è possibile aggiungere il plug-in OpenAPI all'agente. Il frammento di codice seguente illustra come aggiungere il plug-in light dalla specifica OpenAPI precedente:

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();

Successivamente, è possibile usare il plug-in nell'agente come se fosse un plug-in nativo.

Suggerimenti e consigli per l'aggiunta di plug-in OpenAPI

Poiché le specifiche OpenAPI sono in genere progettate per gli esseri umani, potrebbe essere necessario apportare alcune modifiche per semplificarne la comprensione da parte di un'intelligenza artificiale. Ecco alcuni suggerimenti e trucchi per aiutarti a farlo:

Suggerimento Descrizione
Controllo della versione delle specifiche DELL'API Invece di puntare a una specifica dell'API dinamica, prendere in considerazione l'archiviazione e il controllo delle versioni del file Swagger. Ciò consentirà ai ricercatori di intelligenza artificiale di testare (e modificare) la specifica dell'API usata dall'agente di intelligenza artificiale senza influire sull'API dinamica e viceversa.
Limitare il numero di endpoint Provare a limitare il numero di endpoint nell'API. Consolidare funzionalità simili in singoli endpoint con parametri facoltativi per ridurre la complessità.
Usare nomi descrittivi per endpoint e parametri Assicurarsi che i nomi degli endpoint e dei parametri siano descrittivi e autoesplicativi. In questo modo l'intelligenza artificiale comprende il proprio scopo senza dover fornire spiegazioni complete.
Usare convenzioni di denominazione coerenti Mantenere convenzioni di denominazione coerenti in tutta l'API. Ciò riduce la confusione e aiuta l'intelligenza artificiale a apprendere e prevedere più facilmente la struttura dell'API.
Semplificare le specifiche dell'API Spesso, le specifiche OpenAPI sono molto dettagliate e includono molte informazioni che non sono necessarie per l'agente di intelligenza artificiale per aiutare un utente. Più semplice è l'API, il minor numero di token che è necessario spendere per descriverlo e il minor numero di token necessari all'intelligenza artificiale per inviare richieste.
Evitare parametri stringa Quando possibile, evitare di usare parametri stringa nell'API. Usare invece tipi più specifici, ad esempio numeri interi, valori booleani o enumerazioni. Ciò consentirà all'intelligenza artificiale di comprendere meglio l'API.
Fornire esempi nelle descrizioni Quando gli esseri umani usano file Swagger, in genere sono in grado di testare l'API usando l'interfaccia utente di Swagger, che include richieste di esempio e risposte. Poiché l'agente di intelligenza artificiale non può eseguire questa operazione, prendere in considerazione la possibilità di fornire esempi nelle descrizioni dei parametri.
Fare riferimento ad altri endpoint nelle descrizioni Spesso, le interfacce AI confonderanno endpoint simili. Per facilitare la differenziazione dell'intelligenza artificiale tra gli endpoint, è consigliabile fare riferimento ad altri endpoint nelle descrizioni. Ad esempio, è possibile pronunciare "Questo endpoint è simile all'endpoint get_all_lights , ma restituisce solo una singola luce".
Fornire messaggi di errore utili Anche se non rientra nella specifica OpenAPI, è consigliabile fornire messaggi di errore che consentono di correggere automaticamente l'intelligenza artificiale. Ad esempio, se un utente fornisce un ID non valido, è consigliabile specificare un messaggio di errore che suggerisce all'agente di intelligenza artificiale di ottenere l'ID corretto dall'endpoint get_all_lights .

Passaggi successivi

Ora che si sa come creare un plug-in, è ora possibile imparare a usarli con l'agente di intelligenza artificiale. A seconda del tipo di funzioni aggiunte ai plug-in, ci sono modelli diversi da seguire. Per le funzioni di recupero, vedere l'articolo uso delle funzioni di recupero. Per le funzioni di automazione delle attività, vedere l'articolo uso delle funzioni di automazione delle attività .

Informazioni sull'uso delle funzioni di recupero