> ## 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. # Update an agent > Updates one or more agent fields. Only provided fields are changed. At least one field must be provided. ## OpenAPI ````yaml /openapi.json put /agent/{id} 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/{id}: put: tags: - Agents summary: Update an agent description: >- Updates one or more agent fields. Only provided fields are changed. At least one field must be provided. operationId: updateAgent parameters: - name: id in: path required: true schema: type: string format: uuid description: Agent ID. requestBody: required: true content: application/json: schema: type: object properties: agent_name: type: string maxLength: 50 description: New agent name. prompt: type: string maxLength: 120000 description: New system prompt. voice_id: type: string format: uuid description: >- New voice ID from the catalog returned by `GET /agent/voices`. Updates language and gender to match the selected voice. agent_type: type: string enum: - inbound - outbound intro_message: type: - string - 'null' maxLength: 500 description: New greeting message. Pass `null` or empty string to remove. voicemail_detection_enabled: type: boolean description: >- Toggle carrier-side voicemail detection for this agent on supported outbound providers. screener_handling_enabled: type: boolean description: >- Toggle phone screener handling for this agent 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: >- Update the message used after a supported carrier detects voicemail. Pass `null` or an empty string to clear. project_id: type: - string - 'null' format: uuid description: Move the agent to a different project. enable_recording: type: boolean kb_threshold: type: - string - 'null' enum: - low - medium - high - null description: Pass `null` to reset to default (medium). kb_include_summaries: type: boolean kb_result_format: type: - string - 'null' maxLength: 2000 kb_enable_llm_processing: type: boolean kb_llm_system_prompt: type: - string - 'null' maxLength: 120000 variables: type: - array - 'null' items: type: string pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ maxItems: 100 description: >- List of pre-call variable names referenced in the prompt or greeting as `{{name}}`. Per-call values are supplied via the `variables` body field on `POST /calls/start`. Pass `null` to clear. extraction_config: oneOf: - type: 'null' - $ref: '#/components/schemas/ExtractionConfig' description: >- Custom Analysis config — runs an LLM extraction over the transcript after every completed call. Pass `null` to remove the config entirely. To pause extraction while keeping the config, use `extraction_enabled: false` instead. tool_ack_config: oneOf: - type: 'null' - $ref: '#/components/schemas/ToolAckConfig' description: >- Per-agent spoken acknowledgement while a tool call runs. Omit to leave the current setting unchanged; pass `null` to disable, or an object to update. No default is applied on update (unlike create). extraction_enabled: type: boolean description: >- Master switch for AUTOMATIC post-call extraction. Defaults to true. When false, extraction is skipped after calls even if `extraction_config` is set — the config is preserved, not deleted. Manual replay (`POST /calls/{call_id}/extract`) ignores this flag and runs as long as a config exists. end_call_enabled: type: boolean description: Toggle the agent's ability to end the call autonomously. end_call_message: type: - string - 'null' maxLength: 500 description: >- New farewell line. Pass `null` or empty string to fall back to the platform default. end_call_instructions: type: - string - 'null' maxLength: 2000 description: >- Replace the free-text end-call instructions. Pass `null` or empty string to clear the section (the agent can still end calls via prompt logic if `end_call_enabled` is true). Replaces the prior `end_call_triggers` enum array. transfer_enabled: type: boolean description: >- Toggle cold transfer. When false, transfer settings are cleared. transfer_number: type: - string - 'null' description: >- E.164 destination number. Required when `transfer_enabled` is true. transfer_message: type: - string - 'null' maxLength: 500 description: >- New announcement spoken before transferring. Pass `null` or empty string for the platform default. transfer_instructions: type: - string - 'null' maxLength: 2000 description: >- Replace the free-text transfer instructions. Pass `null` or empty string to clear the section. Replaces the prior `transfer_triggers` enum array. user_idle_enabled: type: boolean description: >- Toggle caller-silence follow-up for this agent. Defaults to true on new agents. Set false to prevent the bot from asking if the caller is still there or ending the call due to idle silence. Timeout and retry values remain platform-managed. max_call_duration_secs: type: - integer - 'null' minimum: 60 maximum: 3600 description: >- Update the hard call-duration cap. Range 60-3600. Pass `null` to remove the cap. New agents default to 600 (10 minutes); existing agents created before the default landed may currently hold `null`. background_audio_id: type: - string - 'null' format: uuid description: >- Set or change the background-audio asset. Pass `null` to remove background audio. background_audio_volume: type: - number - 'null' minimum: 0 maximum: 1 description: >- Mixing volume override for `background_audio_id`. Range 0.0-1.0. Pass `null` to use the default (0.3). minProperties: 1 responses: '200': description: Agent updated. 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' '404': $ref: '#/components/responses/NotFound' '409': description: Agent name conflict. 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: 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 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 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 NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: code: NOT_FOUND message: Resource not found 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. ````