정의
웹훅은 무언가 일어났거나 필요할 때 한 시스템이 다른 시스템의 URL로 보내는 HTTP 요청입니다. 음성 에이전트에서 웹훅 도구는 에이전트가 통화 중에 자체 엔드포인트를 호출하는 방법입니다.
웹훅의 작동 방식
대부분의 API는 요청을 받기를 기다립니다. 웹훅은 이를 뒤집습니다. 보내는 쪽 시스템이 여러분이 알려 준 주소로 HTTP 요청을 보냅니다. 받는 쪽은 URL을 공개하고, 보내는 쪽은 POST 같은 메서드, 일련의 헤더, 본문과 함께 그것을 호출하며, 받는 쪽은 상태 코드로 응답합니다.
웹훅은 음성 플랫폼에서 두 가지 방식으로 나타납니다.
- 이벤트 콜백. 통화 종료처럼 일어난 일을 플랫폼이 서버에 알려 주어 전사를 저장하거나 기록을 갱신할 수 있습니다.
- 웹훅 도구. 에이전트가 통화 도중 자체 엔드포인트를 호출해 무언가를 조회하거나 실행하고 그 응답을 사용합니다. 이는 도구 호출의 한 형태입니다.
Cartesia의 Managed Agents에서 웹훅 도구는 URL, HTTP 메서드, 매개변수, 헤더, 인증으로 정의됩니다. Cartesia는 다음 동작을 문서화합니다.
- URL은 HTTPS여야 합니다.
- 모델이 도구 설명을 보고 언제 호출할지 결정합니다.
- 각 매개변수는 모델, 고정 값, 또는 동적 변수가 채웁니다.
- 요청 타임아웃의 기본값은 20초입니다.
- 타임아웃, 연결되지 않는 엔드포인트, 2xx가 아닌 상태는 모델에 오류 결과를 돌려주며 통화는 계속됩니다.
음성 에이전트에게 중요한 이유
웹훅은 대화와 여러분의 시스템을 잇는 연결이므로 그 동작이 귀에 들립니다. 느린 엔드포인트는 정적을 만듭니다. 실패하는 엔드포인트는 모델이 말해야 하는 오류를 돌려주므로, 응답 본문은 에이전트가 쓸 수 있는 말로 무엇이 잘못되었는지 알려 주어야 합니다.
받는 쪽은 발신자가 지켜보고 있다고 생각하고 설계하세요. 긴 JSON 덤프는 모델이 읽는 데 시간이 드니 짧고 평이한 텍스트를 돌려주세요. 데이터를 바꾸는 작업은 재시도나 모델의 중복 요청이 예약을 두 개 잡지 않도록 반복해도 안전하게 만드세요. 요청을 인증하고 모든 매개변수를 자체 서버에서 확인하세요. 모델이 제공하는 값은 낯선 사람과의 대화에서 나오기 때문입니다.
타임아웃은 발신자가 받아들일 멈춤에 맞춰 정하세요. 20초 타임아웃은 통화에서 침묵하기에 긴 시간이므로, 느린 도구는 실행 전에 에이전트가 한마디 하도록 함께 설계하세요.
예시
주문 전화 회선용 설명용 웹훅 도구입니다.
- 메서드와 URL: GET
https://api.example.com/orders/{order_id} - 설명: “주문 번호로 주문 상태를 조회합니다.”
- 응답: “화요일 발송, 금요일 도착 예정.”
모델은 발신자가 한 말로 order_id를 채우고 응답을 자신의 말로 말합니다.