고객 에이전트 API(베타)
학습 내용
고객 에이전트 API의 정의, 각 엔드포인트 그룹의 기능, 고객 에이전트 API 호출을 시작하는 방법입니다. API를 사용하면 고객 에이전트를 구성하고, 프로덕션에서 진행 중인 작업을 읽고, Klaviyo의 나머지 공개 API와 함께 HTTP를 통해 직접 프로그래밍 방식으로 실행할 수 있습니다.
참고: 고객 에이전트 API는 베타 버전이에요. 일반 공개 전에 엔드포인트와 스키마가 변경될 수 있어요. 베타 API는 프로덕션 사용을 목적으로 하지 않아요 — 자세한 내용은 Klaviyo의 버전 관리 및 지원 중단 정책을 확인해 주세요.
API를 통해 수행할 수 있는 작업
고객 에이전트 API는 4가지 작업을 다룹니다:
- 에이전트를 구성합니다. 에이전트 자체와 기술, 도구, 지식 출처 및 암호를 읽거나 업데이트합니다.
- 프로덕션 대화 읽기 — 고객 에이전트 대화를 나열하고 검사합니다.
- 성과 — 끌어오기 용량, 해결률 및 기술별 지표에 대해 보고하세요.
- 에이전트를 한 번 실행 — 대화 순서를 보내고 에이전트의 응답을 다시 받습니다. 헤드리스 프리미티브로, 에이전트를 자신의 표면에 임베드하는 데 유용합니다.
이 네 가지 작업이 모두 하나의 API 뒤에 있기 때문에 연속 학습 루프로 연결할 수 있어요. 일어난 일을 가져오고, 무엇이 효과가 있었고 무엇이 없었는지 진단한 다음, 구성 변경 사항을 다시 반영하면 돼요. 안전하게 구성된 API 연동 또는 MCP 연결을 사용하면 Claude나 ChatGPT 같은 AI 어시스턴트가 대화를 읽고, 실패에서 패턴을 찾고, 스킬, 도구, 지식, 가이드에 대한 변경 사항을 제안하는 데 도움을 줄 수 있어요.
인증 및 액세스
agents 범위를 포함한 Klaviyo 비공개 API 키를 사용해 이러한 엔드포인트를 호출하세요. 고객 에이전트는 계정에서 이미 활성화되어 있어야 해요.
키를 만들 때 agents 범위의 액세스 수준을 선택해요:
액세스 수준 | 권한 부여 |
읽기 액세스 | agents:read — 구성 및 대화를 위한 GET 엔드포인트와 보고서를 위한 POST 엔드포인트. 비밀 값은 반환되지 않습니다. |
전체 액세스 | agents:read 및 agents:write ― 위의 모든 항목에 더해 지원되는 구성 변경, 대화 생성 및 업데이트, 한 턴 동안 에이전트를 실행하는 기능까지 포함돼요. |
연동에서 에이전트(예: 보고 대시보드)만 관찰하면 되는 경우 읽기 전용을 선택합니다. 에이전트를 구성하거나 대화 순서를 실행해야 하는 경우 읽기/쓰기를 선택합니다.
- 설정 > API 키로 이동한 다음 비공개 API 키 만들기를 클릭해 주세요.
- 비공개 API 키 이름을 입력하고 사용자 지정 키를 선택해 주세요.
- 위 표를 사용해 Agents 행에서 연동에 대해 Read Access 또는 Full Access를 선택해 주세요.
- 생성을 클릭한 다음 복사 아이콘을 클릭하고, 키를 안전하게 보관해 주세요. 확인 페이지를 나가면 키를 다시 볼 수 없어요.
자세한 내용은 비공개 API 키를 생성하거나 복제하는 방법을 확인해 보세요.
서버에서 https://a.klaviyo.com (으)로 API 요청을 보내고 이 인증 헤더를 포함해 주세요. 비공개 키는 브라우저 코드와 쇼핑객에게 노출되는 앱에 포함하지 마세요:
Authorization: Klaviyo-API-Key your-private-api-key
모든 요청에는 베타 수정 헤더도 포함되어야 합니다.
revision: 2026-10-15.pre
베타 수정 헤더가 없으면 요청이 거부됩니다.
요금 제한
요율 제한은 엔드포인트 그룹에 따라 달라요:
- 에이전트, 스킬, 도구, 지식, 비밀 및 응답: 초당 10개 요청의 버스트 한도와 분당 150개 요청의 지속 한도가 적용됩니다.
- 대화, 대화 메시지 및 보고서: 버스트 제한은 초당 3회 요청이며, 지속 제한은 분당 60회 요청이에요.
요청 형식
파일 업로드에는 별도의 형식을 사용하면서, Klaviyo의 JSON:API 요청 규칙을 사용해 주세요:
- 콘텐츠 유형: JSON 요청의 경우
application/vnd.api+json입니다.POST /api/agent-knowledge-files에multipart/form-data을(를) 사용하세요. - 페이지 매김된 컬렉션은
page[cursor]및page[size](기본값 50, 최대 100, 앞으로만)을 사용해요. 남은 페이지를 가져오려면 links.next가 비어 있을 때까지 따라가세요. - 필터링은 각 엔드포인트 참조에 나열된 지원 필드와 연산자를 사용해요. 정렬 순서는 엔드포인트별로 달라요. 대화는 최신순, 메시지는 오래된 순, 스킬과 도구는 ID 기준으로 정렬돼요.
엔드포인트 그룹
에이전트
회사당 고객 에이전트는 최대 1개만 있을 수 있어요. GET /api/customer-agents(고객 에이전트)를 호출해 ID를 찾은 다음, 해당 ID를 GET 또는 PATCH URL에 사용해 주세요. 계정에서 고객 에이전트가 활성화되어 있지 않으면 목록이 비어 있어요.
방법 | 경로 | 어떤 기능을 하나요? |
| 에이전트와 ID를 찾아보세요 | |
| 에이전트의 이름, 말투, 에스컬레이션 규칙, 커뮤니케이션 스타일을 가져오세요. | |
| 에이전트의 최상위 필드를 업데이트합니다. |
에이전트 스킬
사전 구축 스킬과 사용자 지정 스킬을 읽을 수 있어요. 사용자 지정 스킬만 업데이트하거나 삭제할 수 있어요. 사용자 지정 스킬의 status을(를) draft (으)로 설정하면 준비 상태로 두거나 일시 중지할 수 있고, live (으)로 설정하면 활성화할 수 있어요.
방법 | 경로 | 어떤 기능을 하나요? |
| 모든 기술을 나열합니다. | |
| 기술 만들기 | |
| 하나의 기술을 확보하세요. | |
| 기술을 업데이트하세요. | |
| 기술을 삭제합니다. |
에이전트 도구
커스텀 도구만 업데이트하거나 삭제할 수 있어요. 외부 HTTP 도구를 만든 후 스킬의 agent-tools 관계를 통해 커스텀 스킬에 바인딩해 주세요. 도구가 바인딩되기 전까지는 해당 스킬에서 사용할 수 없어요.
방법 | 경로 | 어떤 기능을 하나요? |
| 회사에 표시되는 목록 도구입니다. | |
| 외부 HTTP 도구를 만듭니다. | |
| 하나의 도구로 구매하세요. | |
| 도구를 업데이트하세요. | |
| 도구를 삭제합니다. |
에이전트 지식
source.source_type을(를) snippet, webpage, qa 또는 folder(으)로 설정해 텍스트 스니펫, 웹페이지, Q&A 쌍 또는 폴더를 생성하세요. file을(를) 추가하려면 별도의 파일 업로드 엔드포인트를 사용하세요.
방법 | 경로 | 어떤 기능을 하나요? |
| 최상위 지식 항목을 최신순으로 나열하고, folder_id로 필터링하여 폴더의 콘텐츠를 나열합니다. | |
| 스니펫, 웹페이지, Q&A 쌍 또는 폴더 만들기 | |
| 파일을 지식 출처(multipart)로 업로드합니다. | |
| 하나의 지식 출처를 확보하세요. | |
| 스니펫의 제목 또는 콘텐츠, 또는 Q&A 쌍의 질문 또는 답변을 업데이트하세요 | |
| 지식 출처를 삭제합니다. |
에이전트 비밀 정보
사용자 지정 도구에서 사용되는 암호화된 비밀번호입니다. 목록 엔드포인트는 안전한 메타데이터만 반환하며, 비밀번호 값 자체는 반환되지 않습니다.
방법 | 경로 | 어떤 기능을 하나요? |
| 목록 비밀(메타데이터만 해당)입니다. | |
| 비밀번호를 생성합니다. | |
| 비밀번호를 업데이트하세요. | |
| 비밀번호를 삭제합니다. |
대화
에이전트가 쇼핑객과 나눈 대화를 읽거나, API를 통해 실행할 대화를 생성해 보세요. 하나의 대화는 긴 기간에 걸쳐 여러 메시지로 이어질 수 있어요. 목록에는 라이브 대화와 미리보기 대화가 포함될 수 있어요. 라이브 대화로만 제한하려면 filter=equals(mode,"live")를 사용해 주세요.
방법 | 경로 | 어떤 기능을 하나요? |
| 목록 대화 | |
| 메시지에 대한 참조를 포함해 ID로 대화 1개를 가져오기 | |
|
| 페이지네이션을 사용해 메시지 콘텐츠를 오래된 순서부터 읽기 |
| 에이전트를 실행하기 전에 빈 대화를 생성하세요. |
보고서
요청한 회사 범위로 제한된 집계 지표예요. 아래의 두 보고서는 모두 POST 엔드포인트예요. 보고서 파라미터는 본문에 전달해 주세요. agents:read 권한이 필요하므로, 읽기 전용 키로 실행할 수 있어요.
방법 | 경로 | 어떤 기능을 하나요? |
| 대화 수준 지표: 거래량 및 해결률 | |
| 기술별 거래량 보고서 |
에이전트를 실행합니다.
방법 | 경로 | 어떤 기능을 하나요? |
| 고객 에이전트를 실행하여 한 번의 대화로 전환하세요. 쇼핑객 입력을 전달하고 에이전트의 응답을 다시 받으세요. |
고객 에이전트를 나만의 화면(앱, 고객센터, 파트너가 구축한 지원 패널)에 임베딩하기 위한 원시 버전입니다.
턴을 실행하기 전에 POST /api/customer-agent-conversations와(과) 열린 대화를 생성해 주세요. 응답 엔드포인트는 API를 통해 생성된 대화만 허용해요. 종료된 대화 또는 이미 팀으로 라우팅된 대화는 추가 응답을 받을 수 없어요.
여전히 Klaviyo UI가 필요한 사항입니다.
일부 설정 단계가 아직 API에 활성화되어 있지 않습니다.
- 채널 구성 (웹 채팅, 이메일, SMS, WhatsApp) — 채널 설정은 Klaviyo 플랫폼 설정에 있습니다.
- 각 채널에서 라이브 로 전환됩니다. 채널당 켜기/끄기 스위치는 UI에 그대로 유지됩니다.
- 헬프데스크 선택 — 고객 에이전트에서 채널 아래의 채널을 열고 Handoff 섹션을 구성해 주세요. 자세한 내용은 고객 에이전트 설정 관리를 참고해 주세요.
전형적인 워크플로우
한 번 구성한 다음 유지 관리합니다.
- Klaviyo에서
agents범위와 읽기/쓰기 액세스 권한이 있는 비공개 API 키를 생성해 주세요. - 현재 상태 가져오기 — GET /api/customer-agents를 사용해 고객 에이전트 ID를 찾은 다음, 에이전트와 스킬, 도구, 지식 목록을 가져오세요. 페이지네이션 링크를 따라 모든 페이지를 읽어 주세요.
- 변경하기 — 필요에 따라 커스텀 스킬, 도구, 지식, 시크릿을 생성하거나 업데이트하세요. 새 도구를 해당 도구를 사용하는 스킬에 바인딩하고, 활성화할 준비가 되면 커스텀 스킬의 status를 live로 설정하세요.
- 프로덕션 확인 — 최근 대화를 나열하고 값 보고서를 가져와서 에이전트의 성과를 확인합니다.
- 반복합니다.
에이전트를 처음부터 다시 교육하세요.
API는 에이전트가 프로덕션에서 한 일과 구성 방법 사이의 루프를 닫도록 설계되었습니다. 일반적인 루프는 다음과 같습니다.
- 최근 대화 가져오기 ― created_at 및 status로 필터링된 대화를 GET하고, 프로덕션 대화의 경우 필터에 equals(mode,"live")를 추가해 주세요. 각 대화의 고객 에이전트 메시지를 가져온 다음 links.next를 따라가며 모든 페이지를 읽어 주세요.
- 진단 — 각 대화에 대해 성공 또는 실패로 분류합니다. 패턴을 찾아보세요. 에스컬레이션이 주제를 중심으로 군집화되어 있나요? 특정 기술이 라우팅되지 않아야 할 때 라우팅되나요? 에이전트가 필요한 지식을 누락했나요?
- Pull 지표 — 볼륨 및 해결률에 대한 값 보고서와 기술별 분석에 대한 기술 값 보고서입니다. 패턴이 집계로 유지되는지 확인합니다.
- 변경 제안 — 실패 패턴을 기반으로 무엇을 변경할지 결정합니다. 기술 지침 편집, 지식 스니펫 추가, 새 사용자 지정 도구 만들기, 어조 규칙 강화, 에스컬레이션 트리거 추가 등이 있습니다.
- 변경 사항 적용 — 영향을 받는 기술을 패치하고, 새로운 지식 출처를 게시하는 등의 작업을 수행할 수 있습니다.
- 반복합니다. 다음 대화 창에 대해 반복합니다.
Claude, ChatGPT, Cursor 같은 AI 어시스턴트를 사용해 대화를 가져오고, 빈틈을 찾고, 구체적인 수정안을 제안한 뒤, 승인하시면 변경 사항을 적용할 수 있어요. Klaviyo MCP 서버 또는 자체 API 연동을 통해 연결하고, 비공개 API 키는 프롬프트가 아니라 보안 설정에 안전하게 보관해 주세요. MCP 서버가 이러한 작업 중 상당수를 지원하지만, 시크릿을 생성하거나 업데이트하고 지식 파일을 업로드하려면 직접 API 호출이 필요해요.
에이전트를 나만의 화면에 임베드합니다.
청구 또는 프로덕션 지표 없이 테스트하려면 mode: preview을(를) 사용하세요. mode: live은(는) 실제 쇼핑객 상호작용을 위한 것이며 청구 및 프로덕션 지표에 포함돼요. 위의 베타 사용 경고는 여전히 적용돼요.
- 에이전트 범위(읽기/쓰기)가 포함된 키를 만듭니다.
- 대화 만들기 — 서버에서 선택한
mode(으)로/api/customer-agent-conversations에 POST 요청을 보내세요. 반환된 대화 ID를 저장하세요. - UI에서 대화 열기 — 쇼핑객의 입력을 수집합니다.
- Run a turn — 서버에서 mode, messages, 그리고 data.relationships.conversation.data.id에 저장된 ID를 포함해 /api/customer-agent-responses로 POST해 주세요. relationship type으로 customer-agent-conversation을 사용해 주세요. messages에 대화 기록을 포함하고, role: user인 쇼핑객의 최신 메시지로 끝내 주세요.
- 응답 렌더링 — 반환된 이벤트를 순서대로 처리하고, 에이전트의 메시지와 지원되는 구조화된 데이터를 인터페이스에 표시해 주세요. 연동에서 핸드오프 이벤트를 처리해 주세요. API는 스트리밍 없이 이벤트를 함께 반환하며, 채널을 통해 전달하지 않아요.
- 대화가 열려 있는 동안 동일한 대화 ID와 모드를 사용해 각 턴마다 반복해 주세요. 하드 또는 무응답 핸드오프 이후에는 에이전트 응답을 더 이상 요청하지 말고, 쇼퍼를 지원팀으로 라우팅해 주세요.
자주 묻는 질문
MCP 서버가 있나요?
예, 그렇습니다. 원격 호스팅되는 Klaviyo MCP 서버에는 스킬, 도구, 지식, 비밀 메타데이터, 대화, 보고서, 에이전트 실행을 위한 고객 에이전트 도구가 포함되어 있어요. 대화 생성, 시크릿 생성 또는 업데이트, 지식 파일 업로드에는 직접 API 호출이 필요해요. Klaviyo MCP 서버를 확인해 보세요.
이 정도면 충분히 안정적인가요?
베타는 스키마가 변경될 수 있음을 의미합니다. 엔드포인트는 완전히 호출할 수 있지만 아직 장기적인 안정성을 약속하지는 않습니다. 베타 버전에 비해 프로덕션 크리티컬 연동을 배송하지 마세요.
전체 스키마를 어디에서 찾을 수 있나요?
전체 참조 자료는 https://developers.klaviyo.com/en/reference/의 Klaviyo 개발자 포털에 있어요. 고객 에이전트 엔드포인트는 2026-10-15.pre 개정판의 베타 API 아래에 표시돼요.
관련 문서
Learn more about Klaviyo APIs, authentication, and beta features.