OpenAPI 사양에서 플러그 인 추가
기업에서는 실제 작업을 수행하는 API 집합이 이미 있는 경우가 많습니다. 이는 다른 자동화 서비스 또는 인간이 상호 작용하는 파워 프런트 엔드 애플리케이션에서 사용할 수 있습니다. 의미 체계 커널에서는 에이전트가 이를 사용할 수 있도록 플러그 인과 정확히 동일한 API를 추가할 수 있습니다.
OpenAPI 사양 예제
예를 들어 전구의 상태를 변경할 수 있는 API를 예로 들어 보세요. 이 API에 대한 OpenAPI 사양은 다음과 같습니다.
{
"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
}
}
}
}
이 사양은 API와 상호 작용하는 방법을 이해하기 위해 AI에 필요한 모든 것을 제공합니다. API에는 두 개의 엔드포인트, 즉 모든 조명을 가져오는 엔드포인트와 조명의 상태를 변경하는 엔드포인트가 포함됩니다. 또한 다음을 제공합니다.
- 엔드포인트 및 해당 매개 변수에 대한 의미 체계 설명
- 매개 변수의 형식
- 예상 응답
AI 에이전트는 이 사양을 이해할 수 있으므로 에이전트에 플러그 인으로 추가할 수 있습니다.
팁
기존 OpenAPI 사양이 있는 경우 AI에서 쉽게 이해할 수 있도록 변경해야 할 수 있습니다. 예를 들어 설명에 지침을 제공해야 할 수 있습니다. OpenAPI 사양을 AI 친화적으로 만드는 방법에 대한 자세한 팁은 OpenAPI 플러그 인을 추가하기 위한 팁과 요령을 참조하세요.
OpenAPI 플러그 인 추가
몇 줄의 코드를 사용하여 에이전트에 OpenAPI 플러그 인을 추가할 수 있습니다. 다음 코드 조각은 위의 OpenAPI 사양에서 라이트 플러그 인을 추가하는 방법을 보여줍니다.
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();
그런 다음 에이전트의 플러그 인을 네이티브 플러그 인처럼 사용할 수 있습니다.
OpenAPI 플러그 인을 추가하기 위한 팁과 요령
OpenAPI 사양은 일반적으로 인간을 위해 설계되었으므로 AI가 쉽게 이해할 수 있도록 몇 가지 변경을 수행해야 할 수 있습니다. 이 작업을 수행하는 데 도움이 되는 몇 가지 팁과 요령은 다음과 같습니다.
| 추천 | 설명 |
|---|---|
| API 사양을 제어하는 버전 | 라이브 API 사양을 가리키는 대신 Swagger 파일의 체크 인 및 버전 관리가 고려됩니다. 이렇게 하면 AI 연구원이 라이브 API에 영향을 주지 않고 AI 에이전트에서 사용하는 API 사양을 테스트(및 변경)할 수 있습니다. |
| 엔드포인트 수 제한 | API의 엔드포인트 수를 제한해 보세요. 복잡성을 줄이기 위해 선택적 매개 변수를 사용하여 유사한 기능을 단일 엔드포인트로 통합합니다. |
| 엔드포인트 및 매개 변수에 설명이 포함된 이름 사용 | 엔드포인트 및 매개 변수의 이름이 설명적이고 설명적인지 확인합니다. 이렇게 하면 광범위한 설명 없이도 AI가 해당 목적을 이해하는 데 도움이 됩니다. |
| 일관된 명명 규칙 사용 | API 전체에서 일관된 명명 규칙을 유지 관리합니다. 이렇게 하면 혼동이 줄어들고 AI가 API의 구조를 보다 쉽게 학습하고 예측하는 데 도움이 됩니다. |
| API 사양 간소화 | 종종 OpenAPI 사양은 매우 상세하며 AI 에이전트가 사용자를 돕기 위해 필요하지 않은 많은 정보를 포함합니다. API가 간단할수록 이를 설명하는 데 사용해야 하는 토큰이 줄어들고 AI가 요청을 보내는 데 필요한 토큰이 줄어듭니다. |
| 문자열 매개 변수 방지 | 가능하면 API에서 문자열 매개 변수를 사용하지 마세요. 대신 정수, 부울 또는 열거형과 같은 보다 구체적인 형식을 사용합니다. 이렇게 하면 AI가 API를 더 잘 이해할 수 있습니다. |
| 설명에 예제 제공 | 사용자가 Swagger 파일을 사용하는 경우 일반적으로 샘플 요청 및 응답을 포함하는 Swagger UI를 사용하여 API를 테스트할 수 있습니다. AI 에이전트는 이 작업을 수행할 수 없으므로 매개 변수 설명에 예제를 제공하는 것이 좋습니다. |
| 설명에서 다른 엔드포인트 참조 | 종종 AIS는 유사한 엔드포인트를 혼동합니다. AI가 엔드포인트를 구분하는 데 도움이 되도록 설명에서 다른 엔드포인트를 참조하는 것이 좋습니다. 예를 들어 "이 엔드포인트는 엔드포인트와 get_all_lights 비슷하지만 단일 조명만 반환합니다."라고 말할 수 있습니다. |
| 유용한 오류 메시지 제공 | OpenAPI 사양 내에 있지는 않지만 AI가 자체 수정하는 데 도움이 되는 오류 메시지를 제공하는 것이 좋습니다. 예를 들어 사용자가 잘못된 ID를 제공하는 경우 AI 에이전트가 엔드포인트에서 get_all_lights 올바른 ID를 가져오도록 제안하는 오류 메시지를 제공하는 것이 좋습니다. |
다음 단계
이제 플러그 인을 만드는 방법을 알게 되었으므로 이제 AI 에이전트와 함께 사용하는 방법을 알아볼 수 있습니다. 플러그 인에 추가한 함수 유형에 따라 따라 따라 다른 패턴을 따라야 합니다. 검색 함수의 경우 검색 함수 사용 문서를 참조 하세요 . 작업 자동화 함수의 경우 작업 자동화 함수 사용 문서를 참조 하세요 .