腾讯云智能体开发平台动态修改 Agent 配置（Claw 模式

Claw 模式支持在运行时按用户或按会话动态调整 Agent 配置（更换模型、装卸 Skill、绑定插件工具），无需修改应用配置，也无需重新发布。本文说明该机制的启用前提、调用链路，以及各类配置变更的接口用法。
一、前提条件
前提 1：开启「允许在对话中动态修改配置」开关
在应用的高级设置中开启该开关（也可通过 ModifyApp 接口开启）。它是动态配置能力的总开关：仅当开关开启时，后续传入的用户级 AgentId 与运行时配置才会生效；否则对话仅使用应用发布时的固定配置。
通过接口开启开关：
req = models.ModifyAppRequest()
req.AppId = app_id
req.Config = models.AppConfig()
req.Config.Mode = models.AppModeConfig()
req.Config.Mode.ClawAgentConfig = models.ClawAgentConfig()
req.Config.Mode.ClawAgentConfig.CustomConfig = models.ClawAgentCustomConfig()
req.Config.Mode.ClawAgentConfig.CustomConfig.Enabled = True
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["Config.Mode.ClawAgentConfig"]
client.ModifyApp(req)
注意：
修改开关后需要调用 CreateRelease 重新发布才能生效，可参考从零搭建一个 Claw 模式应用 > 发布应用。﻿
前提 2：获取用户级 Agent
按用户维度修改配置，需要一个归属于该用户的 Agent 实例，而非直接修改应用的配置端 Agent。通过 CopyAgentFromApp 从应用复制出用户级 Agent：
Kind 枚举值（关于开发者/使用者的概念，详情请参见 概览）：
值
含义
0
配置端 Agent（开发者创建应用时使用）。
1
用户级 Agent（为使用者复制出的独立实例，用于按用户维度修改配置）。
req = models.CopyAgentFromAppRequest()
req.AppId = app_id
req.Kind = 1                  # 用户级 Agent
resp = client.CopyAgentFromApp(req)
agent_id = resp.ParentAgentId   # 该用户后续对话与改配置都用这个 AgentId
print(f"agent_id={agent_id}")
二、将用户级 Agent 绑定到会话
创建会话时将上一步的 AgentId 传入 CreateConversation（仅在开关开启时可用）：
Type 枚举值：5 = API 接入。详情请参见 从零搭建一个 Claw 模式应用 > 步骤 6：创建会话。
req = models.CreateConversationRequest()
req.Type = 5                  # API 接入
req.AppId = app_id
req.AppKey = APP_KEY
req.UserId = USER_ID
req.AgentId = agent_id       # 绑定用户级 Agent
resp = client.CreateConversation(req)
conversation_id = resp.ConversationId
绑定后，针对该 AgentId 的任何配置变更仅作用于该用户的会话链路。
三、动态修改配置
应用级 vs Agent 级：开启动态配置开关是应用级设置（通过 ModifyApp，所有 Agent 共享），而下文的模型/Skill/工具变更是 Agent 级设置（通过 ModifyAgent，每个用户级 Agent 独立）。关于两者的区别详细请参见 从零搭建一个 Claw 模式应用 > 步骤 4：修改配置（可选）。
所有 Agent 级配置变更均通过 ModifyAgent 完成，由 UpdateMask.Paths 指定需更新的字段，其余字段保持不变。
3.1 更换模型
先通过 DescribeModelList 拉取 Claw 场景可用模型（ModelScene=18 为 Claw 模式可用模型，完整场景枚举见 API 文档），再调用 ModifyAgent 更新 Model 字段：
req = models.DescribeModelListRequest()
req.SpaceId = space_id
req.ModelScene = 18
req.PageNumber = 0
req.PageSize = 20
resp = client.DescribeModelList(req)
new_model_id = resp.ModelList[0].ModelBasic.ModelId
﻿
req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentSpec()
req.Agent.Model = models.AgentModelConfig()
req.Agent.Model.ModelId = new_model_id
req.Agent.Model.ContextWordsLimit = 20000
req.Agent.Model.InstructionsWordsLimit = 20000
req.UpdateMask = models.FiledMask()
req.UpdateMask.Paths = ["Model"]
client.ModifyAgent(req)
3.2 装卸 Skill
先通过 DescribeSkillSummaryList 拉取可选 Skill（可配合 DescribeSkillCategoryList 按分类浏览），再使用 ModifyAgent 提交更新后的完整 SkillList（全量覆盖，非增量）：
﻿
req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentSpec()
﻿
skill_list = []
for skill_id in skill_ids:
    skill = models.AgentSkill()
    skill.SkillId = skill_id
    skill_list.append(skill)
    
req.Agent.SkillList = skill_list
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["SkilList"]
client.ModifyAgent(req)
装载 Skill：将新的 SkillId 加入列表后整体提交。
卸载 Skill：将目标 SkillId 从列表中移除后整体提交。
清空全部：提交空数组 []。
3.3 绑定 / 解绑插件工具
先通过 DescribePluginSummaryList 拉取可用插件（Module=1 表示应用已装载的插件，完整枚举见 API 文档），再使用 ModifyAgent 更新 PluginList 与 ToolList：
req = models.DescribePluginSummaryListRequest()
req.SpaceId = space_id
req.Module = 1
resp = client.DescribePluginSummaryList(req)
﻿
req = models.ModifyAgentRequest()
req AppId = app_id
req AgentId = agent_id
req.Agent = models.AgentSpec()
﻿
plugin = models.AgentPluginConfig ()
plugin.PluginId = "bf8ad2f3-1e5c-410a-ae81-abd7c5c14f1c"
plugin.AuthType = 0
﻿
req Agent.PluginList = [ plugin ]
req.UpdateMask = models FieldMask
req.UpdateMask.Paths = ["PluginList"]
client ModifyAgent (req)
四、透传自定义变量（无需修改 Agent）
若仅需向 Agent 传递运行时上下文（用户信息、部门等），无需 CopyAgentFromApp，也无需修改 Agent——只需在对话请求的 Contents 中追加一个 custom_variables 块即可（同样受开关约束）：
import json
﻿
contents = [
    {"Type": "text", "Text": "帮我生成本月周报"},
    {"Type": "custom_variables", "CustomVariables": {
        # value 若是对象/数组，必须先序列化成字符串
        "account": json.dumps({"id": "u_123", "name": "张三"}, ensure_ascii=False),
        "department": "数据科学部",
    }},
]
# 把 contents 作为 /adp/v2/chat 请求体的 Contents 字段发送（见「从零搭建一个 Claw 应用」的发起对话步骤）
CustomVariables 的 value 若为对象或数组，必须先经 json.dumps 序列化为字符串再传入，否则 Agent 无法正确接收。
五、机制小结
ModifyApp(Config.Mode.ClawAgentConfig) + CreateRelease  ← 通过 API 开启总开关（或在网页高级设置中开启）
        ↓
CopyAgentFromApp(AppId, Kind=1) → ParentAgentId         ← 获取用户级 Agent（修改配置时必需）
        ↓
CreateConversation(AgentId=ParentAgentId)               ← 绑定到会话
        ↓
ModifyAgent(AgentId, UpdateMask=[...])                  ← 更换模型 / 装卸 Skill / 绑定工具
动态操作
是否需要用户级 Agent
关键接口
开启动态配置开关
-
ModifyApp(["Config.Mode.ClawAgentConfig"]) + CreateRelease
获取用户级 Agent
-
CopyAgentFromApp(AppId, Kind=1)
更换模型
需要
DescribeModelList + ModifyAgent(["Model"])
装卸 Skill
需要
DescribeSkillSummaryList + ModifyAgent(["SkillList"])
绑定 / 解绑工具
需要
DescribePluginSummaryList + ModifyAgent(["ToolList","PluginList"])
透传自定义变量
不需要
对话请求 Contents 中追加 custom_variables

动态修改 Agent 配置（Claw 模式）

本页目录：

一、前提条件

前提 1：开启「允许在对话中动态修改配置」开关

前提 2：获取用户级 Agent

二、将用户级 Agent 绑定到会话

三、动态修改配置

3.1 更换模型

3.2 装卸 Skill

3.3 绑定 / 解绑插件工具

四、透传自定义变量（无需修改 Agent）

五、机制小结

值	含义
0	配置端 Agent（开发者创建应用时使用）。
1	用户级 Agent（为使用者复制出的独立实例，用于按用户维度修改配置）。

动态操作	是否需要用户级 Agent	关键接口
开启动态配置开关	-	`ModifyApp(["Config.Mode.ClawAgentConfig"])` + `CreateRelease`
获取用户级 Agent	-	`CopyAgentFromApp(AppId, Kind=1)`
更换模型	需要	`DescribeModelList` + `ModifyAgent(["Model"])`
装卸 Skill	需要	`DescribeSkillSummaryList` + `ModifyAgent(["SkillList"])`
绑定 / 解绑工具	需要	`DescribePluginSummaryList` + `ModifyAgent(["ToolList","PluginList"])`
透传自定义变量	不需要	对话请求 `Contents` 中追加 `custom_variables`