REST API에서 도구를 사용하여 에이전트 확장(미리 보기)

[이 문서는 시험판 설명서이므로 변경될 수 있습니다.]

REST API(API 포함 OpenAI )를 사용하여 작성한 에이전트를 외부 시스템과 연결하고 에이전트 내에서 사용할 수 있는 데이터에 액세스할 수 있습니다. 다음 세 가지를 제공하여 Copilot Studio 에이전트를 REST API에 연결할 수 있습니다.

• API의 기능 및 사용 가능한 작업을 정의하는 OpenAPI 사양
• 필요한 인증 유형에 대한 세부 정보 및 사용자가 외부 시스템에 액세스하기 위해 API에 연결하기 위한 인증 세부 정보
• 언어 모델이 데이터를 활용하기 위해 API를 호출할 시기를 결정하는 데 도움이 되는 설명

Copilot Studio를 통해 REST API는 Copilot 에이전트 및 사용자 지정 에이전트에 추가할 수 있습니다.

Copilot 에이전트를 사용하면 제작자가 커넥터, API, 프롬프트 및 지식 소스와 같은 여러 데이터 소스를 단일 에이전트로 결합할 수 있습니다. 이 에이전트를 사용하여 Microsoft 365 Copilot과 같은 Microsoft 브랜드 에이전트 환경을 확장할 수 있습니다.

사용자 지정 에이전트는 커넥터, API, 프롬프트 및 지식 소스를 포함하는 독립 실행형 에이전트입니다. 사용자 지정 에이전트를 웹 사이트 또는 다른 채널에 통합하여 직접 사용할 수 있습니다.

사전 요구 사항

커넥터 작업으로 Microsoft 브랜드 에이전트 환경을 확장하려면 몇 가지 필수 구성 요소가 필요합니다.

모든 에이전트 환경 유형의 경우 제작자 수준 자격 증명과 Copilot Studio 라이선스가 있어야 합니다.

또한 OpenAPI 사양의 사본, 필요한 인증 유형에 대한 지식 및 인증 세부 정보가 필요합니다.

에이전트에 REST API 작업 추가

에이전트에 REST API를 추가하려면 몇 가지 단계를 거쳐야 합니다. 다음 섹션에서는 프로세스를 안내합니다.

REST API를 추가하는 프로세스는 사용자 지정 에이전트와 Copilot 에이전트 모두에서 동일합니다.

이 프로세스에는 몇 가지 단계가 있습니다.

에이전트에 작업 추가

1. 에이전트의 개요 페이지로 이동합니다.

   

2. 도구 섹션에서 도구 추가를 선택합니다. 도구 탭으로 이동하여 도구 추가를 선택할 수도 있습니다.

   도구 추가 페이지가 표시됩니다.

3. 새 도구>REST API를 선택합니다.

API 사양, 설명 및 솔루션 제공

1. 연결하려는 REST API에 대한 사양 파일을 업로드 OpenAPI 합니다. REST API 업로드 화면으로 사양 파일을 끌어서 놓거나, 시스템을 탐색하여 사용하려는 파일을 찾을 수 있습니다.

   

   참고

   사양은 OpenAPI v2 형식의 JSON 파일이어야 합니다. v3 사양이 제출되면 생성 프로세스 중에 v2 사양으로 자동 변환됩니다.

   사양을 업로드하면 화면이 업데이트되어 사양 파일 이름과 세부 정보가 표시됩니다.

   

   다음 단계에서는 ADO 티켓 관리 시스템인 SunnyADO의 특정 예를 기반으로 절차를 수행합니다. 이 예에서는 사용자가 에이전트를 통해 티켓을 검색하고 업데이트할 수 있도록 하기 위한 것입니다.

2. 자세한 내용을 확인한 후 다음을 선택합니다.

   API 플러그인 세부 정보 페이지가 표시되며 여기에서 API에 대한 추가 정보를 제공할 수 있습니다.

   

   설명 필드는 처음에 업로드한 API 사양의 설명에 따라 채워집니다. 에이전트 오케스트레이션은 설명을 사용하여 특정 도구를 사용할 시기를 결정하기 때문에 자세한 설명을 제공합니다. 에이전트 선택 과정에 도움이 되도록 동의어를 포함한 세부 정보를 제공하십시오.

   예를 들어, 제공된 초기 설명은 "티켓을 관리하는 간단한 서비스"입니다.

   더 나은 설명은 "SunnyADO에서 기존 티켓을 가져오고, 검색하고, 찾고, 표시하는 데 사용되는 시스템입니다. 이를 통해 사용자는 티켓을 업데이트, 변경 및 관리하여 더 많은 데이터를 제공하여 기록을 개선할 수 있습니다.

3. 설명 필드에 개선된 설명을 입력합니다.

4. 솔루션 아래의 드롭다운에는 현재 환경 내에서 사용 가능한 모든 솔루션이 나열됩니다. 사용할 솔루션을 선택합니다. 솔루션이 무엇인지에 대한 자세한 내용은 솔루션 개념을 참조하세요.

   

   선호하는 솔루션이 있거나 선택한 커넥터가 이미 솔루션에 있는 경우 해당 솔루션이 자동으로 선택됩니다.

   솔루션을 선택하거나 비워 둘 수 있습니다. 솔루션을 비워 두면 작업 이름과 기본 게시자를 사용하여 솔루션이 만들어집니다. 작업을 솔루션에 저장하면 여러 환경에서 쉽게 이동할 수 있습니다.

   참고

   이 경우 기본 솔루션 또는 CDS 기본 솔루션이 옵션으로 표시되지 않으면 쉽게 관리할 수 있도록 사용자 지정 솔루션을 사용하는 것이 좋습니다. 자세한 내용은 기본 솔루션과 사용자 지정 솔루션 비교를 참조하세요.

5. 솔루션을 선택한 상태에서 다음을 선택하여 계속 진행합니다.

인증 세부 정보 제공

API에 사용할 인증 유형을 선택할 수 있는 인증 페이지가 표시됩니다.

1. 목록에서 인증 방법을 선택합니다.

2. 인증 방법에 대한 필수 필드를 입력합니다. 필드는 인증 방법에 따라 다릅니다.

   • 없음: 다른 필드는 필요하지 않습니다.
   • API 키:
     • 매개 변수 레이블: API 매개 변수에 대한 텍스트 레이블입니다.
     • 매개 변수 이름: API 매개 변수의 텍스트 이름입니다.
     • 파라미터 위치: 파라미터를 찾을 수 있는 위치입니다.
   • 인증 2.0:
     • 클라이언트 ID: 대상 서비스의 클라이언트 GUID입니다.
     • Client Secret(클라이언트 암호) – 클라이언트의 암호 값입니다. 사용자가 나중에 편집 패널을 열 때 비밀이 표시되지 않습니다. 그러나 추가 편집을 선택하는 경우 필요하므로 비밀을 저장합니다.
     • 권한 부여 URL: 원본 시스템에 권한을 부여하는 데 사용되는 URL입니다.
     • 토큰 URL: 토큰을 조회할 수 있는 URL입니다.
     • URL 새로 고침: 새로 고침 시나리오에서 리디렉션되는 URL입니다.
     • 범위: Microsoft Entra 앱용 API에 할당된 범위 URL입니다.
     • Microsoft 365 엔드포인트에 액세스하는 조직: 소스에 대한 액세스를 제작자의 조직 또는 모든 조직으로 제한합니다.
     • 끝점을 사용할 수 있는 앱(클라이언트): 이 데이터에 액세스하는 데 사용할 수 있는 클라이언트 시스템을 정의하는 GUID입니다. 앱에는 Microsoft 365, Power Automate 및 기타 옵션이 포함될 수 있습니다.

3. 모든 필드가 완료되면 다음을 선택합니다.

   API에 사용할 도구를 선택할 수 있는 플러그 인 도구 선택 및 구성 페이지가 표시됩니다.

   

API용 도구 선택

사용하도록 설정할 API 지원 도구를 선택합니다. 일반적으로 REST API는 API 사양에 정의된 엔드포인트 및 HTTP 메서드(가져오기, 배치, 게시, 삭제 등)의 다양한 조합을 통해 다양한 도구를 제공합니다. 경우에 따라 에이전트의 사용자가 API가 일반적으로 제공하는 모든 작업을 실행할 수 있는 기능을 갖지 않기를 원할 수 있습니다. 예를 들어 API 사양에 업데이트 및 삭제 작업이 포함될 수 있지만 에이전트 사용자만 레코드를 만들 수 있도록 할 수 있습니다.

1. 구성할 목록에서 도구를 선택합니다.

   Configure your plugin action(플러그인 작업 구성) 페이지가 표시됩니다.

   

2. 선택한 작업을 구성합니다. 전체 API와 마찬가지로 도구 이름 및 도구 설명을 입력하라는 메시지가 표시됩니다. 설명은 처음에 API 사양의 설명에서 미리 채워집니다. 이름은 고유할 필요는 없지만 도구 자체를 나타내야 합니다. 전체 API 설명과 마찬가지로 설명은 쿼리가 이 특정 도구와 일치하는지 더 잘 식별할 수 있도록 언어 모델에 세부 정보를 제공할 만큼 구체적이어야 합니다.

3. 필드가 완료되면 다음을 선택합니다.

   도구의 매개 변수 검토 페이지가 표시됩니다.

   

   이 페이지에는 가능한 입력 및 출력 값의 일부로 제공된 값이 표시됩니다. 이러한 값은 변경할 수 없지만 입력 및 출력에 대한 설명 은 업데이트할 수 있습니다. 이 페이지의 모든 콘텐츠는 업로드된 API 사양에서 직접 가져옵니다.

4. 설명에 필요한 값을 입력합니다. 설명은 값이 사용되는 용도에 대한 정의를 제공합니다. 설명이 비어 있는 경우 설명을 완료해야 계속 진행할 수 있습니다. 더 나은 설명이 없는 경우 이름을 붙여넣을 수 있습니다.

5. 설명을 완료한 후 다음을 선택합니다.

   이제 첫 번째 도구가 구성되고 플러그 인 도구 선택 및 구성 페이지의 선택한 도구 목록에 표시됩니다.

   

6. 지금 포함하려는 다른 작업을 추가합니다. 에이전트에서 지원할 도구 추가가 완료되면 다음을 선택합니다.

   도구 검토 페이지가 표시됩니다. 이 페이지에서는 구성된 REST API 도구의 세부 정보를 제공합니다.

   

검토 및 게시

1. 업데이트해야 하는 경우, 뒤로를 선택하여 변경할 수 있습니다. 그렇지 않으면 다음을 선택합니다.

   프로세스가 완료되는 동안 도구가 게시되고 있음을 나타내는 화면이 표시됩니다. 게시가 완료되면 알림을 받습니다.

2. 게시가 완료되면 도구 선택 화면으로 돌아갑니다. 여기에서 새로 구성된 REST API를 Copilot 에이전트 또는 사용자 지정 에이전트에 추가하고 구성 요소 구성을 완료할 수 있습니다.

   

이제 REST API 도구를 에이전트에서 사용할 수 있습니다.