--- title: "Update Agent" method: PATCH path: "/api/ai-agents/{agent_id}" tags: ["ai-agents", "ai-agents"] --- # Update Agent `PATCH /api/ai-agents/{agent_id}` ## Request - Base URL: `https://api.dialogbrain.com` (the document declares no server; this is the origin it was published from) - URL: `https://api.dialogbrain.com/api/ai-agents/{agent_id}` - Auth: none declared Update an AI Agent. Template fork-on-edit (spec §5.2): if the target is a workspace_id=0 system template, materialize a workspace fork first via fork_template, then redirect the rest of the handler to the new fork's id. ## Path parameters - `agent_id` integer, required ## Request body - AiAgentUpdate - `name` string, nullable - `slug` string, nullable - `avatar_url` string, nullable - `description` string, nullable - `text_engine` string, nullable - `role` RoleConfig - `title` string, nullable - `responsibilities` string[] - `kpis` string[] - `personality` string, nullable - `language` string, nullable - `prompt_id` integer, nullable - `prompt_text` string, nullable - `auto_reply_rules` string, nullable - `execution_config` ExecutionConfig - `default_send_mode` string - `max_iterations` integer - `model` string - `fast_model` string, nullable: Auto-reply trigger fast-path model override. NOT used by Agentic, AI-Assisted, or Voice modes — those use the primary agent model or voice_primary_model. None → deepseek-v4-flash-nothink. - `fast_prompt_override` string, nullable: Auto-reply trigger fast-path prompt override. NOT used by Agentic, AI-Assisted, or Voice modes. Placeholders substituted via .replace(): {message}, {history}, {rules}, {tools}, {output_contract}. - `remote_tool` string, nullable: external_agent engine: the workspace integration tool ('ext_') that starts the remote agent. The URL and the secret live in the integration, never here. MUST be declared (ExecutionConfig is extra=ignore) or it would be silently dropped. - `script` string, nullable: rule_based deterministic action: Python run in the workbench sandbox on each matched event, NO LLM. Reads `inputs` (raw_data, message_id, from_name, …) and calls the agent's connected integrations via call_tool('ext_', {..}). Dedupe writes on inputs['message_id'] (retries re-run). None → fall back to the per-trigger template. MUST be declared (ExecutionConfig is extra=ignore) or it would be silently dropped. - `rate_limits` object - `api_surface` string, nullable: OpenAI HTTPS endpoint selection (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). - `native_web_search` boolean: Use the model provider's built-in web search (Anthropic, OpenAI) in place of the platform's web.search tool. True is the default and what every agent got historically. Set False when the agent needs what only our tool provides: filtering results by publication date, the workspace's own Serper key, and control over the query. Ignored on providers with no built-in search (DeepSeek, Qwen), where our tool is always used. - `quiet_hours` object, nullable - `pause_on_human_reply` boolean - `resume_policy` string - `pause_duration_minutes` integer, nullable - `temperature` number - `max_tokens` integer - `preferred_length` string - `max_words` integer, nullable - `use_thread_summary` boolean - `debounce_seconds` integer - `job_ttl_hours` integer - `include_situation` boolean - `include_learned_style` boolean - `include_job_state` boolean - `include_conversation_history` boolean - `include_thread_summary` boolean - `include_tool_call_history` boolean - `include_safety_guidelines` boolean - `include_data_confidentiality` boolean - `include_factual_accuracy` boolean - `include_specialists` boolean - `voice_primary_model` string, nullable - `voice_max_tokens` integer - `voice_max_call_duration_s` integer - `voice_max_tool_calls` integer - `voice_filler_enabled` boolean - `voice_denoise` boolean - `voice_greeting_interruptible` boolean - `voice_speak_first` boolean - `voice_greeting_prerender` boolean - `voice_silence_reprompt_s` number - `voice_preemptive_generation` boolean - `voice_hold_ready_reply` boolean - `voice_record_calls` boolean - `voice_record_announce` boolean - `voice_call_analysis` boolean - `voice_thinking_texts` string[] - `voice_filler_audio_preset` string, nullable - `voice_filler_audio_file_id` integer, nullable - `voice_stt_model` 'nova-3' | 'flux' | 'flux-general-en' | 'flux-general-multi' - `voice_translation_stt_model` 'nova-3' | 'flux' | 'flux-general-en' | 'flux-general-multi' - `voice_stt_provider` string - `voice_stt_language` string - `voice_stt_keyterms` string[] - `voice_transfer_numbers` string[] - `voice_tts_provider` string - `voice_tts_voice` string, nullable - `voice_tts_language` string - `voice_tts_speed` number - `voice_endpointing_min_delay` number - `voice_endpointing_max_delay` number - `voice_endpointing_mode` 'fixed' | 'dynamic' - `voice_interruption_min_duration` number - `voice_turn_detector` 'vad' | 'multilingual' - `voice_flux_eot_threshold` number, nullable - `voice_flux_eager_eot_threshold` number, nullable - `voice_flux_eot_timeout_ms` integer, nullable - `voice_early_finalize_confidence` number, nullable - `voice_mip_opt_out` boolean - `voice_group_interject_aggressiveness` integer - `voice_group_interject_model` string, nullable - `voice_group_barge_in_min_words` integer - `voice_group_barge_in_requires_address` boolean - `voice_group_interim_barge_in` boolean - `voice_group_barge_in_stop_words` string[] - `voice_group_address_terms` string[] - `voice_greeting` string - `voice_greeting_returning` string - `voice_engine` 'pipeline' | 'openai_realtime' | 'gemini_realtime' - `voice_v2v_transcripts` boolean - `voice_realtime_model` string, nullable - `voice_realtime_voice` string, nullable - `tool_config` ToolConfig: Storage shape of the JSONB `ai_agents.tool_config` column. Post-migration 20260523_001: `allowed_tools` is `list[ToolEntry]`, NOT `list[str]`. Reading the JSONB blob as a raw dict and treating `allowed_tools` as strings will crash at runtime (set() on dicts, `"foo" in allowed_tools` always False, etc.). Always go through this model — `AgentRecord.tool_config: ToolConfig` everywhere. - `allowed_tools` ToolEntry[] - `name` string, required - `voice` boolean - `text` boolean - `voice_directions` string[], nullable - `denied_tools` string[] - `extra_tools` string[] - `allow_send_effects` boolean, nullable - `max_tool_calls` integer - `require_approval` string[] - `auto_approve_deletes` boolean - `allow_calendar` boolean - `allow_web_search` boolean - `allow_form_collection` boolean - `calendar_url` string, nullable - `website_url` string, nullable - `product_catalog_source_id` integer, nullable - `forms_endpoint` string, nullable - `knowledge_config` KnowledgeConfig - `collection_ids` integer[] - `scope_mode` string - `use_rag` boolean - `rag_score_threshold` number - `knowledge_mode` string - `pinned_files_only` boolean - `escalation_config` EscalationConfig - `contacts` EscalationContact[] - `contact_id` integer, nullable - `name` string, required - `channel_thread_id` string, nullable - `reason` string, nullable - `status` string, nullable - `priority` integer, nullable - `vision_enabled` boolean, nullable - `memory_enabled` boolean, nullable: Per-agent master switch for the self-learning memory system ([MEMORY] injection + agent-context writes). - `tasks_enabled` boolean, nullable: Per-agent gate for [ACTIVE TASKS] prompt injection (the tasks.* tools stay usable when off). - `memory_scope` string, nullable: Write-routing for agent-authored memory: 'agent' (private) | 'workspace' (shared). ## Response `200` Successful Response - unknown ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway.md) · [All operations](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/dialogbrain/apis/dialogbrain-v2-api-gateway/revisions/d84e7dc9977d?raw)