메모
이 문서의 기능은 standard harness를 기반으로 하며, standard harness 기반 에이전트의 라이선스에 설명된 청구 옵션을 사용합니다. Access 표준 에이전트와 에이전트 플로우에서 표준 기능에 접근하는 방법을 배워보세요.
변수는 네 가지 수준 또는 범위에 존재합니다.
- 생성한 토픽에서만 사용할 수 있는 토픽 변수입니다. 이 범위는 생성하는 변수의 기본값입니다.
- 모든 토픽에서 사용할 수 있는 전역 변수. 토픽 변수의 범위를 변경하여 전역 변수로 만들 수 있습니다.
- 시스템 변수 Copilot Studio가 에이전트에 대해 자동으로 만듭니다. 대화 또는 사용자에 대한 더 많은 상황 정보를 제공합니다. 모든 토픽에서 사용할 수 있습니다.
- Power Platform에서 만드는 환경 변수. Copilot Studio에서 읽기 전용입니다. 이들은 매개 변수 키와 값을 저장하고, 이 키와 값은 Copilot Studio를 포함한 다양한 다른 애플리케이션 객체에 대한 입력으로 사용됩니다. 매개변수를 소비하는 객체와 분리하면, 같은 환경 내에서나 솔루션을 다른 환경으로 마이그레이션할 때 값을 변경할 수 있습니다. 대안은 이를 사용하는 구성 요소 내에 하드 코딩된 매개 변수 값을 남겨 두는 것입니다.
변수 유형
각 변수에는 기본 형식이 있습니다. 유형은 변수가 가질 수 있는 값과 이를 사용하여 논리 표현식을 작성할 때 사용할 수 있는 연산자를 결정합니다.
| 유형 | Description |
|---|---|
| String | 텍스트를 나타내는 데 사용되는 일련의 문자 |
| Boolean |
true 또는 false만 가능한 논리 값 |
| Number | 임의의 실수 |
| Table | 값 목록이지만 모든 값은 동일한 유형이어야 합니다 |
| Record | 값이 모든 유형일 수 있는 이름-값 쌍의 모음입니다 |
| 날짜/시간 | 특정 시점을 기준으로 한 날짜, 시간, 요일 또는 월입니다 |
| 선택 | 연관된 동의어가 있는 문자열 값 목록 |
| 빈 | "무가치" 또는 "알 수 없는 가치"의 자리 표시; Power FX 문서의 Blank 에서 더 자세히 알아보세요 |
변수의 유형은 변수에 값을 처음 할당할 때 설정합니다. 그 후에는 유형이 고정되고 다른 유형의 값을 할당할 수 없습니다. 예를 들어 시작 값 1을 변수에 할당하는 경우 해당 형식을 숫자로 설정합니다. 그런 다음, 과 같이 "apples" 값을 할당하려고 하면 오류가 발생합니다.
에이전트를 테스트할 때 변수가 일시적으로 알 수 없는 형식으로 나타날 수 있습니다. 알 수 없는 변수에는 아직 값이 없습니다.
변수의 순서는 저작 캔버스의 위에서 아래까지 결정됩니다. 에이전트는 저작 캔버스 상단의 노드를 하단의 노드보다 먼저 고려합니다.
조건 노드를 사용해 분기를 만들 때, Copilot Studio는 분기를 왼쪽에서 오른쪽으로 정렬합니다. 에이전트는 가장 왼쪽 분기의 노드들을 가장 오른쪽 분기의 노드보다 먼저 고려합니다.
Entities
Copilot Studio는 엔터티를 사용하여 사용자의 응답에서 특정 유형의 정보를 식별합니다. 식별된 정보는 해당 정보에 적합한 유형의 변수에 저장됩니다. 다음 표에서는 미리 빌드된 엔터티와 연결된 변수 기본 형식을 보여 줍니다.
| 개체 | 변수 기본 유형 |
|---|---|
| 다중 선택 옵션 | 선택 |
| 사용자의 전체 응답 | String |
| 나이 | Number |
| Boolean | Boolean |
| 도시 | String |
| 색깔 | String |
| Continent | String |
| 국가 또는 지역 | String |
| 날짜 및 시간 | 날짜/시간 |
| 전자 메일 | String |
| Event | String |
| 정수 | 정수 |
| 언어 | String |
| 돈 | Number |
| Number | Number |
| 서수 | Number |
| 조직 | String |
| 백분율 | Number |
| 인물 이름 | String |
| 전화번호 | String |
| 관심 지점 | String |
| 속도 | Number |
| 상태 | String |
| 도로명 주소 | String |
| 온도 | Number |
| URL | String |
| 무게 | Number |
| 우편 번호 | String |
| 사용자 지정 엔터티 | 선택 |
환경 변수
환경 변수는 Power Platform 컨셉입니다. 환경 변수는 Power Platform 환경 간에 애플리케이션을 이동하는 기본 ALM(애플리케이션 수명 주기 관리) 시나리오를 활성화합니다. 이 시나리오에서는 소스와 목적지 환경 간에 몇 가지 주요 외부 참조가 다르지만 애플리케이션은 완전히 동일하게 유지됩니다.
환경 변수는 topic, global, system 변수와 같은 방식으로 사용하세요. 한 가지 주목할 만한 차이점은 Copilot Studio에서 환경 변수가 읽기 전용이라는 것입니다. 에이전트 작성자는 Copilot Studio에서 환경 변수를 수정할 수 없습니다. 그러나 관리자는 Power Apps에서 환경 변수 값을 변경할 수 있습니다. Copilot Studio에서는 변수 패널을 사용하여 환경 변수에 대한 정보를 볼 수 있습니다. 변수 속성 패널에는 환경 변수에 대한 제작 환경인 Power Apps에 대한 링크도 있습니다.
환경 변수를 사용하는 에이전트의 공개된 버전에는 에이전트를 공개할 때 설정한 값들이 포함됩니다. 관리자가 환경 변수를 업데이트할 때마다, 변경 사항이 런타임에 적용되도록 해당 변수를 사용하는 에이전트를 다시 게시해야 합니다. 그러나 한 가지 예외는 비밀 형식의 환경 변수 값이 변경될 때 에이전트를 다시 게시할 필요가 없다는 것입니다. 다른 환경 변수와 달리 비밀 변수는 런타임에 검색됩니다.
Copilot Studio의 환경 변수 형식은 다음과 같이 Power Apps 데이터 형식에 매핑됩니다.
| Copilot Studio에서 입력하세요 | Power Apps에서 입력 |
|---|---|
| 10진수 | Number |
| JSON | 값에서 유형을 감지합니다. JSON이 아니라면 => 지정되지 않음(유효성 검사 오류) |
| Text | String |
| 예/아니요 | Boolean |
| 데이터 원본 | String |
| 비밀 | String |
메모
테스트 채팅과 게시 시 환경 변수 오류가 나타납니다. 하지만 환경 변수가 주제 변수가 아니기 때문에 이 오류들은 주제 목록에 나타나지 않습니다.
시스템 변수
모든 에이전트는 대화에 대한 추가 정보를 제공하는 내장 시스템 변수를 포함하고 있습니다.
Copilot Studio는 모든 시스템 변수를 표시하지 않습니다. 숨겨진 시스템 변수에 액세스하려면 Power Fx 수식을 사용합니다.
Power Fx 수식에서 시스템 변수를 사용하려면 변수 이름 앞에 System.를 추가합니다. 예를 들어 시스템 변수 User.DisplayName을 수식에 포함하려면 System.User.DisplayName이라고 합니다.
| Name | 유형 | Definition |
|---|---|---|
| Activity.Attachments | table | 사용자가 제공하는 첨부 파일입니다. |
| Activity.Channel | choice | 현재 대화의 채널 ID입니다. |
| Activity.ChannelData | 임의의 | 채널별 콘텐츠가 포함된 개체입니다. |
| Activity.ChannelId | string | 현재 대화의 채널 ID(문자열)입니다. |
| 액티비티.프롬.아이디 | string | 보낸 사람의 채널별 고유 ID입니다. |
| 활동.발신자.이름 | string | 보낸 사람의 채널별 사용자 식별 이름입니다. |
| 활동.이름 | string | 이벤트의 이름입니다. |
| Activity.Recipient.Id | string | 수신 활동의 Type 속성입니다. |
| Activity.수신자.이름 | string | 채널 내 에이전트의 표시 이름을 나타냅니다. 전화 통신 채널 컨텍스트에서 이 변수의 값은 에이전트가 연결된 전화 번호입니다. |
| Activity.Text | string | 사용자가 보낸 가장 최근 메시지입니다. |
| Activity.Type | choice | 활동의 유형입니다. |
| Activity.TypeId | string | 활동의 유형(문자열)입니다. |
| 활동.값 | 임의의 | 개방형 값입니다. |
| Bot.EnvironmentId | string | 에이전트의 환경 ID입니다. |
| 봇 ID | string | 에이전트의 ID입니다. |
| Bot.Name | string | 에이전트의 이름입니다. |
| Bot.SchemaName | string | 에이전트의 스키마 이름입니다. |
| Bot.TenantId (봇.테넌트ID) | string | 에이전트의 테넌트 ID입니다. |
| ClientPluginActions | choice | 생성형 오케스트레이션을 위해 고려해야 할 동적 클라이언트 플러그 인 작업 모음입니다. |
| Conversation.Id | string | 현재 대화의 고유 ID입니다. |
| 대화.테스트모드에서 | Boolean | 대화가 테스트 캔버스에서 발생하고 있는지 여부를 나타내는 부울 플래그입니다. |
| 대화.현지시간대 | string | IANA 표준 시간대 데이터베이스 형식으로 사용자가 사용할 표준 시간대의 이름입니다. |
| Conversation.LocalTimeZoneOffset | datetime | 현재 로컬 시간대에 대한 UTC로부터의 시간 오프셋입니다. |
| Error.Code | string | 현재 오류에 대한 오류 코드입니다. 현재 오류에 대한 오류 메시지입니다. |
| 오류 메시지 | string | 현재 오류에 대한 오류 메시지입니다. 참고: 이 변수는 트리거가 On Error인 경우에만 지원됩니다. |
| FallbackCount | number | 이 변수는 토픽이 사용자 입력과 일치하지 않는 횟수를 계산합니다. 참고: 이 변수는 트리거가 On Unknown Intent인 경우에만 지원됩니다. |
| InactivityTimer.Continue | Boolean | 타이머를 계속해야 하는지 여부를 나타내는 부울 플래그입니다. 참고: 이 변수는 트리거가 Inactivity인 경우에만 지원됩니다. |
| InactivityTimer.Count | number | 구성된 시간 이후 사용자의 비활성으로 인해 OnInactivity 타이머가 발생한 횟수입니다. 참고: 이 변수는 트리거가 Inactivity인 경우에만 지원됩니다.
비활성 트리거에 대해 자세히 알아보세요. |
| LastMessage.Id | string | 사용자가 이전에 보낸 메시지의 ID입니다. |
| LastMessage.Text | string | 사용자가 이전에 보낸 메시지입니다. |
| Recognizer.ExtractedEntities | choice | 트리거 메시지에서 추출된 엔터티를 나타냅니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다. |
| Recognizer.IntentOptions | choice | 인식기가 모호한 결과를 반환하는 경우의 의도 옵션을 나타냅니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다. |
| Recognizer.SelectedIntent | choice | 인식기에서 선택된 의도를 나타냅니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다. |
| Recognizer.TriggeringMessage.Id | string | 현재 토픽을 트리거한 사용자 메시지의 ID입니다. |
| Recognizer.TriggeringMessage.Text | string | 현재 토픽을 트리거한 사용자 메시지입니다. |
| 인식기.여러_주제_일치_이유 | string | 여러 주제가 일치하는 이유를 확인하는 데 사용됩니다. 참고: 이 변수는 트리거가 On Select Intent인 경우에만 지원됩니다. |
| 로그인 이유 | choice | 토픽을 트리거할 때 필요한 로그인 옵션을 결정하는 데 사용됩니다. 참고: 이 변수는 트리거가 On Sign In인 경우에만 지원됩니다. |
| 사용자.언어 | choice | 이 변수는 대화당 사용자 언어 로캘을 설정하는 데 사용됩니다. |
음성 사용 에이전트에 대한 변수
다음 변수는 음성 지원 에이전트에서만 사용할 수 있습니다. 더 알아보세요 : 음성 변수 사용하기.
| Name | 유형 | Definition |
|---|---|---|
| Activity.InputDTMFKeys | string | 전화 통신의 원시 DTMF 키 값입니다. |
| Activity.음성인식.신뢰도 | number | 자동 음성 인식 가설의 신뢰도 점수는 0에서 1 사이입니다. |
| 활동.음성인식.최소형식화텍스트 | string | 자동 음성 인식 가설 결과의 약간 형식화된 텍스트. 예를 들어, "Five hundred dollars." 단어는 철자로 전부 표기되지만, 기본적인 대문자 사용과 구두점이 포함되어 있습니다. |
| Activity.UserInputType | choice | 에이전트 사용자의 가장 최근 입력 유형입니다. 값은 테스트, 음성 또는 DTMF일 수 있습니다. |
| 대화.OnlyAllowDTMF | Boolean | 런타임 시 IVR을 DTMF 전용 모드로 설정해야 하는지 여부를 나타내는 부울 플래그입니다. |
| Conversation.SipUuiHeaderValue | string | 통화 시작 시 IVR에 컨텍스트를 전달하는 데 사용되는 UUI 헤더 문자열입니다. |
통합 인증을 위한 변수(기본값)
Microsoft로 인증하도록 구성된 에이전트에 사용할 수 있는 변수는 다음과 같습니다. 이 구성은 Microsoft Entra ID 인증을 사용하며 새 에이전트의 기본값입니다. 인증 변수에서 더 알아보세요.
| Name | 유형 | Definition |
|---|---|---|
| 사용자.표시이름 | string | 현재 에이전트와 대화하고 있는 사용자의 표시 이름입니다. |
| 사용자의 이메일 | string | 현재 에이전트와 대화하고 있는 사용자의 이메일 주소입니다. |
| User.FirstName | string | 현재 에이전트와 대화하는 사용자의 이름입니다. |
| 사용자 ID | string | 현재 에이전트와 대화하고 있는 사용자의 고유 ID입니다. |
| User.IsLoggedIn | Boolean | 현재 에이전트와 대화하는 사용자가 인증되었는지 여부를 나타내는 부울 플래그입니다. |
| User.LastName (사용자 성) | string | 현재 에이전트와 대화 중인 사용자의 성입니다. |
| 사용자.주사용자명 | string | 현재 에이전트와 대화하는 사용자의 사용자 계정 이름입니다. |
Generic OAuth 2를 사용한 수동 인증을 위한 변수
다음 변수는 일반 OAuth 2 서비스 제공자를 사용하도록 구성된 에이전트에 사용할 수 있습니다.
| Name | 유형 | Definition |
|---|---|---|
| 사용자.액세스토큰 | string | 에이전트로 인증하는 사용자의 액세스 토큰입니다. |
| 사용자.표시이름 | string | 현재 에이전트와 대화하고 있는 사용자의 표시 이름입니다. |
| 사용자 ID | string | 현재 에이전트와 대화하고 있는 사용자의 고유 ID입니다. |
| User.IsLoggedIn | Boolean | 현재 에이전트와 대화하는 사용자가 인증되었는지 여부를 나타내는 부울 플래그입니다. |
Microsoft Entra ID를 사용한 수동 인증을 위한 변수
다음 변수는 Microsoft Entra ID(이전의 Azure Active Directory) 서비스 제공자를 사용하도록 구성된 에이전트에 사용할 수 있습니다.
| Name | 유형 | Definition |
|---|---|---|
| 사용자.액세스토큰 | string | 에이전트로 인증하는 사용자의 액세스 토큰입니다. |
| 사용자.표시이름 | string | 현재 에이전트와 대화하고 있는 사용자의 표시 이름입니다. |
| 사용자의 이메일 | string | 현재 에이전트와 대화하고 있는 사용자의 이메일 주소입니다. |
| User.FirstName | string | 현재 에이전트와 대화하는 사용자의 이름입니다. |
| 사용자 ID | string | 현재 에이전트와 대화하고 있는 사용자의 고유 ID입니다. |
| User.IsLoggedIn | Boolean | 현재 에이전트와 대화하는 사용자가 인증되었는지 여부를 나타내는 부울 플래그입니다. |
| User.LastName (사용자 성) | string | 현재 에이전트와 대화 중인 사용자의 성입니다. |
| 사용자.주사용자명 | string | 현재 에이전트와 대화 중인 사용자의 기본 이름입니다. |