에이전트 단계
에이전트 단계를 사용하면 AI 기반 의사결정 및 콘텐츠 생성을 Canvas 워크플로에 직접 추가할 수 있습니다. 보다 일반적인 정보는 Braze 에이전트를 참조하세요.

필수 조건
에이전트 단계는 Canvas 컨텍스트 변수를 사용하여 관련 컨텍스트를 수집하고, Canvas에서 활용할 수 있는 변수를 출력합니다.
작동 방식
사용자가 Canvas에서 에이전트 단계에 도달하면 Braze는 설정한 입력 데이터(전체 컨텍스트 또는 선택한 필드)를 선택한 에이전트로 전송합니다. 에이전트는 모델과 지침을 사용해 입력을 처리한 후 출력을 반환합니다. 이 출력은 단계에서 정의한 출력 변수에 저장됩니다.
이 변수는 크게 세 가지 방식으로 사용할 수 있습니다.
- 의사 결정: 에이전트의 응답에 따라 사용자를 서로 다른 Canvas 경로로 라우팅합니다. 예를 들어 리드 스코어링 에이전트는 “Sales Ready”, “Marketing Qualified”, “Disqualified” 같은 리드 카테고리를 반환할 수 있습니다. 이 할당을 활용해 “Sales Ready” 리드에는 Slack 알림이나 자동 메시지를 트리거하고, “Disqualified” 리드는 여정에서 제외할 수 있습니다.
- 개인화: 에이전트의 응답을 메시지에 직접 삽입합니다. 예를 들어 에이전트가 고객 피드백을 분석한 후, 고객의 의견을 언급하고 해결 방안을 제안하는 공감 어린 후속 이메일을 생성할 수 있습니다.
- 사용자 데이터 처리: 사용자 데이터를 분석하고 표준화한 후 고객 프로필에 저장하거나 웹훅으로 전송합니다. 예를 들어 에이전트가 감정 점수나 제품 친밀도 할당을 반환할 수 있습니다. 이 데이터를 고객 프로필에 저장해 향후에 활용할 수 있습니다.
에이전트 단계 만들기
1단계: 단계 추가
사이드바에서 에이전트 컴포넌트를 끌어다 놓거나, 단계 하단의 더하기 버튼을 선택한 다음 에이전트를 선택합니다.
2단계: 에이전트 선택
이 단계에서 데이터를 처리할 에이전트를 선택합니다. 설정 방법은 커스텀 에이전트 만들기를 참조하세요.
에이전트 목록에는 각 에이전트의 일일 호출 한도가 표시됩니다. 한도 위에 마우스를 올리면 사용 비율과 한도 대비 오늘 사용한 호출 수 등 오늘의 한도 진행 상황을 확인할 수 있습니다.

3단계: 에이전트 출력 설정
에이전트 출력은 ‘출력 변수’라고 하며, 쉽게 액세스할 수 있도록 컨텍스트 변수에 저장됩니다. 출력 변수를 정의하려면 변수에 이름을 지정하세요.
출력 변수의 데이터 유형은 에이전트 콘솔에서 설정됩니다. 에이전트 출력은 문자열, 숫자, 부울 또는 객체로 저장할 수 있습니다. 따라서 Canvas에서 텍스트 개인화와 조건 로직 모두에 유연하게 활용할 수 있습니다. 다음은 유형별 일반적인 사용 예시입니다.
| 데이터 유형 | 일반적인 용도 |
|---|---|
| 문자열 | 메시지 개인화(제목란, 본문, 응답) |
| 숫자 | 점수 산정, 임계값, 오디언스 경로에서의 라우팅 |
| 부울 | 결정 분할에서의 예/아니요 분기 |
| 객체 | 이 섹션 앞부분에 나온 데이터 유형 중 하나 이상을 예측 가능한 데이터 구조로 단일 LLM 호출에서 활용 |
컨텍스트 변수와 동일한 템플릿 구문을 사용하여 Canvas 전체에서 출력 변수를 사용할 수 있습니다. 컨텍스트 변수 Segment 필터를 사용하거나, Liquid를 사용하여 에이전트 응답을 직접 템플릿으로 사용하세요: {{context.${response_variable_name}}} .
객체 출력 변수의 특정 속성을 사용하려면 Liquid에서 점 표기법으로 해당 속성에 액세스하세요: {{context.${response_variable_name}.field_name}}

4단계: 선택적 단계 지침 추가
에이전트의 기본 지침에서 다루지 않는, 이 단계에만 해당하는 내용을 에이전트에 알려주는 선택적 단계 지침을 포함할 수 있습니다.
Canvas에서 일반적으로 사용하는 Liquid 템플릿 값을 입력할 수 있습니다. 단계 지침에는 abort_message를 포함할 수 없습니다.
5단계: 에이전트 테스트
에이전트 단계는 두 가지 방법으로 테스트할 수 있습니다.
단계 내 미리보기(Canvas 빌더): 단계를 구성한 후 단계 미리보기를 사용하여 무작위 사용자, 기존 사용자 또는 커스텀 사용자에 대한 에이전트 출력을 확인합니다. 이 방법은 전체 Canvas 경로를 거치지 않고 해당 단계만 따로 테스트합니다.
테스트 Canvas(전체 여정): Canvas 하단에서 테스트 Canvas를 선택하여 사용자 경로를 처음부터 끝까지 미리 봅니다. 테스트가 에이전트 단계에 도달하면 Braze에서 에이전트 “{agentName}”을(를) 실행하시겠습니까?라고 묻습니다.
- 예를 선택하여 필요에 따라 컨텍스트를 추가한 다음 응답 시뮬레이션을 선택하면 미리보기 사용자에 대해 에이전트가 호출됩니다. 샘플 입력(예: 장바구니 내용 또는 메시지 텍스트)을 일반 언어로 설명하여 테스트 사용자의 프로필과 업스트림에서 이미 설정된 Canvas 컨텍스트를 보완할 수 있습니다.
- 아니요를 선택하면 실시간 호출을 건너뛰고 대신 에이전트 콘솔에서 구성한 에이전트의 대체 출력을 사용합니다.
응답 시뮬레이션을 통한 호출은 에이전트의 일일 호출 한도에 포함되며 에이전트의 로그 탭에 표시됩니다. 테스트 Canvas의 전체 동작은 사용자 경로 미리보기를 참조하세요.

오류 처리
Braze가 에이전트 실패, 사용량 제한 오류 및 호출 흐름 제어를 처리하는 방법에 대해서는 에이전트 배포의 오류 처리 및 대체 동작과 Braze 에이전트의 오류 처리를 참조하세요.
- 연결된 모델이 LLM 공급자로부터 사용량 제한 오류를 반환하면, Braze는 호출이 성공하거나 완료할 수 없다고 판단할 때까지 지수 백오프를 사용하여 요청을 지속적으로 재시도합니다. 이후 사용자는 다음 캔버스 단계로 진행합니다.
- 기타 실패(예: 타임아웃 오류 또는 잘못된 API 키)가 발생하거나 에이전트가 일일 호출 한도에 도달하면, 에이전트 콘솔에서 대체 값이 설정되어 있지 않은 한 출력 변수는
null로 설정됩니다. 대체 값이 설정된 경우, Braze는 사용자별로 Liquid를 사용하여 대체 값을 렌더링하고 그 결과를 출력 변수에 저장합니다. 일일 한도로 인해 호출이 차단된 경우에도 마찬가지입니다. - 대체 값을 설정하지 않은 경우, 다운스트림 메시지 단계에서 기본 Liquid 값을 사용하여 null 출력을 처리하세요. 예를 들어, 개인화 추가 Modal에서
{{context.${response_variable_name}.push_title | default: 'Hello friend!'}}또는{{context.${response_variable_name}.push_body | default: 'Open our app to get your prize!'}}와 같은 기본 Liquid 값을 입력할 수 있습니다. - 대체 출력이 특정 사용자에 대해
abort_message를 호출하면, Braze는 해당 사용자를 대체 값이 설정되지 않은 것처럼 처리합니다. 에이전트가 성공하면 대체 값은 사용되지 않으므로, 대체 값에 포함된abort_message호출은 영향을 미치지 않습니다. - 동일한 입력에 대한 응답은 캐시되며, 몇 분 이내에 반복되는 동일한 호출에 재사용될 수 있습니다.
- 캐시된 값을 사용하는 응답도 총 호출 수 및 일일 호출 수에 포함됩니다.
- 에이전트 단계는 대량의 사용자를 처리하는 데 시간이 걸릴 수 있습니다. Braze는 호출 흐름 제어에 따라 호출을 대기줄에 넣으므로, 대량 발송 시 사용자가 대기 상태로 남아 있을 수 있습니다. 로그를 확인하여 호출이 진행되고 있는지 확인하세요.
분석
다음 측정기준을 참고하여 에이전트 단계의 성과를 추적하세요.
| 측정기준 | 설명 |
|---|---|
| 진입 | 사용자가 에이전트 단계에 진입한 횟수입니다. |
| 다음 단계로 진행 | 에이전트 단계를 통과한 후 흐름의 다음 단계로 진행한 사용자 수입니다. |
| Canvas 종료 | 에이전트 단계를 통과한 후 Canvas를 종료한 사용자 수입니다. |
모범 사례
복잡한 사용 사례에서는 에이전트 간에 작업 분할하기
에이전트가 요청한 작업의 복잡성을 처리하는 데 어려움을 겪는다면 작업을 둘 이상의 에이전트 단계로 나누세요. 하나의 프롬프트에 데이터 정리, 라우팅 로직, 전체 메시지 작성을 모두 담으면 목표끼리 충돌해 출력 품질이 들쭉날쭉해질 수 있습니다.
다음은 여행 사례에서 세 개의 에이전트를 사용하는 패턴입니다. 최근 앱에서 검색했지만 예약하지 않은 사용자에게 결제를 유도하는 리타겟팅 문구를 보내려는 상황입니다.
- 에이전트 1은 Canvas 컨텍스트를 요약합니다. 로열티 등급, 마지막으로 검색한 도시, 구매 의도가 높은 검색 행동과 같은 필드를 읽고, 이후 단계에서 재사용할 수 있도록 짧은 구조화된 요약을 출력 변수로 반환합니다.
- 에이전트 2는 Canvas에서 분기할 수 있는 라우팅 값을 반환합니다. 분기 방식에 맞게 숫자, 불리언 또는 구조화된 객체를 사용하세요. 이 값을 오디언스 경로 또는 결정 분할 단계에 매핑합니다. 예를 들어 로열티 중심 메시징과 할인 중심 메시징을 위한 경로를 따로 구성하는 것을 고려해 보세요.
- 에이전트 3은 생성형 메시지 텍스트가 필요한 분기에서만 메시지 초안을 작성합니다. 에이전트 1의 요약(및 분기별 컨텍스트)을 전달하면, 이 에이전트는 같은 프롬프트에서 입력을 정규화하고 전략을 선택하는 대신 어조와 채널 제한에 집중할 수 있습니다.
실험 경로 단계를 사용하여 에이전트 기반 여정을 소규모로 테스트하기
기존 여정과 비교하여 에이전트의 성능과 크레딧 소비량을 테스트하려면 실험 경로 단계를 추가하여 오디언스의 일부만 에이전트 단계가 포함된 분기에 진입하도록 하세요.
예를 들어 처음에는 하루에 수천 명의 사용자만 에이전트가 있는 경로로 보내고, 나머지는 대조군 경로나 에이전트가 없는 경로로 보낼 수 있습니다. 1~2주 동안 데이터를 수집한 다음 경로 간 핵심 성과 지표(KPI), 카운터 측정기준, 에이전트 크레딧 소비량을 비교하세요. 이렇게 하면 에이전트가 활성화된 분기로 트래픽을 늘리기 전에 확신을 쌓고 ROI를 입증할 수 있으며, 그 과정에서 호출 소비량도 제한할 수 있습니다.
자주 묻는 질문
에이전트 단계는 언제 사용해야 하나요?
일반적으로 특정 상황별 데이터를 LLM에 제공하고, 사람이 처리할 수 없는 규모로 LLM이 에이전트 방식으로 Canvas 컨텍스트 변수를 지능적으로 할당하도록 하려는 경우 에이전트 단계를 사용하는 것을 권장합니다.
예를 들어, 이전에 초콜릿과 딸기 맛을 주문한 사용자에게 새로운 아이스크림 맛을 추천하는 개인화된 메시지를 보낸다고 가정해 보겠습니다. 에이전트 단계와 AI 아이템 추천을 사용할 때의 차이점은 다음과 같습니다.
- 에이전트 단계: LLM을 사용하여 에이전트에 제공된 지침과 컨텍스트 데이터 포인트를 바탕으로 사용자가 원할 만한 것에 대해 정성적인 결정을 내립니다. 이 예시에서 에이전트 단계는 사용자가 다양한 맛을 시도해 보고 싶어 할 가능성을 고려해 새로운 맛을 추천할 수 있습니다.
- AI 아이템 추천: 머신 러닝 모델을 사용하여 구매와 같은 과거 사용자 이벤트를 바탕으로 사용자가 원할 가능성이 가장 높은 제품을 예측합니다. 이 예시에서 AI 아이템 추천은 사용자의 이전 두 주문(초콜릿과 딸기)과 이를 워크스페이스 내 다른 사용자의 행동과 비교한 결과를 바탕으로 맛(바닐라)을 추천합니다.
에이전트 단계는 입력 데이터를 어떻게 사용하나요?
에이전트 단계는 에이전트가 사용하도록 구성된 컨텍스트 데이터와 단계에 추가한 선택적 단계 지침을 분석합니다.