도구를 만드는 방법(베타)

베타 기능입니다. 처음부터 완전히 사용자 정의 도구를 만드는 것은 오픈 베타 버전이며 모든 고객 에이전트 계정에서 사용할 수 있습니다. 가입이 필요하지 않습니다. Customer Agent에서 도구 페이지를 찾을 수 있습니다. 기능이 계속 확장 중이며 변경될 수 있습니다.

학습 내용

완전히 사용자 정의된 도구를 사용하여 고객 에이전트를 모든 HTTP 엔드포인트에 연결하고, 고객 에이전트가 실제로 사용할 도구 설명을 작성하고, 기술에 부착하기 전에 도구를 테스트하는 방법입니다.

시작하기 전에 알아야 할 것

필요한 사항은 다음과 같습니다.

• 고객 에이전트가 활성화되었습니다.
• 고객 에이전트가 호출하도록 하는 HTTP 엔드포인트입니다. 오늘 액세스하기 위해 비밀 자격 증명(API 키, 무기명 토큰 등)이 필요하지 않은 엔드포인트입니다 (인증된 엔드포인트가 곧 제공될 예정입니다. 아래 경고 참조).
• 고객 에이전트가 제공하는 기술이나 직접 만든 완전히 사용자 정의 기술 중 하나에 도구를 연결할 수 있는 기술입니다

아직 기술을 설정하지 않았다면 먼저 기술을 만드세요. 도구는 스스로 아무것도 하지 않습니다. 기술에 매달려야 합니다.

경고: API 키 및 기타 비밀번호를 위한 보안 저장소가 곧 제공될 예정입니다. 배송될 때까지 API 키, 무기명 토큰 또는 기타 민감한 자격 증명을 완전한 사용자 정의 도구에 넣지 마세요. 도구 구성은 아직 이를 저장할 수 있는 안전한 장소가 아닙니다. 지금은 비밀 인증 없이 호출하기 안전한 엔드포인트(예: IP 허용 목록의 내부 엔드포인트 또는 민감하지 않은 식별자를 허용하는 엔드포인트)가 있는 도구만 사용합니다. 인증된 엔드포인트에 대한 지원이 진행 중입니다.

완전히 사용자 정의 도구란 무엇인가요?

완전히 사용자 정의된 도구는 고객 에이전트가 대화 중에 만들 수 있는 HTTP 요청입니다. 완전히 사용자 정의 도구를 만드는 방법은 오픈 베타 버전이며 모든 고객 에이전트 계정에서 사용할 수 있습니다. Klaviyo 고객 에이전트가 함께 제공하는 도구에서 필요한 것을 다루지 마세요. 예를 들어, Shopify가 아닌 자체 주문 관리 시스템에서 주문을 조회하거나, 사용자 정의 웨어하우스 시스템에서 재고를 확인하거나, Klaviyo가 기본적으로 연동하지 않는 헬프데스크에서 티켓을 생성하는 등의 작업을 수행할 수 있습니다.

기본 개념은 고객 에이전트 도구 이해 문서를 참조하세요.

완전히 사용자 정의 도구를 만들어야 하는 경우입니다.

다음과 같은 경우에는 완전히 사용자 정의된 도구에 도달하세요.

• Klaviyo가 아직 연동하지 않은 시스템의 실시간 데이터가필요합니다.
• 고객 에이전트가 외부 시스템에서작업을 수행하도록 합니다 (자체 시스템에서 구독 취소, 티켓 생성, 레코드 업데이트).
• 기존 도구가 적합하지 않습니다. 예를 들어, 주문에는 Shopify 대신 사용자 정의 OMS를 사용합니다.

정보가 자주 변경되지 않고 모든 고객에 대해 동일하다면 대신 콘텐츠로 추가하세요. 도구는 동적인 고객별 데이터 및 작업을 위한 것입니다.

설정하세요.

1. 도구 페이지를 엽니다.

고객 에이전트 > 도구로 이동한 다음 도구 만들기 를 클릭합니다.

2. 도구의 이름을 지정하고 설명합니다.

• 이름 — '재고 확보' 또는 '반품 티켓 생성'과 같은 짧은 식별자입니다.
• 설명 — 도구의 기능 및 사용 시기를 설명하는 자연어입니다. 고객 에이전트는 이 설명을 읽고 주어진 요청에 도구를 사용할지 여부를 결정합니다. 구체적이어야 합니다.

좋은 설명 예시입니다.

웨어하우스 시스템에서 주어진 제품 SKU에 대한 실시간 재고 개수를 가져옵니다. 쇼핑객이 특정 제품의 재고 여부를 문의할 때 사용합니다.

모호한 설명 예시(피하기)입니다.

제품 정보를 가져옵니다.

3. HTTP 요청을 구성합니다.

• 방법 — 가져오기, 게시, 가져오기, 삭제 또는 패치합니다.
• URL — 전체 엔드포인트 URL입니다. 동적 값에 대한 자리 표시자를 포함할 수 있습니다(5단계 참조).
• 헤더 — 엔드포인트에서 필요로 하는 모든 헤더( Content-Type 및 인증 헤더 포함).

4. 요청 본문(POST, PUT, PATCH의 경우)을 구성합니다.

JSON 본문을 입력합니다. 고객 에이전트가 런타임에 입력해야 하는 값에 자리 표시자를 사용하세요.

예시 본문은 다음과 같습니다.

{
  "customer_id": "{{profile_id}}"
  "sku": "{{product_sku}}"
}

5. 동적 값에 자리 표시자를 사용합니다.

고객 에이전트는 런타임에 자리 표시자를 사용하여 값을 입력할 수 있습니다. 일반적인 자리 표시자는 다음과 같습니다.

• {{profile_id}} — 대화 중인 고객의 Klaviyo 프로필 ID
• {{conversation_id}} — 현재 대화 ID
• 입력 스키마에서 정의한 모든 매개변수(예: {{product_sku}}, {{order_id}})

자리 표시자는 URL, 헤더 및 본문으로 작동합니다.

6. 인증

인증된 엔드포인트에 대한 지원이 곧 제공될 예정입니다. 그때까지는 API 키, 무기명 토큰 또는 기타 비밀번호를 완전히 사용자 정의 도구에 추가하지 마세요. IP 허용 목록으로 보호되는 내부 엔드포인트 또는 민감하지 않은 식별자를 허용하는 공개 엔드포인트 등 비밀 자격 증명 없이 호출하기 안전한 엔드포인트만 사용합니다.

보안 비밀번호 저장소가 사용 중이며 인증된 엔드포인트를 잠금 해제할 것입니다.

7. 도구를 테스트합니다.

테스트 도구 를 클릭합니다. 모든 입력 매개 변수에 대한 샘플 값을 제공하세요. 다음을 확인하세요.

• 응답이 성공적으로 돌아왔습니다.
• 고객 에이전트가 기대하는 응답 형식입니다.
• 모든 오류 사례가 처리됩니다.

8. 기술을 저장하고 연결합니다.

저장을 클릭합니다. Customer Agent가 실제로 도구를 사용하도록 하려면 사용하려는 기술을 열고 거기에 도구를 추가하세요.

좋은 도구 설명을 작성합니다.

설명은 가장 중요한 필드입니다. Customer Agent는 이름이 아닌 설명을 완전히 기준으로 어떤 도구를 사용할지 선택합니다. 좋은 설명은 다음과 같습니다.

• 도구 가 하는 일 을 한 문장으로 표현하세요
• 한 문장으로 언제 사용할지 알려주세요.
• 반환된 데이터 또는 취한 조치에 대해 구체적입니다.

잘못된 설명은 모호하거나('고객 정보 가져오기'), 너무 광범위하거나('주문과 관련된 모든 것을 처리'), 고객 에이전트에게 도구의 기능보다 행동하는 방법을 알려주는 것입니다.

보안 고려 사항

• 아직 비밀 자격 증명이 필요한 엔드포인트에 완전히 사용자 정의 도구를 사용하지 마세요. 인증된 엔드포인트에 대한 지원이 곧 제공될 예정입니다. 배송될 때까지 비밀 인증 없이 호출하기 안전한 엔드포인트만 사용하세요.
• 가능한 경우 IP 허용 목록을 사용하세요. 엔드포인트가 내부인 경우 비밀에 의존하지 않고 Klaviyo IP 범위에 대한 액세스를 제한하세요.
• 어떤 데이터를 보내는지 잘 알고 있어야 합니다. 고객 에이전트는 기술 지침에 따라 고객 데이터를 도구에 전달합니다. 엔드포인트가 수신하는 필드를 검토하세요.
• 요금 제한입니다. 엔드포인트에 요금 제한이 있는 경우 예상 대화량을 처리할 수 있을 만큼 충분히 높은지 확인하세요.

문제 해결

증상: 고객 에이전트는 도구를 사용하지 않습니다.
설명이 너무 모호하거나 도구를 사용할 기술에 도구가 연결되어 있지 않은 경우 등이 원인일 수 있습니다.
수정: 설명을 다시 작성하여 사용 시기를 구체적으로 설명하세요. 기술의 도구 목록에 도구가 표시되는지 확인합니다.

증상: 테스트 중 도구가 오류를 반환합니다.
원인: 엔드포인트가 허용하지 않는 잘못된 URL, 잘못된 형식의 본문 또는 페이로드 등입니다.
수정: 테스트 도구 기능을 사용하여 원시 요청 및 응답을 확인합니다. 엔드포인트의 예상 입력과 비교하여 URL 및 본문 형식을 확인하세요.

증상: 고객 에이전트가 도구를 사용하지만 잘못된 매개 변수를 전달합니다.
가능한 원인: 자리 표시자 이름이 스키마와 일치하지 않거나 기술 지침이 통과 내용에 대해 명확하지 않습니다.
수정: 자리 표시자 이름이 정확히 일치하는지 확인하세요. 기술 지침을 업데이트하여 도구를 사용해야 하는 시점과 제공해야 하는 매개 변수에 대해 명시하세요.

증상: 도구가 느려 응답이 지연됩니다.
가능한 원인: 엔드포인트 대기 시간입니다.
수정: 엔드포인트를 최적화하세요. 결과를 내 측에 캐시할 수 있는지 확인하세요.

자주 묻는 질문

하나의 도구를 여러 기술에 사용할 수 있나요?
예, 그렇습니다. 일단 생성되면 도구를 여러 기술에 첨부할 수 있습니다.

어떤 인증 방법이 지원되나요?
인증된 엔드포인트에 대한 지원이 곧 제공될 예정입니다. 지금은 비밀 자격 증명이 필요하지 않은 엔드포인트(IP 허용 목록이 있는 내부 엔드포인트 또는 민감하지 않은 식별자가 있는 공개 엔드포인트)를 사용하세요.

엔드포인트가 다운되었거나 오류가 반환되면 어떻게 되나요?
완전히 사용자 정의된 도구에 대한 오류 처리가 아직 구축되지 않았습니다. 엔드포인트에 실패하면 고객 에이전트가 저하되거나 혼란스러운 응답을 생성할 수 있습니다. 배송 관련 오류를 처리하기 전까지는 자신 있는 엔드포인트만 사용하고 도구의 동작을 면밀히 모니터링하세요.

도구를 만든 후 편집할 수 있나요?
예, 그렇습니다. 언제든지 이름, 설명, 구성 및 첨부된 기술을 편집할 수 있습니다.

도구의 버전을 바꿀 수 있나요?
버전 관리가 아직 지원되지 않습니다. 도구에 대한 편집 내용은 해당 도구를 사용하는 모든 기술에 즉시 적용됩니다.

Additional resources