API 플러그 인을 사용하면 Microsoft 365 Copilot 에이전트가 웹 서비스와 상호 작용하고 실시간 정보에 액세스할 수 있습니다. API 플러그 인을 사용하면 사용자가 자연어 명령을 통해 Copilot Chat 내의 에이전트에 대한 LOB(기간 업무) 시스템의 실시간 데이터와 상호 작용할 수 있습니다.
API 플러그인은 API 서비스, OpenAPI 설명 및 매니페스트 파일로 구성됩니다. 플러그 인 매니페스트는 Copilot 오케스트레이터에게 API의 기능에 대해 알려줍니다. 플러그인 매니페스트에는 API 서비스에 대한 OpenAPI 설명이 포함됩니다. OpenAPI 설명은 Copilot에 API에 연결하는 방법을 설명하기 때문에 중요합니다. Copilot을 사용하여 최적의 플러그 인 검색 가능성과 성능을 위해 명확하고 의미 있는 OpenAPI 설명을 제공하세요.
이 문서에서는 Copilot 에이전트 기능을 확장하는 플러그 인에 대해 OpenAPI 설명을 효과적으로 만드는 요소를 설명합니다.
OpenAPI 설명 요소
이 섹션에서는 OpenAPI 설명의 요소와 Copilot 에이전트에 대해 이를 최적화하는 방법에 대해 설명합니다.
OpenAPI 유효성 검사: 첫 번째 단계로 OpenAPI 설명이 OpenAPI 사양의 규칙을 따르는지 확인하는 것이 좋습니다. 다른 사용 사례 중에서 OpenAPI 설명의 유효성을 검사할 수 있는 명령줄 도구인 Hidi 또는 선택한 다른 도구를 사용할 수 있습니다. 유효한 OpenAPI 설명은 Copilot에서 잘 작동할 뿐만 아니라 OpenAPI 설명이 다른 도구에서도 작동할 수 있는지 확인합니다.
정보 섹션: 설명 필드는 OpenAPI 사양에서 선택 사항이지만 Copilot 기술을 확장하기 위한 OpenAPI 설명에는 필수적입니다. Copilot은 API가 무엇을 하고 언제 플러그 인을 사용하는지 알기 위해 설명 필드가 필요합니다. OpenAPI 문서에서 플러그인 매니페스트를 생성할 때 정보 섹션의 설명이 플러그인 매니페스트에 대한 설명으로 사용됩니다. 따라서 항상 간결하고 명확한 설명 필드를 갖는 것이 중요합니다. 예를 들어 다음은 수리점 OpenAPI 설명의 정보 섹션입니다.
info:
title: Repair Service
description: A simple service to manage repairs for various items
version: 1.0.0
작업 ID: OpenAPI 설명의 유용성을 향상시키는 유용한 기술은 API에서 제공하는 API 경로 및 HTTP 메서드의 각 조합에 대해 추가하는 operationID 것입니다. 작업 ID는 API의 작업에 대한 고유 식별자이며 Copilot에서 사용자의 프롬프트에 응답할 때 실행되는 함수를 만드는 데 사용됩니다.
또한 API에서 지원하는 각 작업에 대한 의미 있는 설명을 추가합니다. Copilot은 사용자의 프롬프트와 플러그 인 설명에 따라 플러그 인 사용을 선택한 후 경로 설명을 검색하여 사용자의 요청을 충족하는 데 사용할 엔드포인트를 결정합니다.
작업 ID는 디버깅 중에 Copilot이 실행하려는 작업을 나타내는 함수로 표시됩니다. 다음은 OpenAPI 문서의 샘플과 해당 디버거 출력의 샘플입니다.
paths:
/repairs:
get:
operationId: listRepairs
summary: List all repairs
description: Returns a list of repairs with their details and images
디버거 출력:
매개변수: API에서 지원하는 작업이 매개 변수를 사용하는 경우 OpenAPI 설명에 매개 변수를 포함합니다. 각 매개 변수에 대한 설명 필드를 포함하여 간략하게 설명하고 필요한 경우 매개 변수 사용법의 예를 제공합니다. 매개 변수는 Copilot에서 API에 요청하기 위한 사용자의 프롬프트에서 필요한 모든 정보를 가져오는 데 사용됩니다.
예를 들면 다음과 같습니다:
parameters:
- name: assignedTo
in: query
description: The name or ID of the person or team to whom the repair is assigned.
schema:
type: string
required: false
응답: 성공 및 오류 응답을 포함하여 각 작업에 대해 가능한 모든 응답을 명확하게 정의합니다. 각 응답에는 상태 코드와 응답이 나타내는 내용에 대한 설명이 있어야 합니다. 응답 예제를 포함하면 Copilot이 API에서 기대하는 사항을 이해하는 데 도움이 됩니다.
responses:
'200':
description: A list of repairs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Repair'
examples:
example1:
value:
[
{
"id": "1",
"item": "Laptop",
"status": "In Progress",
"assignedTo": "John Doe"
}
]
'404':
description: No repairs found
'500':
description: Server error