Dodawanie wtyczek ze specyfikacji interfejsu OpenAPI
Często w przedsiębiorstwie masz już zestaw interfejsów API, które wykonują rzeczywistą pracę. Mogą one być używane przez inne usługi automatyzacji lub aplikacje frontonu zasilania, z którymi korzystają ludzie. W jądrze semantycznym można dodać dokładnie te same interfejsy API co wtyczki, aby agenci mogli ich również używać.
Przykładowa specyfikacja interfejsu OpenAPI
Weźmy na przykład interfejs API, który umożliwia zmianę stanu żarówek. Specyfikacja interfejsu OpenAPI dla tego interfejsu API może wyglądać następująco:
{
"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
}
}
}
}
Ta specyfikacja udostępnia wszystkie elementy potrzebne przez sztuczną inteligencję do zrozumienia interfejsu API i sposobu interakcji z nim. Interfejs API zawiera dwa punkty końcowe: jeden, aby uzyskać wszystkie światła, a drugi, aby zmienić stan światła. Udostępnia również następujące elementy:
- Semantyczne opisy punktów końcowych i ich parametrów
- Typy parametrów
- Oczekiwane odpowiedzi
Ponieważ agent sztucznej inteligencji może zrozumieć tę specyfikację, możesz dodać go jako wtyczkę do agenta.
Napiwek
Jeśli masz istniejące specyfikacje interfejsu OpenAPI, może być konieczne wprowadzenie zmian, aby ułatwić im zrozumienie sztucznej inteligencji. Na przykład może być konieczne podanie wskazówek w opisach. Aby uzyskać więcej wskazówek dotyczących sposobu, aby specyfikacje interfejsu OpenAPI były przyjazne dla sztucznej inteligencji, zobacz Porady i wskazówki dotyczące dodawania wtyczek interfejsu OpenAPI.
Dodawanie wtyczki OpenAPI
Za pomocą kilku wierszy kodu możesz dodać wtyczkę OpenAPI do agenta. Poniższy fragment kodu pokazuje, jak dodać wtyczkę light ze specyfikacji Interfejsu OpenAPI powyżej:
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();
Następnie możesz użyć wtyczki w agencie tak, jakby była to wtyczka natywna.
Porady i wskazówki dotyczące dodawania wtyczek interfejsu OpenAPI
Ponieważ specyfikacje interfejsu OpenAPI są zwykle przeznaczone dla ludzi, może być konieczne wprowadzenie pewnych zmian, aby ułatwić zrozumienie sztucznej inteligencji. Oto kilka wskazówek i wskazówek, które pomogą Ci to zrobić:
| Zalecenie | opis |
|---|---|
| Kontrola wersji specyfikacji interfejsu API | Zamiast wskazywać na specyfikację interfejsu API na żywo, rozważ zaewidencjonowanie i przechowywanie wersji pliku struktury Swagger. Pozwoli to badaczom sztucznej inteligencji przetestować (i zmienić) specyfikację interfejsu API używaną przez agenta sztucznej inteligencji bez wpływu na dynamiczny interfejs API i odwrotnie. |
| Ograniczanie liczby punktów końcowych | Spróbuj ograniczyć liczbę punktów końcowych w interfejsie API. Skonsoliduj podobne funkcje do pojedynczych punktów końcowych z opcjonalnymi parametrami, aby zmniejszyć złożoność. |
| Używanie nazw opisowych dla punktów końcowych i parametrów | Upewnij się, że nazwy punktów końcowych i parametrów są opisowe i objaśniające. Pomaga to sztucznej inteligencji zrozumieć swój cel bez konieczności obszernych wyjaśnień. |
| Używanie spójnych konwencji nazewnictwa | Zachowaj spójne konwencje nazewnictwa w całym interfejsie API. Zmniejsza to zamieszanie i ułatwia uczenie się sztucznej inteligencji i przewidywanie struktury interfejsu API. |
| Upraszczanie specyfikacji interfejsu API | Często specyfikacje interfejsu OpenAPI są bardzo szczegółowe i zawierają wiele informacji, które nie są niezbędne dla agenta sztucznej inteligencji, aby pomóc użytkownikowi. Prostszy interfejs API, tym mniej tokenów, które należy wydać, aby go opisać, oraz tym mniej tokenów, które sztuczna inteligencja musi wysyłać do niego żądania. |
| Unikaj parametrów ciągu | Jeśli to możliwe, unikaj używania parametrów ciągu w interfejsie API. Zamiast tego należy używać bardziej szczegółowych typów, takich jak liczby całkowite, wartości logiczne lub wyliczenia. Ułatwi to lepsze zrozumienie interfejsu API przez sztuczną inteligencję. |
| Podaj przykłady w opisach | Gdy ludzie używają plików struktury Swagger, zazwyczaj mogą testować interfejs API przy użyciu interfejsu użytkownika struktury Swagger, który obejmuje przykładowe żądania i odpowiedzi. Ponieważ agent sztucznej inteligencji nie może tego zrobić, rozważ podanie przykładów w opisach parametrów. |
| Odwołuj się do innych punktów końcowych w opisach | Często sztuczna inteligencja mylą podobne punkty końcowe. Aby ułatwić odróżnienie sztucznej inteligencji między punktami końcowymi, rozważ odwołanie się do innych punktów końcowych w opisach. Na przykład można powiedzieć: "Ten punkt końcowy jest podobny do punktu końcowego get_all_lights , ale zwraca tylko pojedyncze światło". |
| Podaj przydatne komunikaty o błędach | Chociaż nie należy do specyfikacji interfejsu OpenAPI, rozważ podanie komunikatów o błędach, które ułatwiają samodzielne poprawianie sztucznej inteligencji. Jeśli na przykład użytkownik podaje nieprawidłowy identyfikator, rozważ podanie komunikatu o błędzie, który sugeruje, że agent sztucznej inteligencji otrzyma prawidłowy identyfikator z punktu końcowego get_all_lights . |
Następne kroki
Teraz, gdy wiesz, jak utworzyć wtyczkę, możesz teraz dowiedzieć się, jak używać ich z agentem sztucznej inteligencji. W zależności od typu funkcji dodanych do wtyczek należy przestrzegać różnych wzorców. Aby zapoznać się z funkcjami pobierania, zapoznaj się z artykułem using retrieval functions (Korzystanie z funkcji pobierania). W przypadku funkcji automatyzacji zadań zapoznaj się z artykułem using task automation functions (Korzystanie z funkcji automatyzacji zadań).