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

# 更新智能体

`PUT /agents/{id}`

更新智能体的名称、描述和配置

## Path parameters

- `id` string, required

## Request body

- InternalHandlerUpdateAgentRequest
  - `avatar` string
  - `config` GithubComTencentWeKnoraInternalTypesCustomAgentConfig
    - `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 will be resolved at startup.
    - `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
    - `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 (only for normal mode)
    - `max_iterations` integer — ===== Agent Mode Settings ===== Maximum iterations for ReAct loop (only for agent type)
    - `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")
    - `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
    - `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
    - `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 preloaded 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 will be resolved at startup.
    - `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.
  - `description` string
  - `name` string

## Response `200`

更新后的智能体

- object

## Other responses

- `400` — 请求参数错误
- `403` — 无法修改内置智能体

---

[API](https://skmtc.net/tencentblueking/apis/weknora-api.md) · [All operations](https://skmtc.net/tencentblueking/apis/weknora-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tencentblueking/weknora-api/revisions/abce9036def5/schema)