> ## 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. # 도구 생성 > 에이전트가 호출할 custom API 도구를 생성합니다. 모델에 노출할 `input_schema`와 서버가 실행할 API 설정을 함께 정의합니다. ## OpenAPI ````yaml /api-reference/v3/openapi.json post /tools openapi: 3.1.0 info: title: vox.ai API description: > vox.ai API v3 ### v3 공개 계약 규칙 - 인증은 `Authorization: Bearer ` 헤더를 사용합니다. 조직 API 키를 Bearer 토큰으로 전달합니다. - 요청과 응답 필드는 기본적으로 `snake_case`를 사용합니다. - `agent.data`는 에이전트 레지스트리와 호환되어야 하므로 `callSettings`, `toolIds`, `builtInTools`, `presetDynamicVariables` 같은 camelCase 필드를 유지합니다. - `_at`으로 끝나는 타임스탬프는 unix milliseconds입니다. 일부 입력값은 호환성을 위해 10~11자리 unix seconds도 허용하고 milliseconds로 정규화합니다. - 캠페인 통화 가능 시간은 분 단위 정수(`start_min` / `end_min`)를 사용합니다. 알림 스케줄은 `HH:MM` 문자열(`start_time` / `end_time`)을 사용합니다. - 응답 객체 자신의 식별자는 `id`입니다. 다른 리소스를 참조하는 필드와 path parameter는 `agent_id`, `call_id`, `telephone_line_id`처럼 명시적인 이름을 사용합니다. - 실패 응답은 `{ "error": { "code", "message", "details" } }` 형태입니다. 가능한 경우 `details.field`, `details.reason`, `details.allowed_values`를 함께 제공합니다. version: 3.0.0 servers: - url: https://client-api.tryvox.co/v3 description: 운영 security: [] paths: /tools: post: tags: - Tools summary: 도구 생성 description: >- 에이전트가 호출할 custom API 도구를 생성합니다. 모델에 노출할 `input_schema`와 서버가 실행할 API 설정을 함께 정의합니다. operationId: createTool requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateToolRequest' examples: simple_get_no_auth: summary: GET 호출, 인증이 필요 없는 간단한 조회 도구 value: 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 post_with_bearer_and_speak: summary: Bearer 인증 + 실행 중 TTS 안내 value: name: create_lead_in_crm description: CRM 에 신규 리드를 생성합니다. input_schema: type: object properties: name: type: string description: 고객 이름 phone: type: string description: 고객 연락처 (하이픈 없는 국내 번호) interest: type: string description: 관심 분야 (자유 텍스트) required: - name - phone api_configuration: url: https://crm.example.com/api/v1/leads method: POST headers: Content-Type: application/json auth_type: Bearer auth_credentials: timeout_seconds: 10 speak_during_execution: enabled: true messages: - 잠시만 기다려주세요. 정보를 등록 중입니다. allow_interruption_during_execution: false response_mode: fire_and_forget description: >- custom 도구 정의입니다. `input_schema`는 에이전트 모델에 노출되는 JSON Schema이고, `api_configuration`은 도구 실행 시 보낼 HTTP 요청을 정의합니다. responses: '201': description: 성공 응답 content: application/json: schema: $ref: '#/components/schemas/ToolDetail' '400': description: 요청 검증 오류 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: 요청 검증 오류 value: error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank '401': description: 인증이 필요합니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: summary: Bearer 토큰 누락 또는 오류 value: error: code: UNAUTHORIZED message: Authentication is required. details: {} '403': description: 권한이 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: summary: 권한이 없습니다. value: error: code: FORBIDDEN message: Permission denied. details: {} '404': description: 리소스를 찾을 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: 리소스를 찾을 수 없습니다. value: error: code: RESOURCE_NOT_FOUND message: Resource not found. details: resource: agent '409': description: 충돌이 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: conflict: summary: 상태 충돌이 발생했습니다. value: error: code: CONFLICT message: The requested operation conflicts with current state. details: current_status: draft '429': description: 요청 한도를 초과했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimited: summary: 요청 한도를 초과했습니다. value: error: code: RATE_LIMIT_EXCEEDED message: Too many requests. details: limit: 5 window_seconds: 1 '500': description: 서버 내부 오류가 발생했습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: 서버 내부 오류가 발생했습니다. value: error: code: INTERNAL_ERROR message: Internal server error. details: {} '503': description: 서비스를 일시적으로 사용할 수 없습니다. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: serviceUnavailable: summary: 서비스를 일시적으로 사용할 수 없습니다. value: error: code: SERVICE_UNAVAILABLE message: Service temporarily unavailable. details: {} security: - BearerAuth: [] components: schemas: CreateToolRequest: properties: name: type: string maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ title: Name description: 도구 이름. 영숫자, 하이픈, 언더스코어만 허용. 1~64자. description: anyOf: - type: string - type: 'null' title: Description description: 도구 설명입니다. null을 허용합니다. input_schema: additionalProperties: true type: object title: Input Schema description: 도구 입력 파라미터를 정의하는 JSON Schema 객체. api_configuration: $ref: '#/components/schemas/ToolApiConfigurationWrite' description: 외부 API 호출 설정. speak_during_execution: anyOf: - $ref: '#/components/schemas/SpeakDuringExecution' - type: 'null' description: 실행 중 사용자에게 재생할 TTS 메시지 설정. allow_interruption_during_execution: type: boolean title: Allow Interruption During Execution description: 도구 실행 중 사용자 발화로 인터럽트를 허용할지 여부입니다. 기본값은 false입니다. default: false response_mode: type: string enum: - wait - fire_and_forget title: Response Mode description: >- `wait`는 API 응답을 기다려 결과를 대화에 전달한다. `fire_and_forget`은 요청을 보낸 뒤 즉시 다음 대화로 진행한다. default: wait type: object required: - name - input_schema - api_configuration title: CreateToolRequest description: 도구 생성 요청 (`POST /v3/tools`). ToolDetail: properties: id: type: string format: uuid title: Id description: 도구의 고유 식별자입니다. name: type: string maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ title: Name description: 도구 이름. description: anyOf: - type: string - type: 'null' title: Description description: 도구 설명입니다. 설정하지 않으면 null입니다. input_schema: additionalProperties: true type: object title: Input Schema description: 도구 입력 파라미터를 정의하는 JSON Schema 객체. api_configuration: $ref: '#/components/schemas/ToolApiConfigurationResponse' description: 외부 API 호출 설정. speak_during_execution: anyOf: - $ref: '#/components/schemas/SpeakDuringExecution' - type: 'null' description: 실행 중 TTS 메시지 설정. allow_interruption_during_execution: type: boolean title: Allow Interruption During Execution description: 도구 실행 중 사용자 발화로 인터럽트 허용 여부. response_mode: type: string enum: - wait - fire_and_forget title: Response Mode description: 응답 대기 모드. `fire_and_forget`은 결과 본문을 대화에 사용하지 않는다. default: wait created_at: type: integer title: Created At description: 리소스 생성 시각입니다. unix milliseconds 형식입니다. updated_at: type: integer title: Updated At description: 리소스 마지막 수정 시각입니다. unix milliseconds 형식입니다. type: object required: - id - name - input_schema - api_configuration - allow_interruption_during_execution - created_at - updated_at title: ToolDetail description: 도구 상세 조회/생성/수정 응답 스키마. ErrorResponse: type: object required: - error title: ErrorResponse description: 모든 실패 응답에서 사용하는 v3 error envelope입니다. examples: - error: code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: error: $ref: '#/components/schemas/ErrorDetail' description: 오류 payload입니다. ToolApiConfigurationWrite: properties: url: type: string format: uri title: Url description: 외부 API 엔드포인트 URL. method: type: string enum: - GET - POST - PUT - PATCH - DELETE title: Method description: HTTP 메서드. headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: 요청에 포함할 추가 헤더. key/value 모두 string. auth_type: anyOf: - type: string enum: - Basic - Bearer - type: 'null' title: Auth Type description: 인증 방식. null이면 미인증. auth_credentials: anyOf: - type: string - type: 'null' title: Auth Credentials description: 인증 자격증명. Basic은 `user:password`, Bearer는 토큰 문자열. timeout_seconds: anyOf: - type: integer maximum: 60 minimum: 1 - type: 'null' title: Timeout Seconds description: 요청 타임아웃입니다. 단위는 초입니다. 생략하거나 null로 보내면 서버가 기본값 10초를 적용합니다. type: object required: - url - method title: ToolApiConfigurationWrite description: >- 도구 생성/수정 시 클라이언트가 입력하는 외부 API 호출 설정입니다. `url`과 `method`는 필수입니다. `timeout_seconds`는 생략하거나 null로 보내면 서버 기본값 10초를 적용합니다. SpeakDuringExecution: properties: enabled: type: boolean title: Enabled description: 실행 중 TTS 메시지 재생 여부입니다. 기본값은 false입니다. default: false messages: items: type: string type: array title: Messages description: 재생할 TTS 메시지 목록입니다. `enabled=true`일 때만 의미가 있습니다. type: object title: SpeakDuringExecution description: 실행 중 사용자에게 재생할 TTS 메시지 설정. ToolApiConfigurationResponse: properties: url: type: string format: uri title: Url description: 외부 API 엔드포인트 URL. method: type: string enum: - GET - POST - PUT - PATCH - DELETE title: Method description: HTTP 메서드. headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: 요청 헤더입니다. 설정하지 않으면 null입니다. auth_type: anyOf: - type: string enum: - Basic - Bearer - type: 'null' title: Auth Type description: 인증 방식입니다. 설정하지 않으면 null입니다. has_auth_credentials: type: boolean title: Has Auth Credentials description: 인증 자격증명이 저장되어 있는지 여부입니다. 실제 값은 반환하지 않습니다. timeout_seconds: type: integer maximum: 60 minimum: 1 title: Timeout Seconds description: 요청 타임아웃입니다. 단위는 초입니다. 생성 시 생략했다면 기본값 10이 적용된 상태로 반환합니다. type: object required: - url - method - has_auth_credentials - timeout_seconds title: ToolApiConfigurationResponse description: |- 도구 상세 조회 시 반환하는 외부 API 호출 설정입니다. 민감 자격증명은 raw 값으로 반환하지 않고, `has_auth_credentials`로 존재 여부만 표시합니다. ErrorDetail: type: object required: - code - message - details title: ErrorDetail description: 기계가 읽을 수 있는 v3 오류 상세 정보입니다. examples: - code: VALIDATION_ERROR message: Request validation failed. details: field: name reason: must not be blank properties: code: type: string title: Code description: 기계가 읽을 수 있는 오류 code입니다. message parsing 대신 이 값을 사용합니다. examples: - VALIDATION_ERROR message: type: string title: Message description: 사용자에게 표시할 수 있는 오류 메시지입니다. 프로그램 처리는 `code`를 사용합니다. examples: - Request validation failed. details: type: object title: Details additionalProperties: true description: 구조화된 context입니다. 주로 `field`, `reason`, `allowed_values`를 포함합니다. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: Organization API key description: '조직 API 키를 `Authorization: Bearer ` 형식으로 보냅니다.' ````