> ## Documentation Index > Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent > Creates a new voice AI agent. The `voice_id` must be a voice ID from the voice catalog (see `GET /agent/voices`). Agent names must be unique per partner. ## OpenAPI ````yaml /openapi.json post /agent openapi: 3.1.0 info: title: Vocobase Partner API version: '2.0' description: >- API for managing voice AI agents, documents, and calls on the Vocobase platform. servers: - url: https://api.vocobase.com/api/v2 description: Production security: - bearerAuth: [] tags: - name: Config description: >- Read and update partner configuration, webhook settings, and telephony credentials. - name: Agents description: Create, read, update, and delete voice AI agents. - name: Voices description: >- List voice tiers, available voices, and stream preview audio for agent configuration. - name: Documents description: Upload, manage, and delete knowledge base documents. - name: Agent Documents description: Link and unlink documents to agents for knowledge base integration. - name: Calls description: Initiate outbound calls and view call history. - name: Phone Numbers description: >- Import DIDs, assign agents for inbound routing, and re-sync carrier Application bindings. - name: Inbound Routing Policies description: >- Define pre-answer routing decisions for inbound calls before AI sessions are created. - name: Telephony Connections description: Create, list, rename, and disconnect named V2 telephony connections. - name: VoiceLink Management description: Manage VoiceLink reseller clients, DID mapping, and readiness sync. - name: Projects description: Organize agents into projects. Every agent belongs to exactly one project. - name: Dictionaries description: Speech-recognition dictionary CRUD and agent attachment. - name: Sessions description: Browser-initiated WebRTC voice sessions for in-app voice agents. paths: /agent: post: tags: - Agents summary: Create an agent description: >- Creates a new voice AI agent. The `voice_id` must be a voice ID from the voice catalog (see `GET /agent/voices`). Agent names must be unique per partner. operationId: createAgent requestBody: required: true content: application/json: schema: type: object required: - agent_name - prompt - voice_id - agent_type properties: agent_name: type: string maxLength: 50 description: Unique agent name. example: Sales Assistant prompt: type: string maxLength: 120000 description: System prompt defining the agent's personality and behavior. voice_id: type: string format: uuid description: >- Voice ID from the catalog returned by `GET /agent/voices`. The language and gender are taken from the selected voice. example: b49e0d0f-2219-4425-a765-1efd32beb509 agent_type: type: string enum: - inbound - outbound description: Whether the agent handles inbound or outbound calls. intro_message: type: - string - 'null' maxLength: 500 description: Optional greeting spoken when a call connects. voicemail_detection_enabled: type: boolean default: true description: >- Per-agent toggle for carrier-side voicemail detection on supported outbound providers. Account-level provider support must also be enabled. screener_handling_enabled: type: boolean default: false description: >- Per-agent toggle for phone screener handling on outbound calls. Requires `voicemail_detection_enabled` to be true and platform screener handling to be enabled. voicemail_message: type: - string - 'null' maxLength: 500 description: >- Optional message used after a supported carrier detects voicemail. Pass `null` or an empty string to clear. project_id: type: - string - 'null' format: uuid description: >- Assign the agent to a specific project. Defaults to the default project if omitted. enable_recording: type: boolean default: false description: Whether to record calls made with this agent. kb_threshold: type: - string - 'null' enum: - low - medium - high - null default: medium description: Knowledge base search relevance threshold. kb_include_summaries: type: boolean default: false description: Include document summaries in KB search results. kb_result_format: type: - string - 'null' maxLength: 2000 description: Custom format template for KB search results. kb_enable_llm_processing: type: boolean default: false description: Enable LLM post-processing of KB search results. kb_llm_system_prompt: type: - string - 'null' maxLength: 120000 description: System prompt for LLM KB processing. end_call_enabled: type: boolean default: true description: >- Master toggle for the end-call tool. When false, the agent cannot end calls on its own regardless of `end_call_instructions`. end_call_message: type: - string - 'null' maxLength: 500 description: >- Farewell line spoken before the bot hangs up. When null/empty, a platform default is used. end_call_instructions: type: - string - 'null' maxLength: 2000 description: >- Free-text natural-language instructions spliced into the system prompt under "When to end the call." Write your own conditions in plain English, e.g. "End the call when the caller says goodbye, has not spoken for an extended period, or asks to be removed from the list." When null/empty, the section is skipped entirely. Replaces the prior `end_call_triggers` enum array. transfer_enabled: type: boolean default: false description: >- Master toggle for cold-transfer-to-human. `transfer_number` is required when true. When the agent transfers a call, Vocobase connects the caller to `transfer_number`. The session.completed webhook includes transfer metadata — see `data.call.transferred`. transfer_number: type: - string - 'null' description: >- E.164 number to transfer the call to. Required when `transfer_enabled` is true. transfer_message: type: - string - 'null' maxLength: 500 description: >- Announcement spoken before the transfer. When null/empty, a platform default is used. transfer_instructions: type: - string - 'null' maxLength: 2000 description: >- Free-text natural-language instructions spliced into the system prompt under "When to transfer." Write your own conditions in plain English. When null/empty, the section is skipped. Replaces the prior `transfer_triggers` enum array. user_idle_enabled: type: boolean default: true description: >- Controls whether the agent responds to caller silence using platform-managed idle settings. Defaults to true. When false, the bot will not ask if the caller is still there and will not end the call because of idle silence. Timeout and retry values are not configurable through V2. tool_ack_config: oneOf: - type: 'null' - $ref: '#/components/schemas/ToolAckConfig' description: >- Per-agent spoken acknowledgement while a tool call (e.g. `search_knowledge_base`) runs. New agents default to enabled with `mode` set to `dynamic` when this field is omitted. Pass `null` to opt the new agent out, or an object to customize. extraction_enabled: type: boolean default: true description: >- Master switch for automatic post-call extraction. Defaults to true. When false, extraction is skipped after calls even if an `extraction_config` is later set (the config is preserved). The extraction schema itself is set via PUT /agent/{id} (`extraction_config`). max_call_duration_secs: type: - integer - 'null' minimum: 60 maximum: 3600 default: 600 description: >- Hard cap on call duration in seconds. New agents default to 600 (10 minutes); pass `null` to disable the cap. Range 60-3600. At `(cap - 30s)` the bot speaks a soft "wrapping up" warning; at the cap it speaks the agent's farewell and gracefully ends the session through the standard end-of-call path. background_audio_id: type: - string - 'null' format: uuid description: >- Reference to a `BackgroundAudio` asset (see `GET /agent/background-audio`) the bot will mix under its TTS for the duration of the call. background_audio_volume: type: - number - 'null' minimum: 0 maximum: 1 description: >- Mixing volume for `background_audio_id`. Range 0.0-1.0. When `null`, the bot applies a default of 0.3. responses: '201': description: Agent created successfully. content: application/json: schema: type: object properties: success: type: boolean const: true data: $ref: '#/components/schemas/Agent' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': description: Agent limit reached. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: LIMIT_REACHED message: Agent limit reached. Maximum 10 agents allowed. '409': description: Agent name already exists. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: CONFLICT message: An agent with this name already exists '500': $ref: '#/components/responses/InternalError' components: schemas: ToolAckConfig: type: object description: >- Per-agent spoken acknowledgement played when the agent starts an eligible tool call, to mask tool latency such as a knowledge-base lookup. Never fires for `end_call` or `transfer_call`. The object is forwarded to the voice engine as-is, so nested keys are camelCase. properties: enabled: type: boolean description: Turn the spoken acknowledgement on or off. mode: type: string enum: - static - dynamic description: >- `static` speaks a random built-in phrase (no added latency). `dynamic` has the LLM generate a short, context- and language-aware line each time (adds roughly 300-800 ms and one extra inference per tool call). maxWords: type: integer minimum: 1 maximum: 200 description: >- Dynamic mode only: soft word cap on the generated acknowledgement. Defaults to 10. Agent: type: object properties: id: type: string format: uuid agent_name: type: string prompt: type: string voice_id: type: - string - 'null' language: type: string agent_type: type: - string - 'null' enum: - inbound - outbound - null intro_message: type: - string - 'null' voicemail_detection_enabled: type: boolean description: >- Whether carrier-side voicemail detection is enabled for this agent on supported outbound providers. screener_handling_enabled: type: boolean description: >- Whether phone screener handling is enabled for this agent on outbound calls. voicemail_message: type: - string - 'null' maxLength: 500 description: >- Message used after a supported carrier detects voicemail. Max 500 characters. enable_recording: type: boolean kb_threshold: type: string enum: - low - medium - high kb_include_summaries: type: boolean kb_result_format: type: - string - 'null' kb_enable_llm_processing: type: boolean kb_llm_system_prompt: type: - string - 'null' variables: type: array items: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ description: >- Pre-call variable names referenced in the prompt or greeting as `{{name}}`. Empty array when none are defined. extraction_config: oneOf: - type: 'null' - $ref: '#/components/schemas/ExtractionConfig' description: >- Custom Analysis config — when present AND `extraction_enabled` is true, the platform runs an LLM extraction over each completed call's transcript and ships the result inline in the `session.completed` webhook. tool_ack_config: oneOf: - type: 'null' - $ref: '#/components/schemas/ToolAckConfig' description: >- Per-agent tool-call acknowledgement configuration, or `null` when the feature is off. See the ToolAckConfig schema. extraction_enabled: type: boolean default: true description: >- Master switch for automatic post-call extraction. When false, extraction is skipped after calls even if `extraction_config` is set (the config is preserved). Manual replay via `POST /calls/{call_id}/extract` still works. project_id: type: - string - 'null' format: uuid description: >- ID of the project this agent belongs to. Defaults to the default project if not specified. transfer_enabled: type: boolean description: Enable call transfer to a human agent. transfer_number: type: - string - 'null' description: >- E.164 phone number to transfer calls to. Required when `transfer_enabled` is true. transfer_message: type: - string - 'null' description: Announcement spoken before transferring. Max 500 characters. transfer_instructions: type: - string - 'null' description: >- Free-text natural-language instructions spliced into the system prompt under "When to transfer." Max 2000 characters. Replaces the prior `transferTriggers` enum array. end_call_enabled: type: boolean description: Enable the agent to end calls on its own. end_call_message: type: - string - 'null' description: Farewell message spoken before hanging up. Max 500 characters. end_call_instructions: type: - string - 'null' description: >- Free-text natural-language instructions spliced into the system prompt under "When to end the call." Max 2000 characters. Replaces the prior `endCallTriggers` enum array. user_idle_enabled: type: boolean default: true description: >- Whether the agent responds to caller silence using platform-managed idle settings. When false, the bot will not ask if the caller is still there and will not end the call due to idle silence. max_call_duration_secs: type: - integer - 'null' minimum: 60 maximum: 3600 default: 600 description: >- Hard cap on call duration in seconds. New agents default to 600 (10 minutes). Set to `null` to disable the cap. Range 60-3600. At `(cap - 30s)` the agent speaks a soft "wrapping up" warning; at the cap it speaks the agent's `end_call_message` (or a default farewell) and gracefully ends the session through the standard end-of-call path so transcript, recording, billing and the `session.completed` webhook all fire normally. background_audio_id: type: - string - 'null' format: uuid description: >- Reference to a `BackgroundAudio` asset (from `GET /agent/background-audio`) that the bot mixes under its TTS for the duration of the call. `null` (default) means no background audio. The asset must be visible to the partner — either a platform-curated asset (`is_platform: true`) or one the partner uploaded. background_audio_volume: type: - number - 'null' minimum: 0 maximum: 1 description: >- Mixing volume for `background_audio_id`. Range 0.0-1.0. When `null`, the bot applies a default of 0.3. document_count: type: integer description: Number of linked documents. status: type: string enum: - active - inactive created_at: type: string format: date-time updated_at: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean const: false error: type: object properties: code: type: string message: type: string required: - code - message required: - success - error ExtractionConfig: type: object description: >- Custom Analysis schema — defines what the post-call extraction LLM should pull from each completed call's transcript. required: - prompt - keys properties: prompt: type: string maxLength: 50000 description: >- Free-form analysis prompt. Describe the data you want extracted; reference the keys by name. keys: type: array maxItems: 50 items: type: object required: - name - type properties: name: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ type: type: string enum: - string - number - integer - boolean - array - date - datetime description: type: string maxLength: 500 includeToolLogs: type: boolean description: >- When true, the extraction LLM also sees the agent's tool calls + KB hits, not just the transcript. Useful for catching things like 'did the agent search for X' or 'what was the booking outcome'. default: false responses: ValidationError: description: Validation error in request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: VALIDATION_ERROR message: agent_name is required and must be max 50 characters Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: UNAUTHORIZED message: Invalid or missing API key InternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: INTERNAL_ERROR message: An unexpected error occurred securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key in format: `rg_live_xxxx`. Pass as a Bearer token in the Authorization header. ````