에이전트 SDK(미리 보기)

Bot Framework/Microsoft 에이전트 SDK 작업 페이로드를 사용자가 제공한 에이전트 엔드포인트에 전달합니다. 에이전트 엔드포인트 URL은 호출당 입력 매개 변수로 제공됩니다. 연결을 만들 때 인증이 선택됩니다. 인증 없음, 정적 API 키 또는 Microsoft Entra ID OAuth(client_credentials). OAuth를 선택하면 전달자 토큰 대상 그룹(연결에 구성된 리소스 URL)이 대상 에이전트에서 예상하는 대상과 일치해야 합니다.

이 커넥터는 다음 제품 및 지역에서 사용할 수 있습니다.

서비스 클래스 Regions
Copilot Studio 표준 다음을 제외한 모든 Power Automate 지역:
     - 미국 정부(GCC)
     - 미국 정부(GCC High)
     - 21Vianet에서 운영하는 중국 클라우드
     - 미국 국방부(DoD)
논리 앱 표준 다음을 제외한 모든 Logic Apps 지역 :
     - Azure Government 지역
     - Azure 중국 지역
     - 미국 국방부(DoD)
Power Apps 표준 다음을 제외한 모든 Power Apps 지역:
     - 미국 정부(GCC)
     - 미국 정부(GCC High)
     - 21Vianet에서 운영하는 중국 클라우드
     - 미국 국방부(DoD)
파워 오토메이트 표준 다음을 제외한 모든 Power Automate 지역:
     - 미국 정부(GCC)
     - 미국 정부(GCC High)
     - 21Vianet에서 운영하는 중국 클라우드
     - 미국 국방부(DoD)
Contact
이름 마이크로소프트
URL https://support.microsoft.com
커넥터 메타데이터
Publisher 마이크로소프트
웹 사이트 https://www.microsoft.com
개인 정보 보호 정책 https://privacy.microsoft.com/
카테고리 Productivity

에이전트 SDK 커넥터는 Bot Framework/Microsoft 에이전트 SDK 작업 페이로드를 사용자가 제공한 에이전트 엔드포인트로 전달합니다. 에이전트 엔드포인트 URL은 호출당 입력 매개 변수로 제공됩니다. OAuth 토큰은 연결에 구성되고 모든 아웃바운드 요청에 전달자 토큰으로 삽입되는 사용자가 제공한 Microsoft Entra ID 애플리케이션 자격 증명에서 플랫폼에 의해 생성됩니다. 전달자 토큰 대상 그룹(연결에 구성된 리소스 URL)은 대상 에이전트가 예상한 대상과 일치해야 합니다.

Prerequisites

  • 배포된 Microsoft 에이전트 SDK/Bot Framework 에이전트는 HTTPS를 통해 연결할 수 있습니다.
  • 대상 에이전트를 호출할 권한 및 권한으로 client_credentials 구성된 에이전트를 호스팅하는 테넌트에 등록된 Microsoft Entra ID 애플리케이션입니다.
  • 에이전트의 예상 토큰 대상 그룹(일반적으로 에이전트의 Microsoft 앱 IDapi://<appId>)입니다.

자격 증명 가져오기

API 요청을 인증하려면 다음이 필요합니다.

  1. Microsoft Entra ID 애플리케이션의 테넌트 ID입니다.
  2. Microsoft Entra ID 애플리케이션의 클라이언트 ID(애플리케이션 ID)입니다.
  3. 해당 애플리케이션에 대한 클라이언트 암호 입니다.
  4. 대상 에이전트(Bot Framework 기술 인증 패턴)에서 예상하는 대상과 일치하는 리소스 URL 입니다.

연결을 만들 때 이러한 값을 제공합니다. 대상 그룹마다 다른 경우 에이전트당 하나의 연결을 만듭니다.

알려진 문제 및 제한 사항

  • 입력은 agentEndpoint 전체 HTTPS URL(예: https://my-agent.azurewebsites.net)이어야 합니다. 커넥터가 작업 페이로드를 추가하고 /api/messages 전달합니다.
  • 커넥터는 as-is 활동 페이로드를 전달하며 설정 deliveryMode되지 않습니다. 에이전트는 POSTing 회신 활동을 인바운드 활동에서 제공된 활동으로 다시 serviceUrl 회신하여 비동기적으로 회신합니다(예: Microsoft Copilot Studio 호출자는 SAS 키 콜백serviceUrl을 제공합니다).
  • 이 커넥터는 미리 보기로 제공됩니다. 가용성 및 기능은 변경될 수 있습니다.

연결을 만드는 중

커넥터는 다음 인증 유형을 지원합니다.
API 키 대상 에이전트가 사용자 지정 HTTP 헤더에 기대하는 정적 API 키를 사용하여 인증합니다. 헤더 이름(예: x-api-key)과 해당 값을 모두 지정합니다. 모든 지역 공유할 수 없음
Microsoft Entra ID(클라이언트 자격 증명) client_credentials 흐름을 사용하여 Microsoft Entra ID 애플리케이션에서 Mint OAuth 전달자 토큰을 전달합니다. 전달자 토큰 대상 그룹(리소스 URL)은 대상 에이전트가 예상하는 대상과 일치해야 합니다. 모든 지역 공유할 수 없음
인증 없음 인증 헤더 없이 대상 에이전트 엔드포인트를 호출합니다. 익명 호출을 명시적으로 수락하는 에이전트에서만 사용합니다. 모든 지역 공유 가능
기본값 [사용되지 않음] 이 옵션은 명시적 인증 유형이 없는 이전 연결에만 해당되며 이전 버전과의 호환성을 위해서만 제공됩니다. 모든 지역 공유할 수 없음

API 키

인증 ID: apiKey

적용 가능: 모든 지역

대상 에이전트가 사용자 지정 HTTP 헤더에 기대하는 정적 API 키를 사용하여 인증합니다. 헤더 이름(예: x-api-key)과 해당 값을 모두 지정합니다.

공유 가능한 연결이 아닙니다. 전원 앱이 다른 사용자와 공유되면 다른 사용자에게 새 연결을 명시적으로 만들라는 메시지가 표시됩니다.

이름 Type 설명 필수
API 키 헤더 이름 string 대상 에이전트가 API 키를 예상하는 HTTP 헤더의 이름입니다(예: x-api-key 또는 Ocp-Apim-Subscription-Key). True
API 키 값 시큐어스트링 (보안 문자열) 모든 요청에서 대상 에이전트 엔드포인트로 전송되는 정적 API 키 값입니다. True

Microsoft Entra ID(클라이언트 자격 증명)

인증 ID: oauthClientCredentials

적용 가능: 모든 지역

client_credentials 흐름을 사용하여 Microsoft Entra ID 애플리케이션에서 Mint OAuth 전달자 토큰을 전달합니다. 전달자 토큰 대상 그룹(리소스 URL)은 대상 에이전트가 예상하는 대상과 일치해야 합니다.

공유 가능한 연결이 아닙니다. 전원 앱이 다른 사용자와 공유되면 다른 사용자에게 새 연결을 명시적으로 만들라는 메시지가 표시됩니다.

이름 Type 설명 필수
임차인 string Microsoft Entra ID 애플리케이션의 테넌트 ID True
클라이언트 ID string Microsoft Entra ID 애플리케이션의 클라이언트(또는 애플리케이션) ID입니다. True
클라이언트 암호 시큐어스트링 (보안 문자열) Microsoft Entra ID 애플리케이션의 클라이언트 암호입니다. True
리소스 URL string OAuth 토큰의 대상 그룹입니다. 일반적으로 대상 에이전트의 Microsoft 앱 ID(예: api://< appId 또는 앱 ID GUID)입니다>. True

인증 없음

인증 ID: 익명

적용 가능: 모든 지역

인증 헤더 없이 대상 에이전트 엔드포인트를 호출합니다. 익명 호출을 명시적으로 수락하는 에이전트에서만 사용합니다.

공유 가능한 연결입니다. 전원 앱이 다른 사용자와 공유되면 연결도 공유됩니다. 자세한 내용은 캔버스 앱에 대한 컨넥터 개요를 참조하세요. Power Apps | Microsoft Docs

기본값 [사용되지 않음]

적용 가능: 모든 지역

이 옵션은 명시적 인증 유형이 없는 이전 연결에만 해당되며 이전 버전과의 호환성을 위해서만 제공됩니다.

공유 가능한 연결이 아닙니다. 전원 앱이 다른 사용자와 공유되면 다른 사용자에게 새 연결을 명시적으로 만들라는 메시지가 표시됩니다.

actions

에이전트에 활동 보내기

활동 프로토콜 페이로드를 {agentEndpoint}/api/messages의 에이전트 엔드포인트에 전달합니다. 연결에서 Microsoft Entra ID OAuth를 사용하는 경우 토큰 대상 그룹(연결의 리소스 URL)은 대상 에이전트(Bot Framework 기술 인증 패턴)에서 예상하는 대상과 같아야 하며, 대상이 다른 경우 에이전트당 하나의 연결을 만듭니다. 커넥터는 작업 페이로드 as-is 전달하고 'deliveryMode'를 설정하지 않습니다. 에이전트는 인바운드 활동에 제공된 'serviceUrl'에 대한 회신 활동을 POSTing하여 비동기적으로(일반 배달) 회신합니다.

에이전트에 활동 보내기

작업 ID:
SendActivity

활동 프로토콜 페이로드를 {agentEndpoint}/api/messages의 에이전트 엔드포인트에 전달합니다. 연결에서 Microsoft Entra ID OAuth를 사용하는 경우 토큰 대상 그룹(연결의 리소스 URL)은 대상 에이전트(Bot Framework 기술 인증 패턴)에서 예상하는 대상과 같아야 하며, 대상이 다른 경우 에이전트당 하나의 연결을 만듭니다. 커넥터는 작업 페이로드 as-is 전달하고 'deliveryMode'를 설정하지 않습니다. 에이전트는 인바운드 활동에 제공된 'serviceUrl'에 대한 회신 활동을 POSTing하여 비동기적으로(일반 배달) 회신합니다.

매개 변수

Name 키 필수 형식 Description
에이전트 엔드포인트 URL
 agentEndpoint True string

대상 Microsoft 에이전트 SDK/Bot Framework 엔드포인트의 기본 URL입니다(예: https://my-agent.azurewebsites.net). 커넥터는 /api/messages를 추가합니다.
object

반품

응답
object

정의

object

'object' 형식입니다.