Skip to main content
POST
/
tools
curl --request POST \
  --url https://client-api.tryvox.co/v3/tools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "weather_lookup",
  "description": "지정한 도시의 현재 날씨를 반환합니다.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "도시명 (예: '서울')"
      }
    },
    "required": [
      "city"
    ]
  },
  "api_configuration": {
    "url": "https://api.example.com/weather",
    "method": "GET",
    "timeout_seconds": 5
  },
  "response_mode": "wait"
}
EOF
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "input_schema": {},
  "api_configuration": {
    "url": "<string>",
    "has_auth_credentials": true,
    "timeout_seconds": 30,
    "headers": {}
  },
  "allow_interruption_during_execution": true,
  "created_at": 123,
  "updated_at": 123,
  "description": "<string>",
  "speak_during_execution": {
    "enabled": false,
    "messages": [
      "<string>"
    ]
  },
  "response_mode": "wait"
}

Authorizations

​
Authorization
string
header
required

조직 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Body

application/json

custom 도구 정의입니다. input_schema는 에이전트 모델에 노출되는 JSON Schema이고, api_configuration은 도구 실행 시 보낼 HTTP 요청을 정의합니다.

도구 생성 요청 (POST /v3/tools).

​
name
string
required

도구 이름. 영숫자, 하이픈, 언더스코어만 허용. 1~64자.

Required string length: 1 - 64
Pattern: ^[a-zA-Z0-9_-]+$
​
input_schema
Input Schema · object
required

도구 입력 파라미터를 정의하는 JSON Schema 객체.

​
api_configuration
ToolApiConfigurationWrite · object
required

외부 API 호출 설정.

​
description
string | null

도구 설명입니다. null을 허용합니다.

​
speak_during_execution
SpeakDuringExecution · object

실행 중 사용자에게 재생할 TTS 메시지 설정.

​
allow_interruption_during_execution
boolean
default:false

도구 실행 중 사용자 발화로 인터럽트를 허용할지 여부입니다. 기본값은 false입니다.

​
response_mode
enum<string>
default:wait

wait는 API 응답을 기다려 결과를 대화에 전달한다. fire_and_forget은 요청을 보낸 뒤 즉시 다음 대화로 진행한다.

Available options:
wait,
fire_and_forget

Response

성공 응답

도구 상세 조회/생성/수정 응답 스키마.

​
id
string<uuid>
required

도구의 고유 식별자입니다.

​
name
string
required

도구 이름.

Required string length: 1 - 64
Pattern: ^[a-zA-Z0-9_-]+$
​
input_schema
Input Schema · object
required

도구 입력 파라미터를 정의하는 JSON Schema 객체.

​
api_configuration
ToolApiConfigurationResponse · object
required

외부 API 호출 설정.

​
allow_interruption_during_execution
boolean
required

도구 실행 중 사용자 발화로 인터럽트 허용 여부.

​
created_at
integer
required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

​
updated_at
integer
required

리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다.

​
description
string | null

도구 설명입니다. 설정하지 않으면 null입니다.

​
speak_during_execution
SpeakDuringExecution · object

실행 중 TTS 메시지 설정.

​
response_mode
enum<string>
default:wait

응답 대기 모드. fire_and_forget은 결과 본문을 대화에 사용하지 않는다.

Available options:
wait,
fire_and_forget