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-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."
    },
    "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."
    },
    "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_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"
      ],
      "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. 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."
    },
    "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."
    },
    "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."
    },
    "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)"
    },
    "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_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_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'."
    }
  }
}

• Data resourceWhatsApp Business API

  Meta · messaging

  name mention0.60
• Data resourceTelegram Bot API

  Telegram · messaging

  name mention0.60

Parent server