---
title: "部分更新智能体"
method: PATCH
path: "/agents/{id}"
tags: ["智能体"]
---

# 部分更新智能体

`PATCH /agents/{id}`

## Request

- Base URL: `/api/v1` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/v1/agents/{id}`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `X-API-Key`

只修改请求中出现的字段，其余配置保持不变。
支持名称、描述、运行模式、系统提示词、对话模型、知识库、MCP、技能范围、联网搜索、多轮对话。
agent_mode 取 quick-answer 或 smart-reasoning。MCP 与技能只在 smart-reasoning 下运行，切到该模式会打开多轮对话。
传 knowledge_bases、mcp_services 或 selected_skills 而不传对应模式时，切换为 selected。
技能模式 all/none 清空技能列表；启用技能须先在编辑器选择沙箱，selected 名称须可用，否则返回 400。

## Path parameters

- `id` string, required

## Request body

- InternalHandlerPatchAgentRequest
  - `agent_mode` 'quick-answer' | 'smart-reasoning': Running mode: quick-answer is RAG; smart-reasoning calls tools, MCP and skills
  - `description` string: What the agent is for
  - `kb_selection_mode` 'all' | 'selected' | 'none': Knowledge bases searched: all, selected (knowledge_bases) or none
  - `knowledge_bases` string[]: Selected knowledge bases, replacing the current ones; without kb_selection_mode it also switches the mode to selected
  - `mcp_selection_mode` 'all' | 'selected' | 'none': MCP services used: all, selected (mcp_services) or none
  - `mcp_services` string[]: Selected MCP services, replacing the current ones; without mcp_selection_mode it also switches the mode to selected
  - `model_id` string: Chat model the agent answers with
  - `multi_turn_enabled` boolean: Whether earlier turns are kept in the conversation context
  - `name` string: Agent name
  - `selected_skills` string[]: Selected skill names, replacing the current ones; without skills_selection_mode it also switches the mode to selected
  - `skills_selection_mode` 'all' | 'selected' | 'none': Skills used: all, selected (selected_skills) or none
  - `system_prompt` string: The whole system prompt
  - `web_search_enabled` boolean: Whether the agent may search the web
  - `web_search_provider_id` string: Empty follows the workspace default; changing the provider does not enable search.

## Response `200`

更新后的智能体

- InternalHandlerAgentWriteResponse
  - `allowed_tools_warnings` InternalHandlerAllowedToolsWarningsDoc
    - `dropped` string[]
    - `kept_unknown` string[]
  - `data` GithubComTencentWeKnoraInternalTypesCustomAgent
    - `avatar` string: Avatar/Icon of the agent (emoji or icon name)
    - `config` GithubComTencentWeKnoraInternalTypesCustomAgentConfig
      - `access_level` 'read_only' | 'confirm' | 'auto_write'
      - `agent_mode` string: ===== Basic Settings ===== Agent mode: "quick-answer" for RAG mode, "smart-reasoning" for ReAct agent mode
      - `agent_type` string: AgentType is a preset category under smart-reasoning mode that pre-fills system prompt, allowed tools and recommended KB compatibility. Valid values: "rag-qa", "wiki-qa", "hybrid-rag-wiki", "custom". Empty / unknown values are treated as "custom" (no preset applied). Ignored for quick-answer mode.
      - `allowed_tools` string[]: Allowed tools (only for agent type)
      - `asr_model_id` string: ASR model ID for audio transcription (optional)
      - `attachment_image_understanding` boolean: AttachmentImageUnderstanding enables VLM OCR fallback for image-only / scanned documents (PDF/PPT whose pages are images). Disabled by default because it materially increases parse latency; only triggers when the extracted text is below a threshold and a VLM model is configured.
      - `attachment_ocr_max_pages` integer: AttachmentOCRMaxPages caps how many pages of a scanned / image-only document this agent sends to the VLM for OCR. 0 falls back to the global default (WEKNORA_CHAT_ATTACHMENT_OCR_MAX_PAGES). More pages means higher coverage but slower parsing and more VLM cost.
      - `attachment_parse_wait_timeout_sec` integer: AttachmentParseWaitTimeoutSec bounds, in seconds, how long a chat turn waits for this agent's still-parsing attachments before proceeding with only the finished ones. 0 falls back to the global default (WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC).
      - `audio_upload_enabled` boolean: Whether audio upload (ASR transcription) is enabled for this agent (default: false)
      - `chat_parser_engine_rules` GithubComTencentWeKnoraInternalTypesParserEngineRule[]: ===== Chat Attachment Parsing Settings ===== ChatParserEngineRules selects parser engines for session-scoped chat attachments by file type. Takes precedence over the tenant-level ParserEngineConfig.ChatParserEngineRules; an explicit per-request parser_engine still overrides both.
        - `engine` string
        - `file_types` string[]
        - `xlsx_first_row_as_header` boolean: XLSXFirstRowAsHeader restores row-1 column context for flat XLSX tables. nil preserves the parser default; an explicit false disables the mode.
      - `citation_enabled` boolean: Whether final answers include knowledge/web source citations. Nil defaults to true so agents saved before this option was introduced keep their existing behavior.
      - `context_template` string: Context template for normal mode (how to format retrieved chunks)
      - `context_template_id` string: ContextTemplateID references a template ID in prompt_templates/ YAML files. If set and ContextTemplate is empty, the template content is resolved at request time for saved agents.
      - `data_analysis_enabled` boolean: ===== Data Analysis Settings ===== Whether to run the legacy in-pipeline DuckDB SQL data-analysis stage when the retrieved chunks include CSV/Excel files. This issues an extra LLM call to generate a SQL query and is disabled by default because most quick-answer / RAG-style agents do not want the added latency.
      - `embedding_top_k` integer: ===== Retrieval Strategy Settings (for both modes) ===== Embedding/Vector retrieval top K
      - `enable_query_expansion` boolean: ===== Advanced Settings (mainly for normal mode) ===== Whether to enable query expansion
      - `enable_rewrite` boolean: Whether to enable query rewrite for multi-turn conversations
      - `fallback_prompt` string: Fallback prompt (when FallbackStrategy is "model")
      - `fallback_response` string: Fixed fallback response (when FallbackStrategy is "fixed")
      - `fallback_strategy` string: Fallback strategy: "fixed" for fixed response, "model" for model generation
      - `faq_direct_answer_threshold` number: FAQ direct answer threshold - if similarity > this value, use FAQ answer directly
      - `faq_priority_enabled` boolean: ===== FAQ Strategy Settings ===== Whether FAQ priority strategy is enabled (FAQ answers prioritized over document chunks)
      - `faq_score_boost` number: FAQ score boost multiplier - FAQ results score multiplied by this factor
      - `history_turns` integer: Number of history turns to keep in context. Quick-answer only; smart-reasoning sizes history by context window
      - `image_storage_provider` string: Storage provider for image uploads: "local", "minio", "cos", "tos", "s3", "oss", "ks3". Empty means use the global/workspace default provider.
      - `image_upload_enabled` boolean: ===== Image Upload / Multimodal Settings ===== Whether image upload is enabled for this agent (default: false)
      - `intent_prompts` object: IntentPrompts holds per-intent system prompt overrides for non-retrieval intents (greeting, chitchat, etc.). Empty values fall back to templates under config/prompt_templates/intent_prompts.yaml.
      - `kb_selection_mode` string: ===== Knowledge Base Settings ===== Knowledge base selection mode: "all" = all KBs, "selected" = specific KBs, "none" = no KB
      - `keyword_threshold` number: Keyword retrieval threshold
      - `knowledge_bases` string[]: Associated knowledge base IDs (only used when KBSelectionMode is "selected")
      - `llm_call_timeout` integer: Timeout for a single LLM call in seconds (0 = use global default)
      - `max_completion_tokens` integer: Maximum completion tokens. Quick-answer uses this for the RAG answer. Smart-reasoning ReAct rounds send this value as-is (zero becomes DefaultMaxCompletionTokens at call time: 24576 for smart reasoning).
      - `max_iterations` integer: ===== Agent Mode Settings ===== Maximum iterations for the ReAct loop. Zero is unset (filled with a default). A negative value is unlimited: the loop runs until the model stops, the user cancels, or another guard fires.
      - `mcp_auth_wait_timeout` integer: MCPAuthWaitTimeout is how many seconds to wait for in-conversation OAuth authorization before skipping. <=0 uses the gate's configured timeout.
      - `mcp_selection_mode` string: MCP service selection mode: "all" = all enabled MCP services, "selected" = specific services, "none" = no MCP
      - `mcp_services` string[]: Selected MCP service IDs (only used when MCPSelectionMode is "selected")
      - `memory_enabled` boolean: Whether this agent may read the user's long-term memory. Nil inherits the workspace setting; false opts a single agent out of memory even when the workspace has it on. There is no "on" that overrides the workspace.
      - `model_id` string: ===== Model Settings ===== Model ID to use for conversations
      - `multi_turn_enabled` boolean: ===== Multi-turn Conversation Settings ===== Whether multi-turn conversation is enabled
      - `query_understand_model_id` string: Dedicated chat model ID for the query-understanding (rewrite + intent) step. When empty, the main conversation ModelID is used as a fallback.
      - `question_suggestions` GithubComTencentWeKnoraInternalTypesQuestionSuggestionConfig
        - `follow_ups` GithubComTencentWeKnoraInternalTypesFollowUpSuggestionConfig
          - `additional_instruction` string
          - `allow_regenerate` boolean
          - `categories` string[]
          - `count` integer
          - `enabled` boolean
          - `knowledge_fallback` boolean
          - `max_context_turns` integer
          - `mode` string
          - `model_id` string
          - `suppress_on_fallback` boolean
          - `suppress_when_answer_asks_question` boolean
        - `starters` GithubComTencentWeKnoraInternalTypesStarterSuggestionConfig
          - `count` integer
          - `enabled` boolean
          - `items` string[]
          - `mode` string
      - `reasoning_effort` string: ReasoningEffort selects the thinking intensity (off | auto | minimal | low | medium | high | xhigh | max). Empty keeps the boolean Thinking semantics: true means "auto". See internal/models/api.ReasoningEffort.
      - `rerank_model_id` string: ReRank model ID for retrieval
      - `rerank_threshold` number: Rerank threshold
      - `rerank_top_k` integer: Rerank top K
      - `retain_retrieval_history` boolean: Whether to retain retrieval history across turns
      - `retrieve_kb_only_when_mentioned` boolean: Whether to retrieve knowledge base only when explicitly mentioned with @ (default: false) When true, knowledge base retrieval only happens if user explicitly mentions KB/files with @ When false, knowledge base retrieval happens according to KBSelectionMode
      - `rewrite_prompt_system` string: Rewrite prompt system message
      - `rewrite_prompt_user` string: Rewrite prompt user message template
      - `sandbox_config_id` string: ===== Sandbox Settings ===== SandboxConfigID selects which workspace sandbox config this agent's skill scripts run on. Empty means sandbox execution is disabled. This references the LOGICAL config, never a specific revision: keeping the indirection here is what would let credential rotation happen without re-pointing every agent (see the spec's §4.8).
      - `selected_skills` string[]: Selected skill names (only used when SkillsSelectionMode is "selected")
      - `skills_selection_mode` string: ===== Skills Settings (only for smart-reasoning mode) ===== Skills selection mode: "all" = all installed skills, "selected" = specific skills, "none" = no skills
      - `supported_file_types` string[]: ===== File Type Restriction Settings ===== Supported file types for this agent (e.g., ["csv", "xlsx", "xls"]) Empty means all file types are supported When set, only files with matching extensions can be used with this agent
      - `system_prompt` string: System prompt for the agent (unified prompt, uses web_search_status placeholder for dynamic behavior)
      - `system_prompt_id` string: SystemPromptID references a template ID in prompt_templates/ YAML files. If set and SystemPrompt is empty, the template content is resolved at request time for saved agents.
      - `temperature` number: Temperature for LLM (0-1)
      - `thinking` boolean: Whether to enable thinking mode (for models that support extended thinking)
      - `vector_threshold` number: Vector retrieval threshold
      - `vlm_model_id` string: VLM model ID for image analysis (optional, falls back to workspace-level VLM)
      - `web_fetch_enabled` boolean: Whether to auto-fetch full page content for reranked web search results
      - `web_fetch_top_n` integer: Max number of pages to fetch after rerank (default: 3)
      - `web_search_enabled` boolean: ===== Web Search Settings ===== Whether web search is enabled
      - `web_search_max_results` integer: Maximum web search results
      - `web_search_provider_id` string: WebSearchProviderID references a specific WebSearchProviderEntity. If empty, the workspace's default provider (is_default=true) is used.
    - `created_at` string: Timestamps
    - `created_by` string: Created by user ID
    - `creator_name` string: CreatorName 由 list handler 在返回前批量回填，作用同 KnowledgeBase.CreatorName： 让前端列表卡片区分「我创建」与「同空间其他成员创建」。不落库，内建 agent / 老数据 仍可能为空。
    - `deleted_at` GormDeletedAt
      - `time` string
      - `valid` boolean: Valid is true if Time is not NULL
    - `description` string: Description of the agent
    - `id` string: Unique identifier of the agent (composite primary key with TenantID) For built-in agents, this is 'builtin-quick-answer' or 'builtin-smart-reasoning' For custom agents, this is a UUID
    - `is_builtin` boolean: Whether this is a built-in agent (normal mode / agent mode)
    - `name` string: Name of the agent
    - `tenant_id` integer: Tenant ID (composite primary key with ID)
    - `updated_at` string
  - `success` boolean

## Other responses

- `400`: 请求参数错误
- `403`: 无权修改该智能体
- `404`: 智能体不存在

## Changes

- **2026-10-15** `7850a7947f81`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tencentblueking/apis/weknora-api/changes/agents/:id/patch.md)

---

[API](https://skmtc.dev/tencentblueking/apis/weknora-api.md) - [All operations](https://skmtc.dev/tencentblueking/apis/weknora-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tencentblueking/apis/weknora-api/revisions/b64b227d0d54?raw)