agents_update

Parameters schema

{
  "type": "object",
  "required": [
    "agent_id"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "New name for the agent"
    },
    "model": {
      "enum": [
        "deepseek-chat",
        "deepseek-reasoner",
        "gpt-4.1",
        "gpt-4.1-mini",
        "gpt-4.1-nano",
        "gpt-4o",
        "claude-haiku-4-5-20251001",
        "claude-sonnet-4-6",
        "claude-sonnet-5",
        "claude-opus-4-6",
        "kimi-k2.6"
      ],
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "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": {
      "enum": [
        "active",
        "paused",
        "archived"
      ],
      "type": "string",
      "description": "Agent status: 'active', 'paused', or 'archived'. OMIT to leave the status unchanged."
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to update"
    },
    "priority": {
      "type": "integer",
      "description": "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": {
      "type": "integer",
      "description": "Prompt ID to assign (null to detach)"
    },
    "send_mode": {
      "enum": [
        "auto",
        "draft"
      ],
      "type": "string",
      "description": "Default send mode: 'auto' or 'draft'. OMIT to leave the send-mode unchanged."
    },
    "fast_model": {
      "type": "string",
      "description": "Model for the fast-path responder (voice, text auto-reply, agent executor). Defaults to deepseek-chat when unset. Non-Anthropic models (deepseek-chat, 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": {
      "enum": [
        "chat_completions",
        "responses"
      ],
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "New description for the agent"
    },
    "prompt_text": {
      "type": "string",
      "description": "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."
    },
    "text_engine": {
      "enum": [
        "rule_based",
        "ai_assisted",
        "agentic",
        "claude_channels"
      ],
      "type": "string",
      "description": "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": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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."
    },
    "allowed_tools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Explicit allow-list of tool IDs this agent can call on triggered runs (e.g. ['messages.send', 'agent.handoff']). Empty list [] = clear the allow-list and fall back to system defaults. When set, only these tools (minus denied_tools) are exposed to the agent. Does NOT affect the My AI dropdown path."
    },
    "max_iterations": {
      "type": "integer",
      "maximum": 50,
      "minimum": 1,
      "description": "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": {
      "type": "boolean",
      "description": "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": {
      "type": "string",
      "description": "Opening line the agent speaks when the call connects. Pass an empty string \"\" to clear. Omit or null leaves unchanged."
    },
    "voice_stt_model": {
      "enum": [
        "flux",
        "flux-general-en",
        "flux-general-multi",
        "nova-3"
      ],
      "type": "string",
      "description": "Speech-to-text model: '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. OMIT to leave the STT model unchanged."
    },
    "voice_tts_speed": {
      "type": "number",
      "maximum": 2,
      "minimum": 0.5,
      "description": "TTS playback speed multiplier (0.5-2.0, default 1.0). Yandex/OpenAI/Cartesia only — ignored for Deepgram."
    },
    "voice_tts_voice": {
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "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'\nEngagement 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."
    },
    "voice_max_tokens": {
      "type": "integer",
      "maximum": 200,
      "minimum": 40,
      "description": "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": {
      "type": "boolean",
      "description": "Include current job state (active job context, tasks, notes) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_situation": {
      "type": "boolean",
      "description": "Include situation context (channel, sender info, trigger type) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "voice_mip_opt_out": {
      "type": "boolean",
      "description": "Opt out of Deepgram's model-improvement program (privacy) for Flux STT. Default false. OMIT to leave unchanged."
    },
    "voice_stt_keyterms": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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": {
      "enum": [
        "multi",
        "en",
        "ru",
        "es",
        "fr",
        "de",
        "pt",
        "it",
        "nl",
        "hi",
        "ja",
        "ko",
        "zh",
        "th",
        "vi",
        "id",
        "ms",
        "tl",
        "ar",
        "tr",
        "uk",
        "pl"
      ],
      "type": "string",
      "description": "STT language hint. 'multi' (default) enables code-switching; singletons like 'en', 'ru', 'es' give higher accuracy when the caller language is known. Use 'multi' for bilingual callers. IMPORTANT: 'en' runs on Flux (fastest, eager end-of-turn); 'multi' and every other language run on Nova-3 (slightly slower, no eager EOT). Some languages — notably Thai ('th'), Vietnamese ('vi'), Indonesian ('id'), Tagalog ('tl') — are NOT in Nova-3's 'multi' auto-detect set, so a Thai/Vietnamese/etc. caller MUST be given the explicit language code here (e.g. 'th') or transcription is garbage. OMIT to leave the STT language unchanged."
    },
    "voice_tts_language": {
      "type": "string",
      "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
      "description": "TTS language code, BCP-47 lite e.g. 'en', 'es', 'pt-BR' (Cartesia only, default 'en')."
    },
    "voice_tts_provider": {
      "enum": [
        "alibaba",
        "cartesia",
        "deepgram",
        "openai",
        "qwen",
        "xai",
        "yandex"
      ],
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "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": {
      "type": "boolean",
      "description": "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": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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_primary_model": {
      "type": "string",
      "description": "Primary LLM for voice turns (e.g. 'gpt-4.1-mini', 'claude-haiku-4-5-20251001'). gpt-4.1-nano is too weak for reliable turn tracking; mini is the recommended floor. Pass null to revert to default."
    },
    "voice_turn_detector": {
      "enum": [
        "vad",
        "multilingual"
      ],
      "type": "string",
      "description": "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": {
      "type": "string",
      "description": "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."
    },
    "voice_filler_enabled": {
      "type": "boolean",
      "description": "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": {
      "type": "integer",
      "maximum": 10,
      "minimum": 1,
      "description": "Max tool calls per voice turn (1-10, default 3). OMIT to leave unchanged."
    },
    "voice_thinking_texts": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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": {
      "type": "boolean",
      "description": "Include learned communication style (per-contact tone, dormancy state) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_thread_summary": {
      "type": "boolean",
      "description": "Include condensed summary of older thread messages in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_factual_accuracy": {
      "type": "boolean",
      "description": "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": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Replace all knowledge collections with these IDs (empty list = clear all)"
    },
    "voice_flux_eot_threshold": {
      "type": "number",
      "maximum": 1,
      "minimum": 0.1,
      "description": "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_returning": {
      "type": "string",
      "description": "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."
    },
    "include_safety_guidelines": {
      "type": "boolean",
      "description": "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": {
      "type": "boolean",
      "description": "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": {
      "type": "string",
      "description": "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": {
      "type": "integer",
      "maximum": 15000,
      "minimum": 500,
      "description": "Flux end-of-turn hard timeout in ms (500-15000). Flux STT only. OMIT to keep the worker default (5000)."
    },
    "voice_endpointing_min_delay": {
      "type": "number",
      "maximum": 2,
      "minimum": 0.1,
      "description": "Silence after end-of-utterance before agent replies (0.1-2.0s, default 0.3). Higher = fewer false interrupts; lower = snappier."
    },
    "voice_preemptive_generation": {
      "type": "boolean",
      "description": "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": {
      "type": "boolean",
      "description": "Include recent messages from this thread (up to 20) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_data_confidentiality": {
      "type": "boolean",
      "description": "Inject the Data Confidentiality block (~250 tokens, cross-contact PII isolation + prompt-injection defense) into the system prompt. Recommended for multi-tenant workspaces. Default OFF. Agentic mode only. OMIT to leave this flag unchanged."
    },
    "voice_greeting_interruptible": {
      "type": "boolean",
      "description": "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": {
      "type": "boolean",
      "description": "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": {
      "type": "number",
      "maximum": 1,
      "minimum": 0.1,
      "description": "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": {
      "type": "integer",
      "maximum": 6,
      "minimum": 1,
      "description": "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": {
      "type": "number",
      "maximum": 1,
      "minimum": 0.1,
      "description": "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": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "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": {
      "type": "number",
      "maximum": 1.5,
      "minimum": 0.1,
      "description": "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": {
      "type": "boolean",
      "description": "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."
    }
  }
}

No endpoints wrapped at confidence ≥ 0.70.

Parent server