> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryvox.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API 도구

> vox.ai의 에이전트가 사용할 API 도구를 만들고 구성하는 방법을 알아보세요.

# 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 사양](https://swagger.io/specification/)에 따라 기술하는 객체입니다. 에이전트는 이 스키마를 참조해 API 호출에 필요한 데이터를 대화 중에 수집합니다.
* **`타임아웃`**: 에이전트가 API 엔드포인트로부터 응답을 기다리는 최대 시간(초)입니다. API의 예상 응답 시간을 고려하여 적절한 값을 설정하세요.
* **`응답 대기 방식`**: 도구 실행 시 API 응답을 기다릴지 여부입니다. 기본값은 응답을 기다리는 `결과 기다리기`이며, 자세한 차이는 아래 [응답 대기 방식](#응답-대기-방식)을 참고하세요.

### 응답 대기 방식

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

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

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

다음 사항에 유의하세요.

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

### 파라미터 전달 방식

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

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

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

#### GET 예시

엔드포인트 URL이 다음과 같다고 가정합니다.

```text theme={null}
https://api.example.com/orders
```

`파라미터`를 다음과 같이 정의하면, 에이전트는 대화 중 주문 ID를 수집합니다.

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

에이전트가 `ORD-1234`를 수집하면 요청은 다음처럼 전송됩니다.

```http theme={null}
GET https://api.example.com/orders?order_id=ORD-1234
```

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

```http theme={null}
GET https://api.example.com/orders?locale=ko&order_id=ORD-1234
```

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

#### JSON 요청 본문 예시

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

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

### 에이전트의 API 호출 방식

```mermaid theme={null}
sequenceDiagram
    participant A as 에이전트
    participant S as 외부 서버
    A->>S: HTTP 요청 (선택한 메서드)
    S-->>A: JSON 응답
    A->>A: 응답 파싱 후 대화에 반영
```

에이전트가 특정 API 도구를 사용하기로 결정하면, 설정된 `메서드`를 사용하여 지정된 `엔드포인트`로 HTTP 요청을 전송합니다. 요청 본문(`POST`, `PUT`, `PATCH`, `DELETE`) 또는 쿼리 매개변수(`GET`)에는 대화에서 추출된 인수가 포함되며, 사용자가 정의한 `파라미터` 스키마와 일치하게 됩니다.

예를 들어, `lookup_store_hours`라는 이름의 도구가 있고 에이전트가 대화에서 "강남점 운영 시간"을 파악했다면, 서버로 전송되는 요청은 다음과 같을 수 있습니다 (`메서드: "POST"` 가정):

**서버로 전송되는 요청 예시:**

```http theme={null}
POST https://your-api-server.com/lookup_store_hours
Content-Type: application/json

{
  "branchName": "강남점"
}
```

### 서버의 응답 처리

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

**성공적인 서버 응답 예시:**

```json theme={null}
{
  "branchName": "강남점",
  "hours": "평일 09:00-18:00",
  "status": "open"
}
```

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

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

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

## 관련 문서

* [도구 개요](/docs/build/tools/overview)
* [빌트인 도구 — 통화 종료](/docs/build/tools/builtin/end-call)

***

<Accordion title="연관 검색어">
  API 도구, API tool, 커스텀 도구, custom tool, HTTP 엔드포인트, 외부 API 연동, 파라미터, 서버 연동
</Accordion>