에이전트 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은 호출당 입력 매개 변수로 제공됩니다. 연결은 인증 없음, 정적 API 키, Microsoft Entra ID 앱 전용 토큰(클라이언트 자격 증명) 또는 위임된 Microsoft Entra ID 사용자 토큰(사용자 로그인) 등 커넥터가 에이전트에 인증하는 방법을 선택합니다. 두 Microsoft Entra ID 옵션 모두 전달자 토큰 대상 그룹(연결에 구성된 리소스 URL)이 대상 에이전트가 예상하는 대상과 일치해야 합니다.

Prerequisites

배포된 Microsoft 에이전트 SDK/Bot Framework 에이전트는 HTTPS를 통해 연결할 수 있습니다.
Microsoft Entra ID(클라이언트 자격 증명)의 경우: 에이전트를 호스트하는 테넌트에 등록된 Microsoft Entra ID 애플리케이션으로, 대상 에이전트를 호출할 권한 및 권한으로 client_credentials 구성됩니다.
Microsoft Entra ID(사용자 로그인)의 경우: 클라이언트 암호가 있는 에이전트 고유의 Microsoft Entra ID 애플리케이션(Microsoft 앱 ID), 사용자가 동의할 수 있는 노출된 API 범위, Microsoft Graph User.Read ("로그인 및 사용자 프로필 읽기") 동의를 사용하여 권한을 위임하고 https://global.consent.azure-apim.net/redirect/agentsdk웹 리디렉션 URI로 추가했습니다.
API 키 및 클라이언트 자격 증명 옵션의 경우 에이전트의 예상 토큰 대상 그룹(일반적으로 에이전트의 Microsoft 앱 ID(예api://<appId>: 앱 ID GUID)) 사용자 로그인의 경우 대상 그룹은 앱 ID GUID여야 합니다(아래 참조).

자격 증명 가져오기

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

커넥터는 앱 전용 토큰을 보냅니다. API 요청을 인증하려면 다음이 필요합니다.

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

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

커넥터는 연결에 로그인한 계정의 위임된 토큰을 보내므로 에이전트가 해당 계정을 대신하여 교환할 수 있습니다(예: Microsoft 365 에이전트 SDK ConnectorUserAuthorization 처리기와 함께). 다음이 필요합니다.

에이전트 Microsoft Entra ID 애플리케이션의 테넌트 ID입니다.
클라이언트 ID: 에이전트의 고유한 Microsoft 앱 ID입니다. Microsoft 365 에이전트 SDK 토큰이 에이전트의 애플리케이션에 발급된 경우에만 사용자를 대신하여 토큰을 교환합니다.
해당 애플리케이션에 대한 클라이언트 암호 입니다.
리소스 URL: 클라이언트 ID와 동일한 값인 에이전트의 Microsoft 앱 ID(GUID)입니다. 에이전트의 자체 애플리케이션은 클라이언트와 리소스 모두이므로 Microsoft Entra 여기에 GUID가 필요합니다(그렇지 않으면 AADSTS90009)api://<appId>. 이 옵션은 지원되지 않습니다.

연결을 만들 때 이러한 값을 제공한 다음, 로그인하여 에이전트의 노출된 범위에 동의합니다. 에이전트당 하나의 연결을 만듭니다.

또한 애플리케이션에는 동의가 있는 Microsoft Graph User.Read("로그인 및 읽기 사용자 프로필") 위임된 권한이 필요합니다. 권한이 없으면 AADSTS90008 로그인이 실패합니다.

다운스트림 API에 대한 토큰을 교환하려면 에이전트 애플리케이션에 대한 API의 위임된 권한을 구성하고 필요한 사용자 또는 관리자 동의를 얻습니다. 에이전트의 자체 API에서 범위를 노출해도 다운스트림 권한이 부여되지 않습니다.

알려진 문제 및 제한 사항

입력은 agentEndpoint 전체 HTTPS URL(예: https://my-agent.azurewebsites.net)이어야 합니다. 커넥터가 작업 페이로드를 추가하고 /api/messages 전달합니다.
커넥터는 as-is 활동 페이로드를 전달하며 설정 deliveryMode되지 않습니다. 에이전트는 POSTing 회신 활동을 인바운드 활동에서 제공된 활동으로 다시 serviceUrl 회신하여 비동기적으로 회신합니다(예: Microsoft Copilot Studio 호출자는 SAS 키 콜백serviceUrl을 제공합니다).
Microsoft Entra ID(사용자 로그인) 연결은 에이전트와 채팅하는 다른 사용자를 대신하여 호출을 포함하여 해당 연결로 이루어진 모든 호출에 대해 항상 연결에 로그인한 계정의 위임된 토큰을 보냅니다. 각 호출자에 대해 별도의 토큰을 보내지 않으므로 활동의 사용자가 토큰의 from 사용자와 다를 수 있습니다. 요청은 유효성이 검사된 토큰의 계정으로만 권한을 부여하고 활동 from 또는 요청 헤더를 채팅 사용자의 권한으로 취급하지 않습니다. 에이전트가 채팅하는 각 사용자 역할을 해야 하는 경우 이 연결 유형을 사용하지 마세요.
로그인한 계정의 동의가 취소되거나 세션을 더 이상 새로 고칠 수 없는 경우 연결에 다시 로그인합니다.
이 커넥터는 미리 보기로 제공됩니다. 가용성 및 기능은 변경될 수 있습니다.

연결을 만드는 중

커넥터는 다음 인증 유형을 지원합니다.


API 키	대상 에이전트가 사용자 지정 HTTP 헤더에 기대하는 정적 API 키를 사용하여 인증합니다. 헤더 이름(예: x-api-key)과 해당 값을 모두 지정합니다.	모든 지역	공유할 수 없음
Microsoft Entra ID(클라이언트 자격 증명)	client_credentials 흐름을 사용하여 Microsoft Entra ID 애플리케이션에서 Mint OAuth 전달자 토큰을 전달합니다. 전달자 토큰 대상 그룹(리소스 URL)은 대상 에이전트가 예상하는 대상과 일치해야 합니다.	모든 지역	공유할 수 없음
Microsoft Entra ID(사용자 로그인)	대상 에이전트의 Microsoft Entra ID 애플리케이션(권한 부여 코드 흐름)을 통해 로그인하고 로그인한 계정의 위임된 전달자 토큰을 보냅니다. 이 연결로 수행된 모든 통화는 에이전트와 채팅하는 사람이 아니라 연결에 로그인한 계정을 사용합니다. 사용자를 대신하여 토큰을 교환하려면 에이전트가 다운스트림 위임 권한 및 동의를 구성해야 합니다.	모든 지역	공유할 수 없음
인증 없음	인증 헤더 없이 대상 에이전트 엔드포인트를 호출합니다. 익명 호출을 명시적으로 수락하는 에이전트에서만 사용합니다.	모든 지역	공유 가능
기본값 [사용되지 않음]	이 옵션은 명시적 인증 유형이 없는 이전 연결에만 해당되며 이전 버전과의 호환성을 위해서만 제공됩니다.	모든 지역	공유할 수 없음

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: oauthAuthorizationCode

적용 가능: 모든 지역

대상 에이전트의 Microsoft Entra ID 애플리케이션(권한 부여 코드 흐름)을 통해 로그인하고 로그인한 계정의 위임된 전달자 토큰을 보냅니다. 이 연결로 수행된 모든 통화는 에이전트와 채팅하는 사람이 아니라 연결에 로그인한 계정을 사용합니다. 사용자를 대신하여 토큰을 교환하려면 에이전트가 다운스트림 위임 권한 및 동의를 구성해야 합니다.

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

이름	Type	설명	필수
임차인	string	대상 에이전트의 Microsoft Entra ID 애플리케이션의 테넌트 ID입니다.	True
클라이언트 ID	string	대상 에이전트의 Microsoft 앱 ID입니다. 에이전트가 사용자를 대신하여 위임된 토큰을 교환할 수 있도록 에이전트 고유의 애플리케이션을 사용합니다.	True
클라이언트 암호	시큐어스트링 (보안 문자열)	대상 에이전트의 Microsoft Entra ID 애플리케이션의 클라이언트 암호입니다.	True
리소스 URL	string	위임된 토큰의 대상 그룹입니다. 대상 에이전트의 Microsoft 앱 ID(GUID)여야 하며 클라이언트 ID와 동일한 값이어야 합니다. Microsoft Entra 애플리케이션이 자체 토큰을 요청할 때 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

매개 변수

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

에이전트 SDK(미리 보기)

Prerequisites

자격 증명 가져오기

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

Microsoft Entra ID(사용자 로그인)

알려진 문제 및 제한 사항

연결을 만드는 중

API 키

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

Microsoft Entra ID(사용자 로그인)

인증 없음

기본값 [사용되지 않음]

actions

에이전트에 활동 보내기

매개 변수

반품

정의

object