本文介绍如何通过 API 修改 Agent 配置中的模型——即更换推理模型、调整上下文长度限制与模型超参。

说明：

已通过 CreateApp 创建好应用，并通过 CreateAgent 创建好 Agent——即已拿到 AppId 和 AgentId。密钥准备与客户端初始化请参考 从零搭建一个 Claw 模式应用 的「前置条件与调用方式」小节。

完整流程：

查看当前模型配置 → 查询可用模型 → 修改 Agent 的 Model → 发布生效

前置条件（可选）：获取 AppId / AgentId

若手头没有 AppId 或 AgentId，可通过以下接口查询。

查应用列表获取 AppId

调用 DescribeAppSummaryList：

关键入参：

关键出参：

req = models.DescribeAppSummaryListRequest()
req.SpaceId = space_id
resp = client.DescribeAppSummaryList(req)
app_id = resp.AppSummaryList[0].AppId

查 Agent 列表获取 AgentId

调用 DescribeAgentSummaryList：

关键入参：

关键出参：

req = models.DescribeAgentSummaryListRequest()
req.Scope = 0
req.AppId = app_id
resp = client.DescribeAgentSummaryList(req)
# 取主 Agent（Role=0）
agent_id = next(a.AgentId for a in resp.AgentList if a.Profile.Role == 0)

步骤 1：查看当前的模型配置

调用 DescribeAgentDetail 获取 Agent 当前的完整配置，确认现有模型及超参，作为修改前的基准。

关键入参：

关键出参：

req = models.DescribeAgentDetailRequest()
req.AppId = app_id
req.AgentId = agent_id
resp = client.DescribeAgentDetail(req)

cur = resp.Agent.Model
print(cur.ModelId, cur.Alias, cur.ContextWordsLimit, cur.InstructionsWordsLimit)
print(cur.ModelParameters.Temperature, cur.ModelParameters.MaxTokens)

返回的 Model 结构示例：

{
    "Alias": "智谱GLM-5.1",
    "ContextWordsLimit": 0,
    "InstructionsWordsLimit": 20000,
    "ModelId": "TCADP/glm-5.1",
    "ModelParameters": {
        "DeepThinking": "",
        "MaxTokens": 16384,
        "ReasoningEffort": "",
        "ReplyFormat": "",
        "StopSequenceList": [],
        "Temperature": 1
    }
}

说明： 步骤 3 使用 UpdateMask 更新 Model 时为整体替换，建议先在此获取当前值，对照后再决定需要保留或调整哪些参数。

步骤 2：查询可用模型

调用 DescribeModelList 获取当前场景下可用的模型列表，从中取得目标模型的 ModelId。

关键入参：

ModelScene 常用枚举值：

完整枚举值（共 30 项，含多模态理解、Embedding、Rerank、工作流各节点等）详见 DescribeModelList 接口文档。

关键出参：

Model 中与修改模型配置相关的字段：

req = models.DescribeModelListRequest()
req.ModelScene = 18            # 18 = Claw 模式
req.SpaceId = space_id
req.PageNumber = 0
req.PageSize = 20
resp = client.DescribeModelList(req)

model = resp.ModelList[0]
model_id = model.ModelBasic.ModelId
print(model_id, model.ModelBasic.Name)

# 查看该模型支持的超参及范围，避免传入非法值
for p in model.ParameterList:
    print(p.Name, p.DefaultValue, p.MinValue, p.MaxValue, p.EnumValueList)

说明： 不同模型支持的超参不同。建议先读取 ParameterList 确认 temperature、top_p 等超参的取值范围，再在步骤 3 中设置。

步骤 3：修改 Agent 的模型配置

调用 ModifyAgent，将 Agent.Model 更新为新模型，并通过 UpdateMask.Paths 指定只更新 Model 字段，其余配置（指令、Skill、工具等）保持不变。

关键入参：

AgentModelConfig 字段：

ModelParams 常用字段：

完整字段详见 ModelParams 数据结构。

关键出参：

model_cfg = models.AgentModelConfig()
model_cfg.ModelId = model_id
model_cfg.Alias = "DeepSeek-V3.2"
model_cfg.ContextWordsLimit = 20000
model_cfg.InstructionsWordsLimit = 20000

# 设置模型超参（取值需在步骤 2 的 ParameterList 范围内）
params = models.ModelParams()
params.Temperature = 0.7
params.TopP = 0.6
params.MaxTokens = 16384
params.DeepThinking = "disabled"
model_cfg.ModelParameters = params

req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentSpec()
req.Agent.Model = model_cfg
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["Model"]      # 只更新 Model 字段
client.ModifyAgent(req)

注意： UpdateMask.Paths 决定哪些字段被更新。只传 ["Model"] 时，Agent 的指令、Skill、工具等配置不受影响。

步骤 4：发布应用使配置生效

Agent 配置修改后不会立即对线上用户生效，需调用 CreateRelease 发布，并用 DescribeReleaseSummary 轮询发布状态。

发布状态枚举值：

import time

req = models.CreateReleaseRequest()
req.AppId = app_id
req.Description = "更换推理模型"
release_id = client.CreateRelease(req).ReleaseId

while True:
    req = models.DescribeReleaseSummaryRequest()
    req.AppId = app_id
    req.ReleaseId = release_id
    status = client.DescribeReleaseSummary(req).ReleaseSummary.Status
    if status == 3:
        print("发布成功")
        break
    if status == 4:
        print("发布失败")
        break
    time.sleep(2)

说明： Claw 模式下若开启了「允许在对话中动态修改配置」，可为每个用户复制独立的用户级 Agent 并在运行时更换模型，无需重新发布。详见 动态修改 Agent 配置（Claw 模式）。

全流程接口一览