변수 개요

변수는 4가지 수준 또는 범위에서 존재할 수 있습니다.

• 토픽 변수는 생성된 토픽에서만 사용할 수 있습니다. 이 범위는 생성하는 변수의 기본값입니다.
• 전역 변수는 모든 토픽에서 사용할 수 있습니다. 토픽 변수의 범위를 변경하여 전역 변수로 만들 수 있습니다.
• 시스템 변수는 에이전트와 함께 자동으로 생성됩니다. 대화 또는 사용자에 대한 더 많은 상황 정보를 제공합니다. 모든 토픽에서 사용할 수 있습니다.
• 환경 변수는 Power Platform에서 생성되며 Copilot Studio에서 읽기 전용입니다. 여기에는 Copilot Studio를 포함한 다양한 다른 애플리케이션 개체에 대한 입력으로 사용되는 매개 변수 키와 값이 저장됩니다. 사용 개체에서 매개 변수를 분리하면 동일한 환경 내에서 또는 솔루션을 다른 환경으로 마이그레이션할 때 값을 변경할 수 있습니다. 대안은 이를 사용하는 구성 요소 내에 하드 코딩된 매개 변수 값을 남겨 두는 것입니다.

변수 유형

변수는 기본 유형과 연결됩니다. 유형에 따라 변수에 포함될 수 있는 값과 논리식을 구성할 때 사용할 수 있는 연산자가 결정됩니다.

Type	Description
String	텍스트를 나타내는 데 사용되는 일련의 문자
부울	true 또는 false만 가능한 논리 값
숫자	임의의 실수
테이블	값 목록이지만 모든 값은 동일한 유형이어야 합니다.
녹음	값이 모든 유형일 수 있는 이름-값 쌍의 모음입니다.
날짜/시간	특정 시점을 기준으로 한 날짜, 시간, 요일 또는 월입니다.
선택 항목	연관된 동의어가 있는 문자열 값 목록
빈 템플릿	"값 없음" 또는 "알 수 없는 값"에 대한 자리 표시자 자세한 내용은 Power Fx의 공백을 참조하세요.

변수의 유형은 값이 처음 할당될 때 설정됩니다. 그 후에는 해당 변수의 유형이 고정되고 다른 유형의 값을 할당할 수 없습니다. 예를 들어 시작 값이 1인 변수에는 숫자 유형이 할당됩니다. 이것을 "apples"의 문자열 값에 할당하려고 하면 오류가 발생합니다.

에이전트를 테스트할 때 변수가 일시적으로 알 수 없는 유형으로 나타날 수 있습니다. 알려지지 않은 변수에 아직 값이 할당되지 않았습니다.

변수의 순서는 제작 캔버스의 위에서 아래로 결정됩니다. 제작 캔버스의 맨 위에 있는 노드는 맨 아래에 있는 노드보다 먼저 고려됩니다.

조건 노드로 분기를 생성하면 분기는 왼쪽에서 오른쪽으로 정렬됩니다. 가장 왼쪽 분기의 노드는 가장 오른쪽 분기의 노드보다 먼저 고려됩니다.

엔터티

웹 앱

Copilot Studio는 엔터티를 사용하여 사용자의 응답에서 특정 유형의 정보를 식별합니다. 식별된 정보는 해당 정보에 적합한 유형의 변수에 저장됩니다. 다음 표에서는 미리 빌드된 엔터티와 연결된 변수 기본 형식을 보여 줍니다.

Entity	변수 기본 유형
다중 선택 옵션	선택 항목
사용자의 전체 응답	String
나이	숫자
부울	부울
시/군/구	String
색상	String
대륙	String
국가 또는 지역	String
날짜 및 시간	날짜/시간
Email	String
이벤트	String
Integer	Integer
언어	String
Money	숫자
숫자	숫자
서수	숫자
조직	String
백분율	숫자
인물 이름	String
전화번호	String
관심 지점	String
속도	숫자
시	String
상세 주소	String
Temperature	숫자
URL	String
두께	숫자
우편 번호	String
사용자 지정 엔터티	선택 항목

클래식

Copilot Studio는 엔터티를 사용하여 사용자의 응답에서 특정 유형의 정보를 식별합니다. 변수 유형은 저장될 때 식별된 정보와 연결됩니다. 변수 유형은 엔터티와 유사합니다.

각 엔터티 또는 변수 유형은 다음 표에 나열된 대로 기본 유형에 매핑됩니다. 기본 유형은 해당 변수로 논리식을 구성할 때 사용할 수 있는 연산자를 결정합니다. 또한 변수를 흐름 또는 Bot Framework 기술에 입력 매개 변수로 입력할 수 있는지 결정합니다.

예를 들어, 부울 기본 유형은 가능한 값이 True 또는 False인 "같음" 연산자에 매핑됩니다. 숫자 기본 유형은 "~와 같음", "~보다 큼" 또는 "~보다 크거나 같음" 등과 같은 숫자 연산자를 제공합니다.

엔터티	변수 기본 유형
다중 선택 옵션	String
사용자의 전체 응답	String
나이	숫자
부울	부울
시/군/구	String
색상	String
대륙	String
국가 또는 지역	String
날짜 및 시간	String
길이	String
Email	String
이벤트	String
언어	String
Money	String
숫자	String
서수	String
조직	String
백분율	숫자
인물 이름	String
전화번호	String
관심 지점	String
속도	숫자
시	String
상세 주소	String
Temperature	숫자
URL	String
두께	숫자
우편 번호	String
사용자 지정 엔터티	String

환경 변수

환경 변수는 Power Platform 개념입니다. 환경 변수는 Power Platform 환경 간에 애플리케이션을 이동하는 기본 ALM(애플리케이션 수명 주기 관리) 시나리오를 활성화합니다. 이 시나리오에서 애플리케이션은 소스 환경과 대상 환경 사이에 몇 가지 주요 외부 참조가 다르다는 점을 제외하고는 정확히 동일하게 유지됩니다.

환경 변수는 토픽, 전역, 시스템 변수와 같은 방식으로 사용합니다. 주목할 만한 차이점 중 하나는 Copilot Studio에서는 환경 변수가 읽기 전용이라는 것입니다. 에이전트 작성자는 Copilot Studio에서 환경 변수를 수정할 수 없습니다. 그러나 관리자는 Power Apps에서 환경 변수의 값을 변경할 수 있습니다. Copilot Studio에서는 변수 패널을 사용하여 환경 변수에 대한 정보를 볼 수 있습니다. 변수 패널에는 기본 작성 환경에 대한 링크도 있습니다.

환경 변수를 사용하는 에이전트의 게시된 버전은 에이전트가 게시될 때 설정된 이러한 변수의 값이 포함되어 있습니다. 관리자가 환경 변수를 업데이트할 때마다 런타임에 변경사항을 적용하려면 이러한 변수를 사용하는 에이전트를 다시 게시해야 합니다. 그러나 한 가지 예외는 비밀 형식의 환경 변수 값이 변경될 때 에이전트를 다시 게시할 필요가 없다는 것입니다. 다른 환경 변수와 달리 비밀 변수는 런타임에 검색됩니다.

Copilot Studio의 환경 변수 유형은 다음과 같이 Power Apps 데이터 유형에 매핑됩니다.

Copilot Studio의 유형	Power Apps의 유형
10진수	숫자
JSON	값에서 유형을 감지합니다. JSON이 아니라면 => 지정되지 않음(유효성 검사 오류)
문자	String
예/아니요	부울
Data source	String
암호	String

참고

환경 변수 오류는 테스트 채팅 및 게시 시 표시됩니다. 그러나 이러한 오류는 토픽 변수가 아니기 때문에 토픽 목록에 표시되지 않습니다.

시스템 변수

모든 에이전트에는 대화에 대한 추가 정보를 제공하는 시스템 변수가 내장되어 있습니다.

참고

음성 지원 에이전트 변수에 대한 자세한 내용은 음성 변수 사용을 참조하세요.

일부 시스템 변수는 목록에 표시되지 않습니다. Power Fx 수식을 사용하여 이러한 숨겨진 시스템 변수에 액세스해야 합니다.

Power Fx 수식에서 시스템 변수를 사용하려면 변수 이름 앞에 System.을 추가해야 합니다. 예를 들어 시스템 변수 User.DisplayName을 수식에 포함하려면 System.User.DisplayName이라고 합니다.

입력	Type	정의
Activity.Attachments	테이블	사용자가 제공한 파일 첨부
Activity.Channel	선택 항목	현재 대화의 채널 ID
Activity.ChannelData	모두	채널별 콘텐츠가 포함된 개체
Activity.ChannelId	string	현재 대화의 채널 ID(문자열)
Activity.From.Id	string	보낸 사람의 채널별 고유 ID
Activity.From.Name	string	보낸 사람의 채널별 사용자 식별 이름
Activity.Name	string	이벤트의 이름
Activity.Recipient.Id	string	수신 활동의 Type 속성입니다.
Activity.Recipient.Name	string	채널 내 에이전트의 표시 이름을 나타냅니다. 전화 통신 채널 컨텍스트에서 이 변수의 값은 에이전트가 연결된 전화 번호입니다.
Activity.Text	string	사용자가 보낸 가장 최근 메시지
Activity.Type	선택 항목	활동의 유형
Activity.TypeId	string	활동의 유형(문자열)
Activity.Value	모두	열린-종료된 값
Bot.EnvironmentId	string	에이전트의 환경 ID
Bot.Id	string	에이전트의 ID
Bot.Name	string	에이전트의 이름
Bot.SchemaName	string	에이전트의 스키마 이름
Bot.TenantId	string	에이전트의 테넌트 ID
ClientPluginActions	선택 항목	생성형 오케스트레이션을 위해 고려해야 할 동적 클라이언트 플러그 인 작업 모음
Conversation.Id	string	현재 대화의 고유 ID
Conversation.InTestMode	부울	대화가 테스트 캔버스에서 발생하고 있는지 여부를 나타내는 부울 플래그
Conversation.LocalTimeZone	string	IANA 표준 시간대 데이터베이스 형식으로 사용자가 사용할 표준 시간대의 이름
Conversation.LocalTimeZoneOffset	datetime	현재 로컬 시간대에 대한 UTC로부터의 시간 오프셋
Error.Code	string	현재 오류에 대한 오류 코드입니다. 현재 오류에 대한 오류 메시지입니다.
Error.Message	string	현재 오류에 대한 오류 메시지입니다. 참고: 이 변수는 트리거가 On Error인 경우에만 지원됩니다.
FallbackCount	번호	이 변수는 토픽이 사용자 입력과 일치하지 않는 횟수를 계산합니다. 참고: 이 변수는 트리거가 On Unknown Intent인 경우에만 지원됩니다.
InactivityTimer.Continue	부울	타이머를 계속해야 하는지 여부를 나타내는 부울 플래그입니다. 참고: 이 변수는 트리거가 Inactivity인 경우에만 지원됩니다.
InactivityTimer.Count	번호	구성된 시간이 지난 후 사용자가 활동하지 않아 OnInactivity 타이머가 실행된 횟수입니다. 참고: 이 변수는 트리거가 Inactivity인 경우에만 지원됩니다.
LastMessage.Id	string	사용자가 이전에 보낸 메시지의 ID
LastMessage.Text	string	사용자가 이전에 보낸 메시지
Recognizer.ExtractedEntities	선택 항목	트리거 메시지에서 추출된 엔터티를 나타냅니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다.
Recognizer.IntentOptions	선택 항목	인식기가 모호한 결과를 반환할 때의 의도 옵션을 나타냅니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다.
Recognizer.SelectedIntent	선택 항목	인식기에서 선택된 의도를 나타냅니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다.
Recognizer.TriggeringMessage.Id	string	현재 토픽을 트리거한 사용자 메시지의 ID
Recognizer.TriggeringMessage.Text	string	현재 토픽을 트리거한 사용자 메시지
Recognizer.MultipleTopicsMatchedReason	string	여러 주제가 일치하는 이유를 확인하는 데 사용됩니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다.
SignInReason	선택 항목	토픽을 트리거할 때 필요한 로그인 옵션을 결정하는 데 사용됩니다. 참고: 이 변수는 트리거가 On Sign In인 경우에만 지원됩니다.
User.Language	선택 항목	이 변수는 대화당 사용자 언어 로캘을 설정하는 데 사용됩니다.

통합 인증을 위한 변수(기본값)

Microsoft로 인증하도록 구성된 에이전트에 사용할 수 있는 변수는 다음과 같습니다. 이 구성은 Microsoft Entra ID 인증을 사용하며 새 에이전트의 기본값입니다.

자세한 내용은 인증 변수를 참조하세요.

입력	Type	정의
User.DisplayName	string	현재 에이전트와 대화하고 있는 사용자의 표시 이름입니다.
User.Email	string	현재 에이전트와 대화하고 있는 사용자의 이메일 주소입니다.
User.FirstName	string	현재 에이전트와 대화하는 사용자의 이름입니다.
User.Id	string	현재 에이전트와 대화하고 있는 사용자의 고유 ID입니다.
User.IsLoggedIn	부울	현재 에이전트와 대화하는 사용자가 인증되었는지 여부를 나타내는 부울 플래그입니다.
User.LastName	string	현재 에이전트와 대화 중인 사용자의 성입니다.
User.PrincipalName	string	현재 에이전트와 대화하는 사용자의 사용자 계정 이름입니다.

일반 OAuth 2를 사용한 수동 인증 변수

다음 변수는 일반 OAuth 2 서비스 제공자를 사용하도록 구성된 에이전트에 사용할 수 있습니다.

입력	Type	정의
User.AccessToken	string	에이전트로 인증하는 사용자의 액세스 토큰입니다.
User.DisplayName	string	현재 에이전트와 대화하고 있는 사용자의 표시 이름입니다.
User.Id	string	현재 에이전트와 대화하고 있는 사용자의 고유 ID입니다.
User.IsLoggedIn	부울	현재 에이전트와 대화하는 사용자가 인증되었는지 여부를 나타내는 부울 플래그입니다.

Microsoft Entra ID를 사용한 수동 인증을 위한 변수

Microsoft Entra ID(이전의 Azure Active Directory) 서비스 공급자를 사용하도록 구성된 에이전트에 사용할 수 있는 변수는 다음과 같습니다.

입력	Type	정의
User.AccessToken	string	에이전트로 인증하는 사용자의 액세스 토큰입니다.
User.DisplayName	string	현재 에이전트와 대화하고 있는 사용자의 표시 이름입니다.
User.Email	string	현재 에이전트와 대화하고 있는 사용자의 이메일 주소입니다.
User.FirstName	string	현재 에이전트와 대화하는 사용자의 이름입니다.
User.Id	string	현재 에이전트와 대화하고 있는 사용자의 고유 ID입니다.
User.IsLoggedIn	부울	현재 에이전트와 대화하는 사용자가 인증되었는지 여부를 나타내는 부울 플래그입니다.
User.LastName	string	현재 에이전트와 대화 중인 사용자의 성입니다.
User.PrincipalName	string	현재 에이전트와 대화 중인 사용자의 보안 주체 이름입니다.

음성 사용 에이전트에 대한 변수

다음 변수는 음성 지원 에이전트에서만 사용할 수 있습니다.

참고

음성 지원 에이전트 변수에 대한 자세한 내용은 음성 변수 사용을 참조하세요.

입력	Type	정의
Activity.InputDTMFKeys	string	전화 통신에서 수신된 원시 DTMF 키 값입니다.
Activity.SpeechRecognition.Confidence	번호	Azure Site Recovery 가설 전체 결과에 대한 신뢰도 점수는 0에서 1 사이입니다.
Activity.SpeechRecognition.MinimallyFormattedText	string	Azure Site Recovery 가설 결과에 대한 약간의 서식이 지정된 텍스트입니다. 예를 들어, "500달러"입니다. 단어의 철자가 명시되어 있지만 기본적인 대문자와 구두점이 포함되어 있습니다.
Activity.UserInputType	선택 항목	사용자의 가장 최근 입력의 입력 유형입니다. 값은 테스트, 음성 또는 DTMF일 수 있습니다.
Conversation.OnlyAllowDTMF	부울	런타임 시 IVR을 DTMF 전용 모드로 설정해야 하는지 여부를 나타내는 부울 플래그입니다.
Conversation.SipUuiHeaderValue	string	통화 시작 시 IVR에 컨텍스트를 전달하는 데 사용되는 UUI 헤더 문자열입니다.