커스텀 에이전트 배포
에이전트를 생성한 후, 이 페이지에서 Braze에서 에이전트를 배포하는 위치와 방법을 알아보세요. 생성 시 선택한 에이전트 유형(Canvas 에이전트 또는 카탈로그 에이전트)에 따라 에이전트가 실행될 수 있는 위치가 결정됩니다. 소개는 Braze Agents를 참조하세요.
커스텀 에이전트 유형
커스텀 에이전트는 유형에 따라 Braze의 서로 다른 위치에 배포됩니다. 다음 표에서 에이전트에 맞는 배포 경로를 확인하세요.
| 에이전트 유형 | 배포 위치 | 실행 시점 | 섹션 |
|---|---|---|---|
| Canvas 단계 에이전트 | Canvas의 에이전트 단계 | 사용자가 단계에 진입할 때 | Canvas 단계 에이전트 사용 |
| 카탈로그 에이전트 | 카탈로그 필드 | 카탈로그 행이 생성되거나 업데이트될 때 | 카탈로그 에이전트 사용 |
에이전트 유형은 에이전트를 생성할 때 에이전트 콘솔에서 선택합니다. 설정 단계는 커스텀 에이전트 생성을 참조하세요.
모범 사례
에이전트가 가장 큰 투자수익률(ROI)을 낼 수 있는 고가치 사용 사례를 목표로 삼고, 반응할 가능성이 높은 오디언스를 선택하세요. 규모가 작더라도 기회가 큰 오디언스가 기회가 적은 대규모 오디언스보다 더 좋은 성과를 내는 경우가 많습니다.
캔버스 단계 에이전트는 최근 검색, 높은 인게이지먼트, 풍부한 프로필 데이터처럼 신호가 강한 사용자부터 시작한 뒤 더 넓은 Segments로 확장하세요. 카탈로그 에이전트는 필요한 입력 열이 이미 채워져 있는 행을 우선 처리해야 각 호출이 유용한 결과를 생성할 만큼 충분한 컨텍스트를 확보할 수 있습니다.
에이전트를 광범위하게 출시하기 전에 소규모로 ROI를 테스트하려면 실험 경로 단계를 사용하세요. 이렇게 하면 오디언스의 일부만 에이전트 단계가 포함된 브랜치로 진입합니다.
테스트 성공 후 확장하기
소규모 테스트(예: 실험 경로 브랜치)에서 품질과 ROI가 만족스러운 것으로 확인되면, 테스트 그룹뿐만 아니라 전체 타겟 오디언스에 에이전트를 출시하여 모든 대상 사용자가 혜택을 받을 수 있도록 계획하세요.
확장하기 전에 다음 사항을 고려하세요.
- Agent Console에서 에이전트의 일일 호출 한도를 늘려 전체 오디언스 규모를 처리할 수 있도록 하세요. 기본값은 250,000이며, 최대 1,000,000까지 늘릴 수 있습니다(고객 성공 매니저와 협의하면 그 이상도 가능). 일일 호출 및 크레딧 한도를 참조하세요.
- 일일 액션 크레딧 비용 한도 예상치를 검토하고, 워크스페이스에 전체 규모 발송에 충분한 크레딧이 있는지 확인하세요.
- 실험을 제거하거나 다시 구성하여 타겟 오디언스 전체가 에이전트 단계로 진입하도록 하세요(또는 우승 배리언트를 메인 경로로 승격하세요).
전체 오디언스로 확장하면 크레딧 소비도 비례하여 증가합니다. 출시 후에는 설정 > 청구 > 크레딧 사용량 > Agent Console에서 사용량을 모니터링하세요.
Canvas 단계 에이전트 사용
Canvas 단계 에이전트를 만든 후에는 Canvas에 에이전트 단계로 추가해 메시지를 개인화하거나 실시간으로 의사결정을 이끌 수 있습니다.
작동 방식
사용자가 Canvas의 에이전트 단계에 도달하면 Braze는 설정한 입력 데이터를 에이전트에 보냅니다. 에이전트는 모델과 지침에 따라 입력을 처리한 다음, 단계에서 정의한 출력 변수에 저장되는 출력을 반환합니다. 이 출력은 의사결정, 개인화 또는 후속 처리에 사용할 수 있습니다.
에이전트 단계는 Canvas 컨텍스트 변수를 사용해 관련 컨텍스트를 수집하고, Canvas에서 사용할 수 있는 변수를 출력합니다. 사전 요구 사항과 전체 참조 정보는 에이전트 단계를 참조하세요.
에이전트 단계 추가
Canvas에 에이전트를 추가하려면 다음 단계를 따르세요.
- 사이드바에서 에이전트 컴포넌트를 끌어다 놓거나, 단계 하단의 더하기 버튼을 선택한 다음 에이전트를 선택합니다.
- 이 단계에서 데이터를 처리할 에이전트를 선택합니다.
- 출력 변수 이름을 정의합니다. 출력 데이터 유형은 에이전트 콘솔에서 설정합니다.
- (선택 사항) 에이전트가 실행될 때 참조할 추가 컨텍스트 값을 추가합니다. 여기에는 에이전트 설정에서 아직 바인딩하지 않은 추가 Liquid 변수나 Canvas 컨텍스트가 포함될 수 있습니다. 예를 들어 이 단계에서 발송 시점에만 전달하려는 값이 있습니다.
- 단계 내 미리보기 또는 Canvas 테스트를 사용해 에이전트를 테스트하고 전체 사용자 경로를 확인합니다.
출력 데이터 유형, Liquid 템플릿, 스크린샷은 에이전트 단계를 참조하세요.
사용 사례
| 사용 사례 | 설명 |
|---|---|
| 리드 점수 산정 및 자격 평가 | 에이전트 단계를 사용해 유입되는 리드를 특정 척도(예: 1~10)로 평가합니다. 점수가 임계값을 넘는 사용자는 육성 경로로 보내고, 적합도가 낮은 리드는 제외합니다. |
| 동적 메시지 개인화 | 에이전트가 사용자 속성이나 최근 행동을 바탕으로 제목란, 제품 추천 또는 메시지 문구를 생성하도록 합니다. 응답은 메시지 단계에 바로 삽입할 수 있습니다. |
| 고객 피드백 처리 | 고객 의견을 에이전트에 전달해 감정을 분석하고 공감하는 후속 메시지를 생성합니다. 고가치 사용자의 경우 에이전트가 응답을 에스컬레이션하거나 혜택을 포함할 수 있습니다. |
| 지능형 라우팅 | 에이전트 출력(불리언 또는 숫자)을 사용해 사용자를 서로 다른 Canvas 경로로 분할합니다. 예를 들어 사용자를 “이탈 위험” 또는 “양호”로 분류하고 그에 따라 메시징 주기를 조정합니다. |
| 설문조사 또는 응답 해석 | 에이전트가 주관식 설문조사 응답이나 자유 텍스트 필드를 분석하고, 후속 경로를 결정하는 구조화된 값(예: 의도 또는 필요 분류)을 반환하도록 합니다. |
| 다단계 추론 | 에이전트가 여러 컨텍스트 필드를 결합해 복잡한 결정을 내리도록 구성합니다. 예를 들어 여러 사용자 속성을 바탕으로 다음 최선의 조치(이메일, SMS 또는 직접 연락)를 추천할 수 있습니다. |
에이전트 출력 사용
에이전트가 실행된 후 Canvas에서 출력 변수를 다음과 같이 사용할 수 있습니다.
- 여정 라우팅: 에이전트의 응답에 따라 사용자를 서로 다른 Canvas 경로로 보냅니다. 숫자, 불리언 또는 구조화된 출력과 함께 오디언스 경로 또는 결정 분할을 사용하세요.
- 개인화: Liquid를 사용해 에이전트의 응답을 메시지 단계에 바로 삽입합니다.
- 사용자 데이터 처리: 사용자 데이터를 분석하고 표준화한 다음 고객 프로필에 저장하거나(예: 사용자 업데이트 단계 사용) 웹훅으로 보냅니다.
예시는 에이전트 단계의 작동 방식을 참조하세요.
오류 처리 및 대체 동작
다음 내용은 에이전트 단계의 Canvas 단계 에이전트에 적용됩니다.
- 연결된 모델이 LLM 제공업체로부터 사용량 제한 오류를 반환하면, Braze는 호출이 성공하거나 완료할 수 없다고 판단할 때까지 지수 백오프를 사용해 요청을 계속 재시도합니다. 그런 다음 사용자는 다음 캔버스 단계로 진행합니다.
- 다른 실패(예: 시간 초과 또는 잘못된 API 키)의 경우, 에이전트 콘솔에서 에이전트에 대체 값이 구성되어 있지 않으면 출력 변수가
null로 설정됩니다. - 에이전트가 일일 호출 한도에 도달한 경우에도 Braze는 구성된 대체 값이 있으면 이를 적용하고, 없으면 출력 변수를
null로 설정합니다.
대체 값이 구성되어 있으면 Braze는 재시도할 수 없는 오류와 일일 한도 실패에 대해 이를 적용합니다. Braze는 사용자별로 Liquid를 사용해 대체 값을 렌더링하고, 그 결과를 에이전트 단계 출력 변수에 저장합니다. 대체 값이 없으면 이러한 실패 시 출력 변수가 null로 설정됩니다. 에이전트 콘솔의 대체 값 대신 메시지 단계에서 단계별 기본값을 구성하려는 경우, 후속 단계에서 Liquid 기본값을 사용할 수 있습니다. 이렇게 하려면 에이전트 설정의 출력 섹션에서 대체 값을 비워 두어, 에이전트가 null을 반환할 때 Liquid 기본값이 적용되도록 하세요.
사용량 제한 오류, 모델 사용 불가, 일일 호출 한도 실패는 Braze 크레딧을 소비하지 않습니다. 시간 초과는 크레딧을 소비합니다. 크레딧이 소비되는 경우를 참조하세요.
- 동일한 입력에 대한 응답은 캐시되며, 몇 분 내에 반복되는 동일한 호출에 재사용될 수 있습니다. 캐시된 응답도 총 호출 수와 일일 호출 수에 포함됩니다.
- 에이전트 단계는 대규모 사용자 배치를 처리하는 데 시간이 걸릴 수 있습니다. Braze는 호출 흐름 제어에 따라 호출을 대기줄에 넣으므로, 대량 발송 중에는 사용자가 대기 상태로 남아 있을 수 있습니다.
에이전트 단계 설정 및 런타임 세부 정보는 에이전트 단계의 오류 처리를 참조하세요. 자세한 내용은 Braze Agents의 오류 처리를 참조하세요.
카탈로그 에이전트 사용
카탈로그 에이전트를 만든 후 카탈로그 필드에 적용하면 각 행의 값을 자동으로 생성하거나 계산할 수 있습니다. 에이전트는 이후 카탈로그에 추가되는 새 행에서도 실행됩니다.
작동 방식
에이전트를 시작하면 각 행을 평가하고, 선택한 열을 컨텍스트로 사용해 출력을 생성합니다. 에이전트를 배포한 후에 추가된 모든 새 행에서도 에이전트가 실행됩니다. 카탈로그 행 업데이트 시 재계산을 선택한 경우, 기존 소스 필드가 변경되면 이 필드의 모든 값이 업데이트됩니다.
카탈로그 에이전트의 입력 열을 구성할 때는 에이전트가 호출되기 전에 실행에 필요한 열을 표시하는 제품 내 컨트롤을 활성화하세요(워크스페이스에 따라 레이블이 약간 다를 수 있습니다). 이 컨트롤을 활성화한 상태에서 반드시 값이 있어야 하는 열을 선택합니다. 선택한 열은 기본적으로 필수로 설정되지만, 비어 있어도 에이전트 실행을 막지 않아도 되는 열은 제외할 수 있습니다. 에이전트는 필수로 남겨 둔 열이 비어 있거나 누락된 경우에만 해당 행을 건너뜁니다. 예를 들어 아직 입력되지 않은 gender 필드가 이에 해당합니다. 필요한 컨텍스트 없이 실행하면 토큰이 낭비되고 품질이 낮은 출력이 생성될 수 있습니다.
카탈로그 에이전트는 열 간의 종속성도 고려합니다. D 열이 B 열과 C 열을 기반으로 생성되는 경우, 해당 행의 B 열과 C 열에 값이 채워지기 전까지 에이전트는 그 행의 D 열에서 실행되지 않습니다.
카탈로그에서 에이전트를 사용하는 필드는 새로 고치고 편집할 수 있습니다. 열에서 에이전트를 제거하려면 AI 에이전트 적용의 선택을 해제하세요. 그러면 해당 열은 에이전트가 적용되지 않은 일반 열로 돌아가며, 필드에는 에이전트가 카탈로그에서 마지막으로 실행되었을 때 적용한 최신 값이 유지됩니다.
카탈로그에서는 순환 참조가 지원되지 않으므로 다음과 같은 시나리오는 발생할 수 없습니다.
- 에이전트 열 1이 에이전트 열 2를 입력으로 사용
- 에이전트 열 2가 에이전트 열 1을 입력으로 사용
카탈로그 필드에 에이전트 추가
카탈로그 필드에 에이전트를 추가하려면 다음 단계를 따르세요.
- 카탈로그에서 새 필드를 추가합니다.
- AI 에이전트 적용을 선택합니다.
- 이 필드에 에이전트를 할당합니다.
- 입력으로 전달할 열을 선택합니다. 아무 열도 선택하지 않으면 에이전트가 카탈로그의 모든 열에 액세스할 수 있습니다.
- (선택 사항) 선택한 입력 열 중 하나 이상이 비어 있는 행을 건너뛰려면 필수 열에 값이 있는 경우에만 실행을 활성화합니다. 이 옵션을 켜면 에이전트가 실행되기 위해 반드시 값이 채워져 있어야 하는 입력 열을 선택합니다. 선택한 모든 열은 기본적으로 필수로 설정되지만, 비어 있어도 실행을 막지 않아도 되는 열은 제외할 수 있습니다.
- 카탈로그 행이 업데이트될 때 에이전트가 필드를 다시 계산할지 결정합니다. 이 옵션을 선택하지 않으면 에이전트는 행당 한 번만 실행됩니다.
- 필드 추가를 선택하여 에이전트를 배포하고 비용 추정치를 검토합니다. 비용 추정 Modal에는 에이전트가 이 카탈로그에서 실행될 횟수가 표시되며, 이는 대략 전체 행 수와 같습니다. 계속하려면 확인을 선택합니다.
카탈로그 에이전트 모범 사례
카탈로그 필드에 에이전트를 적용하기 전에 에이전트에 필요한 열을 미리 계획하세요. 필드에 필수 입력 컨트롤을 활성화한 후 에이전트가 읽어야 할 데이터가 포함된 열을 선택하고, 비어 있어도 실행을 막지 않아도 되는 열은 선택 해제하세요. 에이전트는 필수로 표시된 열이 비어 있는 경우에만 해당 행을 건너뜁니다.
일부 행에서 열이 비어 있을 것으로 예상되지만 에이전트는 계속 실행되기를 원한다면, 해당 열을 필수로 표시한 채로 두지 말고 필수 집합에서 제외하세요. 불완전한 행을 건너뛰면 불필요한 토큰 사용을 방지하고 출력 품질을 높게 유지할 수 있습니다.
| 시나리오 | 결과 |
|---|---|
| 입력 안내 값만 미리 채워진 행 | ID와 펀드 이름만 있는 카탈로그 행을 추가하고 나머지 열은 나중에 채우는 경우, 필수 입력 열에 값이 채워질 때까지 에이전트는 해당 행을 건너뜁니다. |
| 행이 이미 있는 상태에서 에이전트 적용 | 이미 행이 있는 카탈로그의 필드에 에이전트를 적용하면, 에이전트는 모든 행을 평가하지만 필수 입력 열에 값이 채워진 행에서만 실행됩니다. |
| 부분적으로 완성된 카탈로그 | 예를 들어 100개의 행이 있는 카탈로그에서 2026년 항목에는 leader가 채워져 있지만, 다른 행에는 ID와 펀드 이름만 있고 나머지 필드는 비어 있는 경우입니다. leader가 필수로 유지되면 에이전트는 leader 값이 있는 행에서는 실행되고, 값이 없는 행은 건너뜁니다. |
| 종속 열 | 열 3이 열 1과 열 2에 종속된 경우, 해당 행의 열 1과 열 2에 값이 채워질 때까지 에이전트는 열 3에 값을 쓰지 않습니다. |
사용 사례
| 사용 사례 | 설명 |
|---|---|
| 제품 설명 생성 | 새 카탈로그 항목에 대한 짧은 마케팅 문구를 자동으로 만듭니다. 예를 들어 이름, 카테고리, 기능 같은 구조화된 제품 데이터를 바탕으로 눈길을 끄는 설명을 생성할 수 있습니다. |
| 제품 속성 보강 | 제품 이름과 세부 정보를 바탕으로 색상 계열, 스타일, 시즌 같은 누락된 값을 채웁니다. 예를 들어 제품 이름이 “Laguna Polarized Sunglasses”라면 에이전트가 스타일을 “sport”로, 색상 계열을 “blue”로 지정할 수 있습니다. |
| 파생 필드 계산 | 기존 필드를 사용해 새 데이터를 생성합니다. 예를 들어 속성을 기반으로 한 “적합도 점수”나 판매 및 리뷰 수를 기반으로 한 “인기 태그”를 만들 수 있습니다. |
| 항목 분류 또는 태그 지정 | 추천 로직에 사용할 태그를 지정하여 개인화 모델이 제품을 더 효과적으로 세분화할 수 있도록 합니다. 예를 들어 제품에 “outdoor”, “festival-ready”, “premium” 같은 태그를 지정할 수 있습니다. |
| 콘텐츠 현지화 | 글로벌 Campaigns를 위해 카탈로그 텍스트를 다른 언어로 번역하거나, 지역별 채널에 맞게 어조와 길이를 조정합니다. 예를 들어 “Classic Clubmaster Sunglasses”를 스페인어 “Gafas de sol Classic Clubmaster”로 번역하거나, SMS Campaigns에 맞게 설명을 줄일 수 있습니다. |
| 리뷰 또는 피드백 요약 | 감정이나 피드백을 새 필드에 요약합니다. 예를 들어 긍정, 중립, 부정 같은 감정 점수를 지정하거나 “대부분의 고객이 핏이 좋다고 언급하지만 배송이 느리다는 의견도 있습니다.” 같은 짧은 텍스트 요약을 만들 수 있습니다. |
응답 필드 정의
에이전트가 출력 형식으로 필드를 사용하는 경우, 카탈로그 필드에서 사용할 응답 필드로 에이전트의 해당 필드를 선택할 수 있습니다.
예를 들어 출력 형식을 구조화하기 위해 다음 필드를 사용하여 카탈로그에 제품 설명을 추가하는 에이전트가 있다고 가정해 보겠습니다.
| 필드 이름 | 값 |
|---|---|
| description | 텍스트 |
| confidence_score_out_of_ten | 숫자 |
카탈로그에 product_description이라는 필드를 추가하고 description을 응답 필드로 선택하면, 에이전트가 생성한 설명으로 해당 열을 채울 수 있습니다.
항목 편집을 선택하고 에이전트가 생성한 설명을 직접 수정하여 에이전트가 생성한 셀을 수동으로 덮어쓸 수도 있습니다. 에이전트가 생성한 설명으로 되돌리려면 셀에서 새로 고침 아이콘을 선택하세요.
오류 처리
- LLM 공급자가 사용량 제한 오류를 반환하면, Braze는 호출이 성공하거나 완료할 수 없다고 판단될 때까지 지수 백오프를 사용하여 요청을 계속 재시도합니다.
- 그 밖의 실패(예: 시간 초과 또는 유효하지 않은 API 키)의 경우 카탈로그 필드 값이 업데이트되지 않습니다. 카탈로그 에이전트는 에이전트 콘솔에서 대체 값을 구성하는 기능을 지원하지 않습니다.
- 실패한 실행에 대한 자세한 내용은 에이전트 로그에서 확인할 수 있습니다.
- 카탈로그 에이전트는 행당 최대 25KB의 입력 값만 처리할 수 있습니다.
에이전트 모니터링
모니터링은 에이전트가 캔버스에서 실행되든 카탈로그에서 실행되든 동일하게 작동합니다.
에이전트의 사용량 섹션에서는 카탈로그와 캔버스에서 에이전트가 현재 사용되고 있는 위치를 확인하고 해당 위치로 이동할 수 있습니다.
에이전트의 로그 섹션에서는 캔버스와 카탈로그에서 발생하는 실제 에이전트 호출을 모니터링할 수 있습니다. 날짜 범위, 성과(성공 또는 실패), 호출 위치 등의 정보로 필터링할 수 있습니다. 또한 CSV 내보내기를 선택하면 현재 페이지에 표시된 로그만 내보낼 수 있습니다.
특정 에이전트 호출에 대해 보기를 선택하면 입력, 출력, 사용자 ID를 확인할 수 있습니다.
캔버스 단계 에이전트의 경우, 로그에는 호출 중 오류가 발생했을 때 사용된 대체 출력을 보여주는 대체 출력 섹션이 포함됩니다.
Currents 사용
다음 Currents 이벤트를 사용하여 Kafka 레코드 스키마에 액세스할 수도 있습니다.
- 에이전트 실행 이벤트
- 도구 호출 이벤트
자세한 내용은 메시지 인게이지먼트 이벤트 용어집을 참조하세요.