API 도구

API 도구는 에이전트가 통화 중에 사용자의 HTTP 엔드포인트나 외부 API를 호출하게 해요. 에이전트는 대화에서 모은 값을 요청에 담아 보내고, 받은 응답으로 대화를 이어가요.

언제 사용하나요

고객 정보를 확인할 때: 사용자 ID로 고객의 세부 정보를 가져와 상담에 써요.
문의를 접수할 때: 통화에서 들은 요약과 설명으로 지원 티켓을 제출해요.
매장 정보를 안내할 때: 고객이 말한 지점의 운영 시간을 조회해 알려 줘요.
알림을 보내거나 기록을 남길 때: 응답을 기다리지 않고 요청만 보내 통화 흐름을 막지 않아요.

API 도구 추가하기

도구 만들기

구축 > 도구에서 도구 만들기를 누르세요. 도구 이름은 에이전트가 이 도구를 부를 때 쓰는 이름이에요. 예: get_user_details, submit_support_ticket. 도구 설명에는 도구가 하는 일과 에이전트가 이 도구를 써야 하는 상황을 적으세요. 설명이 분명해야 에이전트가 알맞은 때에 불러요. 예: 사용자 ID로 사용자 세부 정보를 가져옵니다.

엔드포인트 정하기

API 엔드포인트에 메서드와 요청을 받을 전체 URL을 넣고, 응답 대기 시간을 정하세요. 메서드는 GET, POST, PUT, PATCH, DELETE 가운데 하나이고 대시보드에서 새로 만들면 GET이에요. v3 API로 만들 때는 메서드를 꼭 적어야 해요. 응답 대기 시간은 에이전트가 응답을 기다리는 최대 시간(초)이니 엔드포인트의 응답 시간에 맞추세요.

파라미터 정의하기

파라미터에 엔드포인트가 받을 값을 OpenAPI 3.0 사양에 따라 적으세요. 에이전트는 이 스키마를 보고 통화 중에 필요한 값을 모아요.

실행 중 소리와 응답 처리 고르기

실행 대기음은 도구가 실행되는 동안 재생할 소리예요. 기본값은 소리 없음이고, 동작은 실행 대기음에 있어요. 응답 대기 방식의 기본값은 결과 기다리기예요. 아래 응답 대기 방식 고르기를 보고 고른 뒤 만들기를 눌러 저장하세요.

에이전트에 붙이고 호출 조건 적기

에이전트 설정의 도구에서 추가를 눌러 만든 도구를 붙이세요. 프롬프트에 언제 이 도구를 쓸지 도구 이름으로 적으세요.

고객이 운영 시간을 물으면 지점 이름을 확인한 뒤 lookup_store_hours 도구를 사용하세요.

응답 대기 방식 고르기

도구를 실행할 때 API 응답을 기다릴지 고르세요. v3 API 필드는 response_mode예요.

방식	통화에서
결과 기다리기(`wait`, 기본값)	응답을 받은 뒤 결과를 대화에 반영해요
요청만 보내고 계속 진행(`fire_and_forget`)	요청을 보낸 직후 대화를 이어가요. 응답 본문은 대화에 쓰지 않아요

요청만 보내고 계속 진행은 알림 전송, 기록 적재처럼 응답을 대화에 쓰지 않는 호출에 맞아요. 응답을 기다리지 않아서 느린 엔드포인트가 통화 흐름을 막지 않아요.

늦게 도착한 성공이나 실패는 대화에 반영되지 않고 도구 호출 기록에만 남아요. 호출이 실패하거나 타임아웃이 나도 통화에는 영향이 없어요.
플로우에서는 응답 변수나 결과 기반 전환 조건과 함께 쓸 수 없어요. 함께 쓰면 저장할 때 거부돼요.
플로우의 도구 노드는 도구에 정한 응답 대기 방식을 그대로 따라요. 노드에서 따로 바꿀 수 없어요.

통화에서 일어나는 일

에이전트가 도구를 쓰기로 하면 요청을 보내요. 정한 메서드로 API 엔드포인트에 HTTP 요청을 보내요. 대화에서 뽑은 값은 파라미터 스키마에 맞춰 쿼리 매개변수(GET)나 요청 본문(POST, PUT, PATCH, DELETE)에 담겨요.
응답은 에이전트에게 전달돼요. 에이전트는 JSON 응답을 보고 다음 행동을 정하거나 고객에게 필요한 정보를 알려요. 본문은 15,000자까지만 전달되고, 넘으면 잘렸다는 표시와 원래 길이가 붙어요. 응답에는 에이전트가 쓸 값만 담으세요.

엔드포인트에서 요청 받기

파라미터에 정의한 값은 메서드에 따라 다른 곳에 담겨요.

메서드	값이 담기는 곳
`GET`	URL 쿼리 매개변수
`POST`, `PUT`, `PATCH`, `DELETE`	JSON 요청 본문

GET 요청 받기

GET 요청에는 JSON 요청 본문이 없어요. 값은 URL 뒤에 ?key=value 꼴로 붙어요. 엔드포인트 URL이 다음과 같다고 해 볼게요.

https://api.example.com/orders

파라미터를 다음과 같이 정의하면 에이전트는 대화 중에 주문 ID를 모아요.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "조회할 주문 ID입니다."
    }
  },
  "required": ["order_id"]
}

에이전트가 ORD-1234를 모으면 요청은 다음처럼 가요.

GET https://api.example.com/orders?order_id=ORD-1234

GET에서 항상 같은 값은 엔드포인트 URL에 직접 넣을 수 있어요. 대화 중 달라지는 값은 파라미터에 정의하세요. URL에 고정 쿼리 매개변수가 있으면 에이전트가 모은 값은 기존 쿼리 뒤에 붙어요.

GET https://api.example.com/orders?locale=ko&order_id=ORD-1234

배열 값은 같은 키를 반복하고, 객체 값은 JSON 문자열로 보내요. tags 값이 ["vip", "gift"]이고 filter 값이 {"status":"shipped"}이면 요청은 다음과 같아요.

GET https://api.example.com/orders?tags=vip&tags=gift&filter=%7B%22status%22%3A%22shipped%22%7D

값이 null인 파라미터와 빈 배열은 보내지 않아요. false와 0, 빈 문자열은 각각 false, 0, key=로 보내요. URL에 미리 적은 중복 키와 빈 값도 그대로 남아요.

JSON 요청 본문 받기

POST, PUT, PATCH, DELETE 메서드는 파라미터 값을 JSON 요청 본문으로 보내요.

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "사용자의 고유 식별자입니다."
    },
    "includeOrderHistory": {
      "type": "boolean",
      "description": "응답에 사용자의 주문 내역을 포함할지 여부입니다."
    }
  },
  "required": ["userId"]
}

예를 들어 lookup_store_hours 도구의 메서드가 POST이고 에이전트가 대화에서 「강남점 운영 시간」을 알아냈다면, 서버로 가는 요청은 다음과 같을 수 있어요.

POST https://your-api-server.com/lookup_store_hours
Content-Type: application/json

{
  "branchName": "강남점"
}

엔드포인트에서 응답 돌려주기

요청을 처리한 뒤 JSON으로 응답하세요. 응답 내용은 에이전트에게 전달돼 다음 행동을 정하거나 고객에게 알릴 정보로 쓰여요.

{
  "branchName": "강남점",
  "hours": "평일 09:00-18:00",
  "status": "open"
}

호출 중 오류가 나면 알맞은 HTTP 상태 코드(4xx, 5xx)와 오류 내용을 담은 JSON 본문을 돌려주세요.

{
  "error": "알 수 없는 지점입니다.",
  "details": "지정된 지점에 대한 운영 시간 정보를 찾을 수 없습니다."
}

문제가 생겼을 때

에이전트가 도구를 부르지 않아요

도구 설명과 프롬프트에 도구를 쓸 상황을 도구 이름과 함께 적었는지 확인하세요. 만든 도구를 에이전트 설정의 도구에 붙였는지도 보세요.

에이전트가 API 응답 내용을 말하지 않아요

응답으로 답해야 하는 도구는 응답 대기 방식을 결과 기다리기로 바꾸세요. 요청만 보내고 계속 진행이면 응답 본문을 대화에 쓰지 않아요.

플로우를 저장할 때 거부돼요

도구의 응답 대기 방식을 결과 기다리기로 바꾸거나 응답 변수와 결과 기반 전환 조건을 빼세요. 요청만 보내고 계속 진행으로 둔 도구를 응답 변수나 결과 기반 전환 조건과 함께 쓰면 저장이 거부돼요.

서버가 GET 요청의 배열이나 객체 값을 읽지 못해요

서버에서 반복된 키를 배열로 모으고 객체 값은 JSON으로 파싱하세요. 배열 값은 같은 키를 반복해서 오고, 객체 값은 URL 인코딩된 JSON 문자열로 와요.

시작하기

구축

배포

발신

모니터링

설정

정책

언제 사용하나요

API 도구 추가하기

응답 대기 방식 고르기

통화에서 일어나는 일

엔드포인트에서 요청 받기

GET 요청 받기

JSON 요청 본문 받기

엔드포인트에서 응답 돌려주기

문제가 생겼을 때

관련 문서

​언제 사용하나요

​API 도구 추가하기

​응답 대기 방식 고르기

​통화에서 일어나는 일

​엔드포인트에서 요청 받기

​GET 요청 받기

​JSON 요청 본문 받기

​엔드포인트에서 응답 돌려주기

​문제가 생겼을 때

​관련 문서

언제 사용하나요

API 도구 추가하기

응답 대기 방식 고르기

통화에서 일어나는 일

엔드포인트에서 요청 받기

GET 요청 받기

JSON 요청 본문 받기

엔드포인트에서 응답 돌려주기

문제가 생겼을 때

관련 문서