Custom Tools

Let your AI call your own endpoints to fetch live, customer-specific data

Standard & Pro 요금제

개요

맞춤 도구를 사용하면 AI 에이전트가 대화 중에 직접 사용하는 API 엔드포인트를 호출하여 주문 상태, 배송 추적, 특정 SKU의 재고, 계정 정보 등 요청별 실시간 데이터를 가져올 수 있습니다.

Asyntai는 실시간 또는 고객별 데이터를 AI에 제공하는 세 가지 방법을 제공합니다. 맞춤 도구는 AI가 필요로 하는 값이 대화 도중에만 나타날 때 적합한 선택입니다:

실시간 데이터 피드 — 하나의 고정된 데이터셋(예: 전체 제품 카탈로그)을 모든 대화에 불러옵니다. 모든 방문자에게 동일한 공유 데이터에 가장 적합합니다.
사용자 컨텍스트 — 사이트가 현재 방문자에 대해 이미 알고 있는 데이터(예: 로그인한 고객의 이름, 요금제, 최근 주문)를 채팅 시작 시 전달합니다. 방문자가 미리 식별되어 있을 때 가장 적합합니다.
맞춤 도구 — AI가 채팅에서 추출한 값으로 필요할 때마다 엔드포인트를 호출합니다. 익명 방문자의 주문 번호처럼 고객이 입력하기 전까지 값을 알 수 없을 때 가장 적합합니다.

예를 들어 고객이 “제 주문 #10294은 어디에 있나요?”라고 물으면, AI는 주문 번호를 추출하여 그 값으로 엔드포인트를 호출하고 검증된 응답을 사용해 답변합니다. 주문 번호는 대화 도중에야 알 수 있기 때문에 사용자 컨텍스트만으로는 이 경우를 처리할 수 없으며, 바로 여기에 맞춤 도구가 적합합니다. (많은 상점이 로그인한 방문자에게는 사용자 컨텍스트를 사용하고 동시에 임의 조회에는 맞춤 도구를 사용합니다.)

AI는 작성하신 설명을 바탕으로 도구를 언제 호출할지 결정합니다. 도구를 엔드포인트로 지정함으로써 도구가 무엇을 하는지는 사용자가 결정합니다. Asyntai가 서버 측에서 호출을 수행하므로, 코드를 작성하거나 미들웨어를 호스팅할 필요가 없습니다.

작동 방식

도구를 정의합니다 — 이름, 설명, 엔드포인트 URL, 그리고 AI가 보내야 할 매개변수를 지정합니다.
AI가 관련 상황에서 호출합니다 — 대화가 설명과 일치하면, AI는 고객 메시지에서 추출한 값으로 도구를 호출합니다.
Asyntai가 엔드포인트를 호출합니다 — 당사 서버가 해당 URL로 HTTP 요청을 보내고 응답을 AI에 전달합니다.
AI가 답변합니다 — 엔드포인트가 반환한 검증된 데이터를 사용합니다.

코드가 필요 없습니다: 이미 데이터를 반환하는 엔드포인트만 있으면 됩니다. 나머지는 모두 대시보드 양식에서 설정하며, 별도로 만들어야 할 콜백, 웹훅, 브라우저 스크립트가 없습니다.

AI 어시스턴트

제 주문 #10294은 어떻게 되었나요?

지금 확인해 드리겠습니다…

주문 #10294이 접수되어 배송 준비 중입니다. 배송이 시작되면 추적 링크를 이메일로 받아보실 수 있습니다.

감사합니다!

천만에요! 더 도와드릴 일이 있을까요?

사용 사례

주문 상태 번호로 주문을 조회하고 현재 상태를 반환합니다

배송 추적 추적 번호에 대한 최신 추적 상태를 반환합니다

재고 확인 특정 제품 또는 SKU의 실시간 재고 현황을 반환합니다

계정 조회 식별자에 대한 계정 또는 구독 정보를 반환합니다

설정

맞춤 도구 열기 /custom-tools/로 이동하여 도구 추가를 클릭합니다

도구 설명하기 이름, 명확한 설명, 그리고 엔드포인트 URL을 입력합니다

매개변수 정의하기 AI가 추출하여 보내야 할 입력값을 추가합니다(예: order_number)

저장 & 테스트 저장한 다음, 봇에게 일치하는 질문을 던져 작동하는 모습을 확인합니다

필드

이름 — 함수의 식별자입니다(영문자, 숫자, 밑줄), 예: get_order_status. AI는 이 이름을 봅니다.
설명 — 가장 중요한 필드입니다. AI에게 도구를 언제 호출할지 알려줍니다. 명확하게 작성하세요: “고객이 주문 번호를 언급할 때마다 이 도구를 호출하세요. 추가 확인을 요청하지 마세요.”
엔드포인트 URL — Asyntai가 호출할 공개 HTTPS URL입니다.
HTTP 메서드 — GET(읽기 전용, 권장) 또는 POST(데이터를 변경할 수 있음 — 아래 보안 참조).
매개변수 — AI가 대화에서 추출하여 보내는 입력값입니다. 각각 이름, 유형, 설명, 필수 여부 플래그를 가집니다. GET의 경우 쿼리 문자열 매개변수로 전송되고, POST의 경우 JSON 본문으로 전송됩니다.
인증 헤더 (선택 사항) — 모든 호출 시 전송되는 헤더 이름 + 값입니다, 예: X-API-Key. 엔드포인트에 키가 필요한 경우 사용하세요.

AI가 값을 전달하려면 매개변수가 필요합니다. 엔드포인트에 입력값(예: 주문 번호)이 필요하다면, 반드시 그에 대한 매개변수를 추가해야 합니다. 매개변수가 없으면 AI는 값을 넣을 자리가 없어 엔드포인트를 비어 있는 상태로 호출하게 됩니다. 두 가지가 중요합니다:

매개변수 이름은 엔드포인트가 기대하는 것과 정확히 일치해야 합니다. order_number라는 이름의 매개변수는 ?order_number=...(GET) 또는 {"order_number": "..."}(POST)로 전송됩니다. 엔드포인트가 id를 읽는다면 매개변수 이름을 id로 지정하세요.
값을 직접 입력하는 일은 결코 없으며, 매개변수만 선언합니다. AI가 호출 시점에 고객이 작성한 내용에서 값을 채웁니다.

실제 예시: 주문 상태 조회

상점이 다음 엔드포인트를 제공한다고 가정해 보겠습니다:

GET https://yourstore.com/api/order-status?order_number=10294

…이는 다음과 같은 JSON을 반환합니다:

{
  "found": true,
  "status": "Accepted, preparing for shipment",
  "carrier": "DHL",
  "customer_message": "Your order has been accepted and is being prepared for shipment."
}

다음과 같이 도구를 구성합니다:

이름: get_order_status
설명: “고객 주문의 상태를 조회합니다. 고객이 주문 번호를 제공할 때마다 즉시 이 도구를 호출하고, 추가 확인을 요청하지 마세요. 답변에는 반환된 customer_message를 사용하세요.”
엔드포인트 URL: https://yourstore.com/api/order-status
메서드: GET
매개변수: order_number (string, 필수) — “고객의 주문 번호이며, 일반적으로 8자리 이상입니다.”

고객이 “제 주문 #10294은 어떻게 되었나요?”라고 작성하면, AI는 get_order_status(order_number=10294)를 호출하고, Asyntai는 ?order_number=10294를 붙여 해당 URL로 요청을 보내며, AI는 그 응답을 사용해 답변합니다.

팁: AI는 스스로 결정한 값을 전송하며, 사용자가 미리 채워 넣지 않습니다. 모델이 무엇을 추출해야 하는지 정확히 알 수 있도록 매개변수 이름과 설명을 명확하게 유지하세요.

엔드포인트가 수신하는 내용과 반환해야 할 내용

요청: 매개변수가 쿼리 문자열에 포함된 GET, 또는 JSON 본문이 포함된 POST입니다. 구성한 인증 헤더가 있으면 함께 포함됩니다.
응답: JSON(권장) 또는 일반 텍스트를 반환합니다. Asyntai는 본문을 AI에 전달합니다. customer_message처럼 AI가 직접 인용할 수 있는 필드가 효과적입니다.
찾을 수 없음 / 오류: 명확한 페이로드(예: found: false와 customer_message가 포함된 JSON 객체)를 반환하여 AI가 추측하는 대신 사실대로 답변할 수 있도록 하세요.

도구 테스트하기

각 도구에는 구성 페이지에 이 도구 테스트 패널이 내장되어 있어, 고객이 사용하기 전에 — 그리고 봇을 통해 메시지를 보내지 않고도 — 정상 작동 여부를 확인할 수 있습니다.

도구의 매개변수에 대한 샘플 값을 입력합니다(예: 실제 주문 번호).
테스트 실행을 클릭합니다. Asyntai는 AI와 똑같은 방식으로 엔드포인트를 호출합니다 — 동일한 쿼리 문자열 또는 JSON 본문, 동일한 인증 헤더, 동일한 5초 시간 제한 및 안전 검사를 사용합니다.
결과를 즉시 확인할 수 있습니다: 성공/실패 배지, HTTP 상태, 응답 시간, 당사가 호출한 정확한 URL, 그리고 엔드포인트의 원시 응답(JSON인 경우 보기 좋게 정렬됨).

저장하지 않은 수정 사항에도 작동하므로, URL, 매개변수 또는 인증 헤더를 조정하고 원하는 결과가 반환될 때까지 다시 테스트할 수 있습니다.

참고: POST 도구를 테스트하면 실제로 엔드포인트를 호출하여 데이터가 변경될 수 있으며, 테스트 패널이 실행 전에 경고합니다. 읽기 전용 GET 도구의 경우 걱정할 것이 없습니다.

보안 — 반드시 읽어보세요

보안 경계는 AI가 아니라 엔드포인트입니다. 채팅 위젯은 공개되어 있으며, 방문자가 AI를 조작하여 임의의 값으로 도구를 호출하게 만들 수 있습니다. 이는 모든 AI 도구 호출 시스템에 해당합니다. 이에 맞게 엔드포인트를 설계하세요:

GET / 읽기 전용을 선호하세요. 조회(주문 상태, 재고, 추적)는 노출해도 안전합니다. 이러한 이유로 GET이 기본값입니다.
POST에는 동의가 필요합니다. POST는 데이터를 변경할 수 있으므로, 자신의 엔드포인트에서 요청을 보호하고 인가하는 책임이 전적으로 본인에게 있음을 확인하는 체크박스를 선택한 후에야 POST 도구를 저장할 수 있습니다. 엔드포인트가 요청을 독립적으로 검증하지 않는 한, 환불, 취소, 비밀번호 변경, 자금 이동을 절대 연결하지 마세요.
열거 공격에 대비하세요. 조회 키가 추측 가능한 경우(예: 순차적인 주문 번호), 두 번째 요소를 요구하세요 — 예를 들어 주문 번호 와 주문에 등록된 이메일을 함께 요구하고 일치하는지 확인하여 — 방문자가 번호를 무작위로 시도하여 다른 고객의 데이터를 읽지 못하도록 하세요.
AI의 인수를 절대 신뢰하지 마세요. 모든 요청이 익명의 공격자로부터 온 것처럼 서버 측에서 검증하고 인가하세요 — 사실상 그럴 수 있기 때문입니다.

실제 호출 확인하기

도구가 활성화되면 대화에서 발생하는 모든 실제 호출이 기록됩니다. 각 호출에 대해 당사는 도구 이름, AI가 보낸 인수, 당사가 요청한 정확한 URL, HTTP 상태, 응답, 소요 시간을 기록합니다. 이를 통해 자신의 서버 로그를 뒤지지 않고도 실제 채팅에서 도구가 작동했는지 확인하고 엔드포인트가 무엇을 반환했는지 볼 수 있습니다. (위의 이 도구 테스트 패널은 본인이 직접 설정을 확인하기 위한 것이며, 이 로그는 실제 고객 대화 중에 일어나는 일을 포착합니다.)

제한 & 안전장치

웹사이트당 최대 10개의 도구.
호출당 5초 시간 제한이 있으며, 응답은 10 KB로 제한됩니다.
엔드포인트는 공개 http(s) URL이어야 합니다. 사설, 루프백, 내부 네트워크 주소는 차단됩니다.
Standard 및 Pro 요금제에서 사용할 수 있습니다.
요금: 각 도구 호출은 요금제에서 추가 메시지 1건으로 계산됩니다. 일반 답변은 메시지 1건을 사용하지만, AI가 도구를 호출하는 답변은 2건(답변과 도구 호출)을 사용합니다. 도구 호출에는 추가 AI 요청이 필요하기 때문입니다.
도구 호출이 실패하면(시간 초과, 오류, 차단), AI에 그 사실이 전달되어 자연스럽게 답변합니다 — 대화가 중단되지 않습니다.

문서