agents_update
Update an existing AI agent's configuration.
All parameters are optional — only provided fields will be updated.
Use this to:
Enable or disable an agent
Change agent name or description
Assign or detach a prompt
Change default send mode
Replace knowledge collections
Update agent status
Change agent priority for trigger matching (lower number = higher priority)
Override which tools the agent can/can't call on triggered runs
Override which context sections (situation, communication style, job state, conversation history, thread summary) the agent receives
Opt into boilerplate prompt sections (safety guidelines, data confidentiality, factual accuracy) — all default OFF
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name for the agent | |
| model | No | Canonical source for which LLM the agent runs on. To switch models pass JUST this — do NOT also rewrite prompt_text (any 'duty model' section in the prompt is stale doc, not the config). OMIT to leave the model unchanged. | |
| script | No | rule_based deterministic action (no LLM): Python run in the workbench sandbox on each matched event. Reads `inputs` (raw_data, message_id, from_name, …) and calls the agent's integrations via call_tool('ext<id>_<name>', {..}). Dedupe writes on inputs['message_id'] (retries re-run). Pass null to clear (falls back to per-trigger template). | |
| status | No | Agent status: 'active', 'paused', or 'archived'. OMIT to leave the status unchanged. | |
| agent_id | Yes | ID of the agent to update | |
| priority | No | Agent priority for trigger matching. LOWER number = HIGHER priority (wins tiebreaks). Typical range 1-100. Fallback auto-reply agents use 10; specialised/topical agents use 100. When two agents match the same incoming message, the one with the lower priority number fires. | |
| prompt_id | No | Prompt ID to assign (null to detach) | |
| send_mode | No | Default send mode: 'auto' or 'draft'. OMIT to leave the send-mode unchanged. | |
| fast_model | No | Model for the fast-path responder (voice, text auto-reply, agent executor). Defaults to deepseek-v4-flash-nothink when unset. Non-Anthropic models (deepseek-v4-flash-nothink, gpt-4.1-nano, kimi-k2.6) do NOT use BYOK today — they use the system API key + credits. Pass null to revert to default. | |
| api_surface | No | OpenAI HTTPS endpoint for this agent's LLM calls (Phase 3a). 'chat_completions' (default, also when null) routes to /v1/chat/completions. 'responses' routes to /v1/responses — required for OpenAI native server tools (web_search, code_interpreter, image_generation, input_file PDFs). Capability still wins: agents whose tool list triggers the server_tool_responses_api substitution always route to Responses regardless of this setting. Ignored on non-OpenAI models (Anthropic, DeepSeek, Moonshot). OMIT to leave the api_surface unchanged. | |
| description | No | New description for the agent | |
| prompt_text | No | DESTRUCTIVE — REPLACES the entire system prompt. Pass ONLY when the user explicitly asks to edit/rewrite the prompt. To READ the prompt use prompts.get. When updating other fields (model, name, …) OMIT this. To append, prompts.get first then concatenate. Pass null to revert to the linked template. | |
| remote_tool | No | Only for text_engine='external_agent': the workspace integration tool that starts the remote agent, e.g. 'ext42_run_routine' (list them with integrations.search_tools). On each trigger DialogBrain calls it once with the event, the agent's instructions and the ids to answer with; the remote agent replies through the DialogBrain MCP tools (messages.send, tasks.comment, agents.task_complete). The endpoint and its secret belong to the integration, not to the agent. | |
| text_engine | No | Text-execution engine: 'agentic', 'ai_assisted', 'rule_based', or 'claude_channels'. Replaces the legacy execution_mode field (20260523_002). Voice is now derived from triggers, not engine. OMIT to leave unchanged. | |
| voice_tools | No | The EXACT set of tool IDs exposed to the LIVE VOICE runner (dotted IDs, e.g. ['knowledge.query','messages.send','messages.read_history','agent.handoff','calls.end','calendar.check_availability','calendar.create_event','contacts.capture_lead']). SEPARATE from allowed_tools (which governs TEXT mode): a tool only reaches the voice LLM if listed here. When set this REPLACES the whole voice surface — include EVERY tool the voice agent needs (the small default set is NOT auto-added once any voice tool is set). Tools listed here are also added to the text allow-list if absent. Empty list [] = no voice tools. OMIT to leave the voice tool surface unchanged. | |
| denied_tools | No | Block-list of tool IDs the agent must not call on triggered runs. Applied after allowed_tools and default visibility. Empty list [] = clear the block-list. | |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. | |
| voice_engine | No | Voice execution engine: 'pipeline' (default — Deepgram/Gladia STT + LLM + TTS), 'openai_realtime' (OpenAI Realtime API v2v; requires the workspace to have a BYOK OpenAI key connected — the worker falls back to 'pipeline' and logs why if the key is missing), or 'gemini_realtime' (Gemini Live native-audio v2v; runs on the workspace owner's Gemini key, else on the platform key unless platform keys are switched off). If the chosen realtime engine has no usable key, the result carries `warnings` and calls use the default pipeline. OMIT to leave unchanged. | |
| allowed_tools | No | Explicit allow-list of tool IDs this agent can call on triggered TEXT runs (e.g. ['messages.send', 'agent.handoff']). REPLACES the current text list: only these tools (minus denied_tools) are exposed to text runs. Empty list [] = no tools for text runs (there is no fallback set). Omit to leave the list unchanged. Tools already on the agent keep their current text/voice settings; only NEWLY named tools are switched on for text. So re-sending the current list plus one name adds exactly that one tool, and a tool that is currently call-only stays call-only (switch it on for text in the Tools tab, or remove it with voice_tools and name it again). Call tools are not removed by omitting them here — without voice_tools, the call surface is kept as it is; use voice_tools to change it. Does NOT affect the My AI dropdown path. | |
| resume_policy | No | When a human-paused thread hands control back to the agent: 'manual' (stays paused until an operator resumes it from the thread header), 'next_incoming_from_guest' (default — resumes on the contact's very next message), or 'after_<N>_hours' (e.g. 'after_2_hours'). With 'next_incoming_from_guest' a manual takeover lasts exactly one message; pick 'manual' when a person is expected to finish the conversation. OMIT to leave unchanged. | |
| voice_denoise | No | Server-side noise suppression (DeepFilterNet) on the INBOUND caller audio before STT — cleans background noise so the agent hears callers in loud/public places and gets fewer false barge-ins. Channel-agnostic: applies to every voice channel the agent answers on. Default false (unset). OMIT to leave unchanged. | |
| max_iterations | No | Hard cap on agentic-loop turns (LLM round-trips) per run, 1-50 (default 10). Each turn can call tools; the loop stops when the model replies with no tool call OR this cap is hit. Raise it for multi-step tool chains (e.g. browser automation: open → snapshot → fill → confirm → reply) that otherwise exhaust their turns before producing a final answer. OMIT to leave it unchanged. | |
| vision_enabled | No | Per-agent opt-in for vision content. When true, the executor splices recent image attachments from the active thread into the LLM call (Phase 3a continuous vision for Meet bot screen-share, plus any future channel that uploads images). Requires the agent's model to support vision (model_has_vision check). Default false; new calls pay zero token cost until the operator opts in. OMIT to leave the vision flag unchanged. | |
| voice_greeting | No | Opening line the agent speaks when the call connects. Pass an empty string "" to clear. Omit or null leaves unchanged. | |
| voice_stt_model | No | Speech-to-text model (Deepgram provider only): 'flux' (alias for flux-general-en), 'flux-general-en' (English Flux, LLM-powered end-of-turn), 'flux-general-multi' (multilingual Flux), or 'nova-3' (silence-based fallback). Flux variants are more responsive; nova-3 is the fallback when your Deepgram plan lacks Flux. Ignored when voice_stt_provider='gladia' (Gladia has a single model). OMIT to leave the STT model unchanged. | |
| voice_tts_speed | No | TTS playback speed multiplier (0.5-2.0, default 1.0). Yandex/OpenAI/Cartesia only — ignored for Deepgram. | |
| voice_tts_voice | No | TTS voice id — provider-specific (e.g. 'aura-2-thalia-en' for Deepgram, 'alloy' for OpenAI, 'alena' for Yandex, Cartesia voice UUID). Pass null to revert to provider default. | |
| auto_reply_rules | No | Plain-English rules injected into the fast model's system prompt as a `## Rules` block. No reserved keywords — the fast model reads them as guidance and decides per turn whether to reply directly or escalate to the main model for tools. Example: '- If the user greets, reply "Hi! How can I help?"\n- If the user asks what you can do, reply with a 1-sentence summary\n- If the question needs live data (prices, stock, booking), escalate' Engagement filtering (SKIP) belongs in trigger `conditions` (keywords, ai_filters, channel_types, cooldown), NOT here — if a message should be ignored the trigger shouldn't have fired. Pass null to clear. | |
| debounce_seconds | No | Seconds to wait after the last inbound message before generating, so rapid-fire messages coalesce into one reply (0-120, default 5). OMIT to leave unchanged. | |
| voice_max_tokens | No | Max TTS tokens per voice reply (40-200, default 100). Lower = snappier, higher = more detail. Controls speech brevity only: when the agent has voice tools, the runtime floors the underlying LLM completion cap at 400 so tool-call JSON always fits. | |
| include_job_state | No | Include current job state (active job context, tasks, notes) in the agent's prompt. OMIT to leave this flag unchanged. | |
| include_situation | No | Include situation context (channel, sender info, trigger type) in the agent's prompt. OMIT to leave this flag unchanged. | |
| native_web_search | No | Whether this agent may use the model provider's built-in web search (Anthropic, OpenAI) instead of the platform's web.search tool. Default true. Set false when the agent needs to filter results by publication date, use the workspace's own Serper key, or control the query — the built-in search offers none of those. No effect on providers without a built-in search (DeepSeek, Qwen). OMIT to leave unchanged. | |
| voice_mip_opt_out | No | Opt out of Deepgram's model-improvement program (privacy) for Flux STT. Default false. OMIT to leave unchanged. | |
| voice_speak_first | No | Who speaks first when a call connects. true (default): the agent says its greeting right away. false: the agent listens first and answers what the other person says; it greets only if they are silent for ~2 s. Use false for outbound calls where the person answering introduces themselves first. OMIT to leave unchanged. | |
| voice_record_calls | No | Record voice calls handled by this agent (stereo audio: caller and agent on separate channels), stored with the call for later playback. Default false. Ensure callers are informed of recording where consent rules apply. OMIT to leave this flag unchanged. | |
| voice_stt_keyterms | No | Domain-vocab bias for STT — names, product SKUs, etc. Passed verbatim as repeated `&keyterm=<w>` query params. Works on both Nova-3 and Flux. Prefer short phrases over full sentences. Empty list [] = no bias. Omit leaves unchanged. | |
| voice_stt_language | No | STT language code, validated against the SELECTED voice_stt_provider. 'multi' (default) enables autodetect / code-switching on either provider; a singleton like 'en', 'ru', 'uz' gives higher accuracy when the caller language is known. Deepgram provider: 'en' runs on Flux (fastest, eager end-of-turn); 'multi' and every other language run on Nova-3. Some languages — notably Thai ('th'), Vietnamese ('vi'), Indonesian ('id'), Tagalog ('tl') — are NOT in Nova-3's 'multi' auto-detect set, so those callers MUST be given an explicit code. Gladia provider: use its codes (e.g. 'uz' Uzbek, 'kk' Kazakh, 'az' Azerbaijani, 'tg' Tajik) — these are NOT valid under Deepgram. The enum below lists the union of both providers' codes; a code invalid for the chosen provider is rejected on save. OMIT to leave the STT language unchanged. | |
| voice_stt_provider | No | Speech-to-text provider. 'deepgram' (default) runs Nova-3 / Flux and preserves existing behaviour. 'gladia' routes to Gladia streaming STT (solaria-1), which is Deepgram-class latency and covers ~115 languages Deepgram does NOT — including Uzbek ('uz'), Kazakh ('kk'), Azerbaijani ('az'), Tajik ('tg'). Pick 'gladia' when the caller's language is outside Deepgram's coverage, then set voice_stt_language to that language's code. The provider also decides which language codes voice_stt_language accepts. OMIT to leave the STT provider unchanged. | |
| voice_tts_language | No | TTS language code, BCP-47 lite e.g. 'en', 'es', 'pt-BR' (Cartesia only, default 'en'). | |
| voice_tts_provider | No | Text-to-speech provider: 'deepgram' (default, Aura-2 EN-only), 'openai' (multilingual), 'cartesia' (Sonic-3, ultra-low TTFB, multilingual), 'alibaba' (CosyVoice v3-flash, multilingual, ~95ms TTFB), 'yandex' (best Russian), 'qwen' (Qwen3-TTS, self-hosted), or 'xai' (Grok, ~20 langs). OMIT to leave the TTS provider unchanged. | |
| default_calendar_id | No | Default Google calendar_id applied at the TOOL layer whenever this agent calls a calendar tool without an explicit calendar_id (e.g. 'c_...@group.calendar.google.com'). Use for agents whose bookings must always land on one dedicated calendar — a prompt-only rule is advisory and the model occasionally drops the param. An explicit calendar_id in a tool call still wins. Pass an empty string to clear (falls back to 'primary'). OMIT to leave unchanged. | |
| include_specialists | No | Inject a [SPECIALISTS] block (~50–200 tokens) listing the workspace's delegation-capable agents so a router-style agent can pick a handoff target without first calling agents.list. Default OFF for new agents; the Router template ships with this ON. Agentic mode only. OMIT to leave this flag unchanged. | |
| output_text_filters | No | Deterministic post-processing of the user-facing text an AGENTIC run produces (messages.send text + auto-delivered final answer; drafts inherit; ai_assisted fast-path replies and messages.edit are NOT covered). List of {pattern, replacement} regex rules applied in order. Example — strip AI-tell em dashes while keeping '—————' separator runs and never gluing lines: [{"pattern": "[ \\t]*(?<![—–])[—–](?![—–])[ \\t]*", "replacement": ", "}] (use [ \\t], not \\s — \\s matches newlines). Use for style rules the LLM won't reliably follow via prompt. Patterns are validated (invalid regex rejects the update). Max 20 rules. Empty list [] = clear all filters. OMIT to leave unchanged. | |
| voice_call_analysis | No | Run a post-call LLM analysis after each answered call: summary, success verdict with reason, and a 1-10 quality score, stored on the voice session and returned by calls.get_transcript metadata. Default false (costs one LLM call per call). OMIT to leave unchanged. | |
| voice_primary_model | No | Primary LLM for voice turns (e.g. 'gpt-4.1-mini', 'claude-haiku-4-5-20251001'). Pass null to revert to default. | |
| voice_turn_detector | No | Voice end-of-turn detector: 'vad' (default — sharp, low-latency) or 'multilingual' (semantic model, ~1s slower per turn, fewer mid-pause cuts). OMIT to leave unchanged. | |
| fast_prompt_override | No | Full fast-path prompt override. Placeholders substituted via .replace(): {message}, {history}, {rules}, {tools}, {output_contract}. agent.prompt_text is NOT injected into fast_prompt_override — include it yourself if you want it. Pass null to clear. | |
| pause_on_human_reply | No | Pause the agent on a thread the moment a human operator replies there. Default true. OMIT to leave unchanged. | |
| voice_filler_enabled | No | Emit 'thinking' filler audio while tools run so the caller hears life on the line (default true). OMIT to leave this flag unchanged. | |
| voice_max_tool_calls | No | Max tool calls per voice turn (1-10, default 3). OMIT to leave unchanged. | |
| voice_output_gain_db | No | Output attenuation in dB applied to the agent's WhatsApp call audio before the codec (-12.0 to 0.0, default 0 = unchanged). Use a negative value (e.g. -3.5) when a hot voice engine (OpenAI Realtime rides near 0 dBFS) causes blown-speaker distortion on loud words: the 24 kbps call codec needs headroom, and this restores it. Applied on the next call, no deploy needed. | |
| voice_realtime_model | No | Realtime (v2v) model for the agent's voice_engine. openai_realtime: 'gpt-realtime' (~18c/min on short calls) or 'gpt-realtime-mini' (~75% cheaper). gemini_realtime: a Gemini Live model, newest first 'gemini-3.8-live', 'gemini-3.1-flash-live-preview', 'gemini-2.5-flash-native-audio-latest', 'gemini-2.5-flash-native-audio-preview-12-2025' (today's default). 'default' = back to the engine's default. OMIT to leave unchanged. | |
| voice_thinking_texts | No | Pool of phrases spoken while the agent sets up the turn before calling the LLM (e.g. ['Hmm', 'So', 'One sec']). Pre-rendered to PCM at call start; one is picked at random per turn so the agent doesn't repeat the same word. Pass [] to clear. Omit or null leaves unchanged. | |
| include_learned_style | No | Include learned communication style (per-contact tone, dormancy state) in the agent's prompt. OMIT to leave this flag unchanged. | |
| voice_record_announce | No | On recorded calls, prepend a short 'this call may be recorded' notice to the agent's greeting. Only takes effect when voice_record_calls is enabled. Default false. OMIT to leave unchanged. | |
| voice_v2v_transcripts | No | Enable live transcripts for voice-to-voice engines (default true). OMIT to leave unchanged. | |
| include_thread_summary | No | Include condensed summary of older thread messages in the agent's prompt. OMIT to leave this flag unchanged. | |
| voice_endpointing_mode | No | LiveKit endpointing mode. 'fixed' (default) waits voice_endpointing_min_delay every turn; 'dynamic' adapts the wait from the conversation's own rhythm. OMIT to leave unchanged. | |
| voice_hold_ready_reply | No | Keep a finished reply the caller talked over (before any audio played) and speak it at the next pause, then answer what was said since. Without it (the default) stock LiveKit behaviour applies: that reply is discarded and regenerated from scratch. Default false. OMIT to leave unchanged. | |
| voice_transfer_numbers | No | Phone numbers (E.164, e.g. '+15551234567') the agent may cold-transfer a live call to ('let me put you through to a manager'). Any destination not on this list is refused; an empty list [] means the agent cannot transfer at all. Omit leaves unchanged. | |
| include_factual_accuracy | No | Inject the Factual Accuracy block (~100 tokens, generic anti-hallucination rules) into the system prompt. Default OFF — skip if you write domain-specific accuracy rules in Instructions. Agentic mode only. OMIT to leave this flag unchanged. | |
| knowledge_collection_ids | No | Replace all knowledge collections with these IDs (empty list = clear all) | |
| voice_flux_eot_threshold | No | Flux STT end-of-turn confidence threshold (0.1-1.0). Higher = wait for more certainty before finalizing the turn. Flux STT only (ignored on nova-3). OMIT to keep the worker default (0.7). | |
| voice_greeting_prerender | No | Gemini realtime agents only: synthesize the greeting in the agent's own voice while the phone is ringing, so it plays the instant the call is answered — word for word, no model start-up delay. Default false. OMIT to leave unchanged. | |
| voice_greeting_returning | No | Greeting variant for RETURNING callers (thread has prior history or a resolved name). Supports '{name}' — replaced with the caller's name when known, stripped when not. Pass an empty string "" to clear (always use voice_greeting). Omit or null leaves unchanged. | |
| voice_silence_reprompt_s | No | Seconds of silence from BOTH sides after which the agent briefly checks that the other person can still hear it (at most twice per call; never while the phone is still ringing). 0 = off (default). Typical 3-5 for outbound calls. OMIT to leave unchanged. | |
| include_safety_guidelines | No | Inject the generic Safety Guidelines block (~80 tokens) into the system prompt. Default OFF — enable only if you don't already write safety rules in your Instructions. Agentic mode only. OMIT to leave this flag unchanged. | |
| include_tool_call_history | No | Include the agent's own tool calls and results from the last 3 runs on this thread, compacted to IDs + top hits (~200-1000 tokens). Lets the agent recall file IDs, search hits, and decisions it already made across turns. Default ON. Agentic mode only. OMIT to leave this flag unchanged. | |
| voice_filler_audio_preset | No | Which bundled clip plays as the 'thinking' filler while the agent is working (LLM + tool calls), used when voice_thinking_texts is empty. Requires voice_filler_enabled=true. Built-in presets: 'keyboard_typing' / 'keyboard_typing2' (keyboard-typing SFX — sounds like the agent is typing/looking something up), plus any bundled music preset. Pass '' to clear (fall back to spoken filler). An unknown value silently plays no filler. OMIT or null to leave unchanged. | |
| voice_flux_eot_timeout_ms | No | Flux end-of-turn hard timeout in ms (500-15000). Flux STT only. OMIT to keep the worker default (5000). | |
| voice_max_call_duration_s | No | Wall-clock cap for a voice call in seconds, clamped to 60-14400; the worker ends the call at it regardless of what the conversation is doing. OMIT to leave unchanged (default is no cap — a call ends when the conversation ends). To REMOVE an existing cap, clear the field in the agent's Voice settings UI (0 there = no limit). Two agents talking to each other are capped separately by calls.agent_duel's own max_duration_s. | |
| voice_endpointing_max_delay | No | LiveKit endpointing.max_delay (0.5-10.0s, default 3.0). Ceiling on how long the agent waits for a turn to end. voice_endpointing_min_delay is the floor after silence; this is what stops a thinking pause from holding the turn open, and it is the knob to raise when an agent talks over someone who pauses mid-thought. | |
| voice_endpointing_min_delay | No | Silence after end-of-utterance before agent replies (0.1-2.0s, default 0.3). Higher = fewer false interrupts; lower = snappier. | |
| voice_preemptive_generation | No | Speculatively start the LLM on STT partials so the agent begins responding before end-of-utterance. Matches LiveKit stock template. Default true. OMIT to leave this flag unchanged. | |
| include_conversation_history | No | Include recent messages from this thread (up to 20) in the agent's prompt. OMIT to leave this flag unchanged. | |
| include_data_confidentiality | No | Inject the Data Confidentiality block (~250 tokens, cross-contact PII isolation + prompt-injection defense) into the system prompt. Default OFF. Agentic mode only. OMIT to leave this flag unchanged. | |
| voice_greeting_interruptible | No | Allow the caller to barge in during the opener TTS. Default true (trial-friendly — long greetings can be interrupted). Set false on outbound-call agents whose configured opener would otherwise get preempted by the caller's 'Hello?' triggering an off-script auto-turn. OMIT to leave this flag unchanged. | |
| voice_group_interim_barge_in | No | GROUP/Meet barge-in: interrupt the agent AS SOON AS a participant starts speaking (on the interim transcript), instead of waiting for the finished utterance. Default true. Set true to make a presenter/group agent easy to interrupt mid-sentence (word-gated by voice_group_barge_in_min_words so ambient noise can't trip it); false = only a completed utterance interrupts. OMIT to leave unchanged. | |
| voice_flux_eager_eot_threshold | No | Flux eager end-of-turn threshold (0.1-1.0). Setting this ENABLES EagerEndOfTurn for faster turn-taking at the cost of +50-70% LLM calls. Flux STT only. OMIT to leave eager off. | |
| voice_group_barge_in_min_words | No | GROUP/Meet barge-in word gate (1-6, default 1): a participant line must have at least this many words to interrupt the agent. 1 = any word interrupts (most responsive); raise to ignore short cross-talk. OMIT to leave unchanged. | |
| voice_early_finalize_confidence | No | Flux early-finalize confidence (0.1-1.0, worker default 0.65). Lower = finalize sooner on trailing silence (snappier, small mid-word clip risk). Flux STT only. OMIT to leave unchanged. | |
| voice_group_barge_in_stop_words | No | GROUP/Meet barge-in stop-words: any of these words/phrases ALWAYS interrupts the agent, even below voice_group_barge_in_min_words (e.g. ['стоп','подожди','вопрос','stop','wait','question']). Empty list [] clears. OMIT to leave unchanged. | |
| voice_interruption_min_duration | No | Min caller speech duration to interrupt the agent (0.1-1.5s, default 0.25). Higher = ignore short fillers like 'uh-huh'. | |
| voice_group_barge_in_requires_address | No | GROUP/Meet barge-in: when true, only lines that ADDRESS the agent (by name/keyword) interrupt it — two humans talking to each other won't break the walk. Default false. OMIT to leave unchanged. |