API 도구

API 도구를 활용하면 에이전트가 사용자의 HTTP 엔드포인트나 외부 API와 직접 통신하여 다양한 작업을 수행할 수 있습니다. 에이전트의 기능을 원하는 대로 확장하고 세밀하게 제어할 수 있는 핵심 수단입니다.

API 도구 설정 이해하기

API 도구를 효과적으로 설정하고 관리하기 위해 다음 주요 구성 필드들을 이해하는 것이 중요합니다. 각 필드는 API 도구가 어떻게 동작하고 에이전트와 상호작용하는지를 정의합니다.

주요 구성 필드:

이름: 도구를 식별하는 고유한 이름입니다. 에이전트는 이 이름을 사용하여 특정 API 도구를 호출합니다. (예: get_user_details, submit_support_ticket)
설명: 도구가 어떤 작업을 수행하는지, 어떤 기능을 가지고 있는지, 에이전트가 어떤 상황에서 이 도구를 사용해야 하는지를 설명하는 자연어 텍스트입니다. 명확한 설명은 에이전트가 도구를 적절히 활용하는 데 핵심적인 역할을 합니다. (예: “사용자 ID를 기반으로 사용자 세부 정보를 가져옵니다.” 또는 “제공된 요약 및 설명으로 새 지원 티켓을 제출합니다.”)
엔드포인트 URL: API가 호스팅되어 요청을 수신하는 전체 URL 주소입니다. (예: https://api.example.com/users, https://your-backend.com/submit-ticket)
메서드: 엔드포인트가 예상하는 HTTP 메서드입니다. v3 API에서는 "GET", "POST", "PUT", "PATCH", "DELETE" 중 하나를 명시해야 합니다. 대시보드에서 새 API 도구를 만들면 기본값은 "GET"입니다.
파라미터: API 엔드포인트가 필요로 하는 값을 OpenAPI 3.0 사양에 따라 기술하는 객체입니다. 에이전트는 이 스키마를 참조해 API 호출에 필요한 데이터를 대화 중에 수집합니다.
타임아웃: 에이전트가 API 엔드포인트로부터 응답을 기다리는 최대 시간(초)입니다. API의 예상 응답 시간을 고려하여 적절한 값을 설정하세요.
응답 대기 방식: 도구 실행 시 API 응답을 기다릴지 여부입니다. 기본값은 응답을 기다리는 결과 기다리기이며, 자세한 차이는 아래 응답 대기 방식을 참고하세요.

응답 대기 방식

도구 실행 시 API 응답을 기다릴지 선택합니다 (v3 API 필드: response_mode).

모드	동작
결과 기다리기 (`wait`, 기본값)	응답을 받은 뒤 결과를 대화에 반영합니다.
요청만 보내고 계속 진행 (`fire_and_forget`)	요청을 보낸 직후 대화를 계속 진행합니다. 응답 본문은 대화에 사용되지 않습니다.

요청만 보내고 계속 진행은 알림 전송, 기록 적재처럼 응답 결과를 대화에 쓰지 않는 호출에 적합합니다. 응답을 기다리지 않으므로 느린 엔드포인트가 통화 흐름을 막지 않습니다. 다음 사항에 유의하세요.

늦게 도착한 성공/실패는 대화에 반영되지 않고 도구 호출 기록에만 남습니다. 호출 실패나 타임아웃도 통화에는 영향을 주지 않습니다.
플로우에서 사용할 때 응답 변수나 결과 기반 전환 조건과는 함께 쓸 수 없습니다 — 저장 시 거부됩니다.
플로우의 도구 노드는 도구에 설정된 응답 대기 방식을 그대로 상속합니다. 노드에서 별도로 변경할 수 없습니다.

파라미터 전달 방식

파라미터에 정의한 값은 선택한 메서드에 따라 다른 위치로 전달됩니다.

메서드	전달 위치
`GET`	URL 쿼리 매개변수
`POST`, `PUT`, `PATCH`, `DELETE`	JSON 요청 본문

GET 요청에는 JSON 요청 본문을 보내지 않습니다. 파라미터에 정의한 값은 URL 뒤에 ?key=value 형태로 붙습니다.

GET 예시

엔드포인트 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

엔드포인트 URL에 이미 고정 쿼리 매개변수가 있으면, 에이전트가 수집한 값은 기존 쿼리 뒤에 추가됩니다.

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

항상 같은 값은 엔드포인트 URL에 직접 넣을 수 있습니다. 대화 중 달라지는 값은 파라미터에 정의하세요.

JSON 요청 본문 예시

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

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

에이전트의 API 호출 방식

에이전트가 특정 API 도구를 사용하기로 결정하면, 설정된 메서드를 사용하여 지정된 엔드포인트로 HTTP 요청을 전송합니다. 요청 본문(POST, PUT, PATCH, DELETE) 또는 쿼리 매개변수(GET)에는 대화에서 추출된 인수가 포함되며, 사용자가 정의한 파라미터 스키마와 일치하게 됩니다. 예를 들어, lookup_store_hours라는 이름의 도구가 있고 에이전트가 대화에서 “강남점 운영 시간”을 파악했다면, 서버로 전송되는 요청은 다음과 같을 수 있습니다 (메서드: "POST" 가정): 서버로 전송되는 요청 예시:

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

{
  "branchName": "강남점"
}

서버의 응답 처리

요청을 받은 서버는 해당 작업을 처리한 후 JSON 형식의 응답을 반환해야 합니다. 이 JSON 응답 내용은 에이전트에게 전달되어, 다음 행동을 결정하거나 사용자에게 관련 정보를 전달하는 데 사용됩니다. 성공적인 서버 응답 예시:

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

API 호출 중 오류가 발생했다면, 서버는 적절한 HTTP 상태 코드(예: 4xx 또는 5xx)와 함께 오류의 상세 내용이 담긴 JSON 본문을 반환하는 것이 좋습니다.

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

API 도구를 명확하게 정의하고 올바르게 설정함으로써, 에이전트가 사용자의 기존 인프라 및 다양한 서비스와 효과적으로 상호작용할 수 있는 강력한 기반을 마련할 수 있습니다.

시작하기

빌드하기

배포하기

모니터링

기타

API 도구

API 도구

API 도구 설정 이해하기

주요 구성 필드:

응답 대기 방식

파라미터 전달 방식

GET 예시

JSON 요청 본문 예시

에이전트의 API 호출 방식

서버의 응답 처리

관련 문서

​API 도구

​API 도구 설정 이해하기

​주요 구성 필드:

​응답 대기 방식

​파라미터 전달 방식

​GET 예시

​JSON 요청 본문 예시

​에이전트의 API 호출 방식

​서버의 응답 처리

​관련 문서

API 도구

API 도구 설정 이해하기

주요 구성 필드:

응답 대기 방식

파라미터 전달 방식

GET 예시

JSON 요청 본문 예시

에이전트의 API 호출 방식

서버의 응답 처리

관련 문서