---
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)
    - `audio_upload_enabled` boolean — Whether audio upload (ASR transcription) is enabled for this agent (default: false)
    - `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/tenant 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_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.
    - `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
    - `suggested_prompts` string[] — ===== Suggested Prompts ===== 推荐问题列表，用于在前端对话面板展示快捷提问
    - `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 tenant-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 tenant's default provider (is_default=true) is used.
  - `description` string
  - `name` string

## Response `200`

更新后的智能体

- object

## Other responses

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

## Changes

- **2026-02-26** `3762795e29b6` — 1 info
  - endpoint added
- **2025-12-16** `edf61e68559d` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/tencentblueking/apis/weknora-api/changes/agents/:id/put.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-service-production.skmtc.workers.dev/v1/apis/tencentblueking/weknora-api/revisions/d113fcd208b2/schema)