도구를 만드는 방법

학습 내용

커스텀 도구를 사용해 고객 에이전트를 HTTP 엔드포인트에 연결하는 방법, 사용해야 하는 경우, 테스트 방법, 그리고 고객 에이전트가 이를 직접 사용할 수 있는지 또는 스킬을 통해서만 사용할 수 있는지 구성하는 방법

시작하기 전에 알아야 할 것

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

• 고객 에이전트가 활성화되었습니다.
• 공개 호스트명을 통해 연결할 수 있는 HTTP 엔드포인트예요. 사설 네트워크 주소, localhost, 그리고 호스트명 대신 IP 주소를 사용하는 URL은 지원되지 않아요. 엔드포인트에 API 키 또는 토큰이 필요하면, 이를 시크릿으로 저장해 두세요(1단계와 6단계를 참고하세요).
• 필요한 정책 확인을 포함해, 고객 에이전트가 이 도구를 언제 사용해야 하는지에 대한 계획이에요.

대화에서 어떻게 사용할지 결정하기 전에 도구를 만들고 테스트할 수 있어요. 커넥터에서 권한을 설정하세요: 직접 사용을 위해 항상 허용, 포함된 스킬을 통해 사용하려면 스킬에서만, 또는 사용을 방지하려면 차단됨으로 설정하면 돼요. 워크플로우별 지침이 필요하면 스킬 만드는 방법을 참고하세요.

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

완전 맞춤형 도구는 대화 중에 고객 에이전트가 실행할 수 있는 HTTP 요청이에요. 고객 에이전트에 기본으로 포함된 도구로는 필요한 작업을 처리할 수 없을 때 사용하세요. 예를 들어 Shopify 대신 자체 주문 관리 시스템에서 주문을 조회하거나, 맞춤형 창고 시스템에서 재고를 확인하거나, Klaviyo에서 기본으로 통합을 제공하지 않는 헬프데스크에서 티켓을 생성할 때 사용할 수 있어요.

기본 개념은 도구 이해를 참조하세요.

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

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

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

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

설정하세요.

1. Custom tools 페이지를 여세요.

1. 고객 에이전트 > 커넥터로 이동한 다음 사용자 지정 카드를 여세요.
2. 엔드포인트에 자격 증명이 필요하면 비밀로 이동한 다음 비밀 추가를 클릭해 주세요. 이름과 비밀 값을 입력한 다음 비밀 추가를 클릭해 주세요. 비밀이 이미 저장되어 있거나 엔드포인트에 비밀이 필요하지 않으면 이 단계를 건너뛰세요.
3. 도구 만들기를 클릭합니다.

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

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

좋은 설명 예시입니다.

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

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

제품 정보를 가져옵니다.

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

• HTTP 메서드 — GET, POST, PUT, DELETE 또는 PATCH.
• URL 템플릿 — 전체 엔드포인트 URL. 동적 값에 대한 자리표시자를 포함할 수 있어요(5단계 참고).
• 헤더 — 엔드포인트에서 필요로 하는 모든 헤더( Content-Type 및 인증 헤더 포함).
• 쿼리 매개 변수 — 엔드포인트에서 쿼리 문자열의 값을 예상하는 경우, 여기에서 해당 이름과 값을 입력해 주세요. 값에는 플레이스홀더를 사용할 수 있어요(5단계 참고).

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

본문 템플릿에서 JSON 객체를 제공해 주세요. 런타임에 고객 에이전트가 채워야 하는 값에는 자리표시자를 사용해 주세요.

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

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

5. 동적 값에 대한 변수를 정의하세요.

각 자리표시자는 변수 아래에 일치하는 변수가 있어야 해요. 위 예시 본문의 경우:

1. 변수 추가를 클릭하고 변수 이름에 profile_id을(를) 입력해 주세요. 소스를 Klaviyo 프로필로 설정하고, Klaviyo 속성을 Klaviyo ID로 설정해 주세요. 이렇게 하면 인증된 쇼퍼의 Klaviyo 프로필 ID가 제공돼요.
2. product_sku라는 다른 변수를 추가해 주세요. Source를 Dynamic Variable로 설정하고, Type으로 String을 선택한 다음, Description에 고객 에이전트가 제공해야 하는 SKU를 설명해 주세요. 엔드포인트에 필요하다면 Required를 선택해 주세요.

order_id 등 엔드포인트에 필요한 다른 값에도 동일하게 반복해 주세요. 변수 이름은 플레이스홀더와 정확히 일치해야 해요. conversation_id 이라는 변수는 현재 대화 ID로 자동 채워지지 않아요.

URL, 헤더, 쿼리 매개 변수 또는 본문에서 {{profile_id}} 및 {{product_sku}}과 같은 변수를 자리 표시자로 사용하세요. Klaviyo 프로필 변수를 사용하는 도구에는 인증된 쇼퍼가 필요해요. 필수 프로필 값이 누락되면 요청이 실행되지 않아요.

6. 인증

엔드포인트에 API 키, bearer 토큰 또는 기타 자격 증명이 필요하면 시크릿으로 저장하세요. 시크릿은 암호화되며, 값은 고객 에이전트에 절대 표시되지 않고 저장한 후에는 다시 볼 수 없어요.

1. 도구에서 Variables 아래에 있는 Add variables를 클릭해 주세요. 변수에 이름(예: api_key)을 지정하고, Source를 Secret으로 설정한 다음 저장한 시크릿을 선택해 주세요.
2. 엔드포인트에서 자격 증명을 기대하는 위치(헤더, URL, 쿼리 매개 변수 또는 본문) 어디에서든 변수를 참조하세요. 예를 들어, 이름이 Authorization 인 헤더를 추가하고 값으로 Bearer {{api_key}}을(를) 설정하세요.

키를 교체하려면 비밀 행 메뉴를 열고 업데이트를 클릭한 다음, 대체 값을 입력하고 업데이트를 클릭하세요. 해당 시크릿을 사용하는 모든 도구에 새 값이 적용돼요. 사용 중인 도구 열에는 각 시크릿을 참조하는 도구가 표시되므로, 삭제하기 전에 확인해 주세요.

7. 도구 저장 및 테스트하기

저장하기 전에 설정에서 타임아웃(초)과 최대 재시도 횟수를 확인해 주세요. 일시적 오류에 대비해 전체 시간 제한을 1～10초로, 재시도 횟수를 0～3회로 설정할 수 있어요. 도구가 데이터를 변경하는 경우, 엔드포인트에서 반복 요청을 안전하게 처리할 수 있는지 확인해 주세요.

저장을 클릭하여 도구를 생성해 주세요. 저장된 도구는 테스트 섹션과 함께 열려요.

테스트는 엔드포인트로 실제 요청을 전송하며 데이터가 변경될 수 있어요. 테스트 프로필과 테스트 레코드를 사용해 주세요. 저장하고 테스트 실행은 라이브 스킬에서 이미 사용 중인 도구를 포함해, 도구에 대한 모든 수정 사항도 저장해요.

테스트에서 동적 변수의 샘플 값을 입력해 주세요. 도구에서 Klaviyo 프로필 변수를 사용하는 경우 프로필 아래에서 테스트 프로필을 선택해 주세요. 테스트를 저장하고 실행을 클릭해 주세요.

응답을 검토하고 다음 사항을 확인해 주세요:

• 응답이 성공적으로 돌아왔습니다.
• 응답에는 워크플로우에 필요한 데이터가 포함되어 있어요.
• 예상되는 오류 사례에서는 유용한 상태 코드와 메시지가 반환돼요

8. 권한과 맞춤 스킬을 구성해 주세요

1. 고객 에이전트 > 커넥터 > 사용자 지정에서 도구 권한을 검토해 주세요. 직접 사용하려면 항상 허용을, 스킬로만 제한하려면 스킬에서만을, 사용을 방지하려면 차단됨을 선택해 주세요. 권한 변경 사항은 즉시 저장돼요.
2. 특정 지침이 필요한 워크플로우의 경우, 맞춤 스킬을 열거나 새로 만드세요. 응답 방법에서 도구를 사용해야 하는 위치에 /을(를) 입력한 다음, 해당 항목을 선택하세요. 언제 호출해야 하는지, 어떤 값을 제공해야 하는지, 어떤 정책 검사를 수행해야 하는지, 그리고 결과나 오류를 어떻게 처리할지 설명해 주세요. ‘스킬에서만’으로 설정된 도구는 스킬에 포함되어 있어야 합니다.
3. 커스텀 스킬의 경우, 초안을 테스트한 다음 준비되면 게시 또는 업데이트를 클릭해 주세요. 또한 도구가 항상 허용으로 설정되어 있다면 Playground에서 직접 도구 사용도 테스트해 보세요.

도구 권한에 대해 자세히 알아보세요.

캠페인 컴포저를 사용해 맞춤 동작을 구성해 주세요.

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

명확한 설명은 고객 에이전트가 도구를 언제 사용할지 결정하는 데 도움이 돼요. 맞춤 스킬에 포함된 경우, 스킬의 안내가 추가 워크플로우 가이드를 제공해요. 좋음 설명:

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

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

보안 고려 사항

• 스토어 자격 증명을 시크릿으로 저장하세요. API 키나 토큰을 헤더, URL 또는 본문에 직접 붙여넣지 마세요. 시크릿으로 추가한 다음 시크릿 변수로 참조하세요(6단계 참고).
• 가능하면 IP 허용 목록을 사용해 주세요. 엔드포인트는 여전히 공개 호스트 이름을 통해 접근 가능해야 하며, 프라이빗 네트워크 주소와 localhost는 차단돼요. 인증과 함께 추가적인 보호 계층으로 허용 목록을 사용해 주세요.
• 전송하는 데이터가 무엇인지 유의해 주세요. 요청 구성과 변수 소스에 따라 엔드포인트로 어떤 값이 전송되는지가 결정돼요. 스킬 지침은 동적 변수에 대해 고객 에이전트가 제공하는 값을 안내해요. 엔드포인트에서 수신하는 필드를 검토해 주세요.
• 요금 제한입니다. 엔드포인트에 요금 제한이 있는 경우 예상 대화량을 처리할 수 있을 만큼 충분히 높은지 확인하세요.

문제 해결

증상: 고객 에이전트가 도구를 전혀 사용하지 않아요.
Connectors에서 권한을 확인해 주세요. 차단된 도구는 실행할 수 없어요. ‘스킬에서만’으로 설정되어 있다면, 적절한 게시된 스킬에 포함되어 있는지 확인해 주세요. 도구 설명을 구체적으로 작성하고, 필수 입력값과 인증을 확인한 다음 다시 테스트해 주세요.

증상: 테스트 중에 도구에서 오류가 반환돼요.
가능성이 높은 원인: 잘못된 URL, 형식이 올바르지 않은 본문, 필수 프로필 데이터 누락 또는 엔드포인트에서 허용하지 않는 페이로드예요.
해결 방법: 테스트에서 요청 미리 보기와 응답을 확인해 주세요. URL, 헤더, 본문이 엔드포인트에서 예상하는 입력과 일치하는지 확인해 주세요. 도구에서 Klaviyo 프로필 변수를 사용하는 경우, 필요한 값이 있는 테스트 프로필을 선택해 주세요.

증상: 고객 에이전트가 도구를 사용하지만 잘못된 매개변수를 전달해요.
가능성이 높은 원인: 변수의 소스 또는 프로필 속성이 잘못되었거나, 스킬 안내에서 무엇을 전달해야 하는지 명확하지 않아요.
해결 방법: 변수 아래에서 변수 이름, 소스, 선택한 프로필 속성을 확인해 주세요. 변수 설명과 스킬 안내를 업데이트해서 무엇을 제공해야 하는지 명확히 적어 주세요.

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

자주 묻는 질문

하나의 도구를 여러 스킬에서 사용할 수 있나요?
예, 그렇습니다. 도구를 한 번 생성하면 여러 스킬에서 사용할 수 있어요. 각 스킬의 편집 가능한 안내에 삽입한 다음, 각 스킬을 게시하거나 업데이트해 주세요.

지원되는 인증 방법은 무엇인가요?
베어러 토큰이나 API 키 헤더처럼 요청과 함께 정적 자격 증명을 전송하는 모든 방법이 지원돼요. 자격 증명을 시크릿으로 저장하고 Secret 변수로 참조하세요(6단계 참조). OAuth처럼 요청 시점에 토큰을 가져오거나 새로 고쳐야 하는 플로우는 완전 맞춤 도구에서 지원되지 않아요.

엔드포인트가 다운되거나 오류를 반환하면 어떻게 되나요?
Klaviyo는 도구 실패를 고객 에이전트에 보고해요. 일시적인 실패는 도구의 타임아웃 및 재시도 한도 내에서 다시 시도할 수 있어요. 스킬의 안내에서, 도구가 요청을 완료하지 못하는 경우 어떻게 응답할지(예: 담당자에게 연결해 드리겠다고 안내하기)를 설명해 주세요. 신뢰할 수 있는 엔드포인트를 사용하고, 도구 동작을 면밀히 모니터링해 주세요.

도구를 만든 후에 편집할 수 있나요?
예, 그렇습니다. 고객 에이전트 > 커넥터 > 사용자 지정에서 도구를 열고 이름, 설명 또는 요청 구성을 편집한 다음 저장을 클릭해 주세요. 각 스킬의 안내에서 도구를 추가하거나 제거해 주세요.

도구에 버전을 지정할 수 있나요?
아직 버전 관리는 지원되지 않아요. 저장된 변경 사항은 직접 사용을 포함해 공유 도구와 이를 참조하는 모든 스킬에 적용돼요. 저장하고 테스트 실행을 사용하면 변경 사항도 저장되므로, 편집하기 전에 도구의 권한과 실제 사용 현황을 검토해 주세요.

추가 자료