本文介绍如何通过 API 修改 Agent 配置中的 Skill（技能）——即为 Agent 装载与卸载 Skill。

说明：

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

完整流程：

查看已装载的 Skill → 查询可用 Skill → 修改 Agent 的 SkillList → 发布生效

前置条件（可选）：获取 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：查看已装载的 Skill

调用 DescribeAgentDetail 获取 Agent 当前配置，从 SkillList 中确认已装载哪些 Skill。由于步骤 3 提交的 SkillList 为全量覆盖，本步获取的列表是后续增删的基准。

关键入参：

关键出参：

AgentDetail.SkillList 中每项（AgentSkill）的字段：

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

# 记录当前已装载的 SkillId，作为增删基准
current_skill_ids = [s.SkillId for s in resp.Agent.SkillList]
for s in resp.Agent.SkillList:
    print(s.SkillId, s.Name, s.DisplayName, s.CurrentVersion)

步骤 2：查询可用 Skill

调用 DescribeSkillSummaryList 拉取空间内可用的 Skill 列表，取得目标 Skill 的 SkillId。

关键入参：

ProviderType（提供方类型）枚举值：

关键出参：

SkillSummary 中的常用字段：

req = models.DescribeSkillSummaryListRequest()
req.SpaceId = space_id
req.Query = "数据分析"
req.PageNumber = 0
req.PageSize = 20
# 只看官方 Skill
f = models.Filter()
f.Name = "ProviderType"
f.ValueList = ["1"]
req.FilterList = [f]
resp = client.DescribeSkillSummaryList(req)

skill = resp.SkillSummaryList[0]
skill_id = skill.SkillId
print(skill_id, skill.Profile.DisplayName, skill.CurrentVersionInfo.Version)

说明： 若需按分类筛选，可先调用 DescribeSkillCategoryList（无需入参）获取全部分类，再将 CategoryKey 填入 FilterList。

req = models.DescribeSkillCategoryListRequest()
resp = client.DescribeSkillCategoryList(req)
for c in resp.CategoryList:
    print(c.CategoryKey, c.CategoryName)     # 例：doc 文档

（可选）查看 Skill 详情

装载前若需确认 Skill 的版本列表、调用情况或安全检测结果，可调用 DescribeSkillDetail：

关键入参：

关键出参：

req = models.DescribeSkillDetailRequest()
req.SkillId = skill_id
req.SpaceId = space_id
resp = client.DescribeSkillDetail(req)
print(resp.SkillDetail.SkillSummary.Profile.DisplayName)

步骤 3：修改 Agent 的 SkillList

调用 ModifyAgent，提交更新后的 SkillList，并通过 UpdateMask.Paths 指定只更新 SkillList 字段。

关键入参：

AgentSkillConfig 字段：

关键出参：

SkillList 为全量覆盖（非增量），三种操作都通过提交完整列表实现：

# 在步骤 1 获取的 current_skill_ids 基础上追加新 Skill
target_skill_ids = current_skill_ids + [skill_id]

# 如需卸载：target_skill_ids = [i for i in current_skill_ids if i != skill_id]

skill_list = []
for sid in target_skill_ids:
    s = models.AgentSkillConfig()
    s.SkillId = sid
    skill_list.append(s)

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

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

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

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

发布状态枚举值：

import time

req = models.CreateReleaseRequest()
req.AppId = app_id
req.Description = "装载数据分析 Skill"
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 并在运行时装卸 Skill，无需重新发布。详见 动态修改 Agent 配置（Claw 模式）。

全流程接口一览