本文介绍如何通过 API 修改 Agent 配置中的连接器（Plugin + Tool）——即为 Agent 装载与卸载插件及其下的工具。

说明：

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

完整流程：

获取 PluginId → 获取 ToolId →〔可选：创建子 Agent〕→ 修改 Agent 的 PluginList / ToolList → 发布生效

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

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

查应用列表获取 AppId

调用 DescribeAppSummaryList：

关键入参：

关键出参：

req = models.DescribeAppSummaryListRequest()
req.SpaceId = space_id
req.Query = "数据分析助手"
f = models.Filter()
f.Name = "AppMode"
f.ValueList = ["4"]
req.FilterList = [f]
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：获取 PluginId

调用 DescribePluginSummaryList，在空间内拉取可用插件列表，定位目标插件的 PluginId。

关键入参：

关键出参：

req = models.DescribePluginSummaryListRequest()
req.SpaceId = space_id
req.Query = "搜索"
req.Module = 3              # 3 = 智能工作台场景
req.PageNumber = 0
req.PageSize = 20
resp = client.DescribePluginSummaryList(req)
plugin_id = resp.PluginList[0].PluginId

说明： PluginSummary 中不含工具级别的 ToolId，需要通过步骤 2 的 DescribePlugin 获取。PluginClass=1 表示连接器类插件。

步骤 2：获取 ToolId

调用 DescribePlugin，用步骤 1 拿到的 PluginId 获取插件详情，从 ToolList 中取得具体工具的 ToolId。

关键入参：

关键出参：

req = models.DescribePluginRequest()
req.PluginId = plugin_id
req.SpaceId = space_id
resp = client.DescribePlugin(req)
tool_id = resp.Plugin.ToolList[0].ToolId

到这里已集齐挂载所需的两个 ID：plugin_id 与 tool_id。

步骤 3（可选）：创建子 Agent

如果要把连接器挂到已有的主 Agent 上，跳过本步骤，直接进入步骤 4。

仅当需要一个独立的子 Agent 来承载连接器时，调用 CreateAgent 新建：

关键入参：

Profile.Role 枚举值：

关键出参：

req = models.CreateAgentRequest()
req.AppId = app_id
req.Agent = models.AgentSpec()
req.Agent.Profile = models.AgentProfile()
req.Agent.Profile.Name = "连接器子Agent"
req.Agent.Profile.Role = 1            # 子 Agent
req.Agent.Profile.Description = "调用外部连接器完成检索类任务"
req.Agent.Instructions = "你负责调用外部连接器完成检索类任务。"
req.Agent.Model = models.AgentModelConfig()
req.Agent.Model.ModelId = "Moonshot/moonshot-v1-128k"
req.Agent.Model.Alias = "moonshot-v1-128k"
req.Agent.Model.ContextWordsLimit = 20000
req.Agent.Model.InstructionsWordsLimit = 20000
resp = client.CreateAgent(req)
agent_id = resp.AgentId    # 后续步骤 4 使用此 AgentId

说明： CreateAgent 也支持创建时直接传入 PluginList / ToolList 一并挂载连接器。

步骤 4：挂载连接器

调用 ModifyAgent，将步骤 1、2 获取的 PluginId / ToolId 挂载到目标 Agent。

ADP 采用「平台注册 Plugin → 显式绑定 Tool 到 Agent」的模式。一个 Plugin 包含一个或多个 Tool；Agent 需要显式声明使用哪些 Plugin 及其下的哪些 Tool：

二者的 PluginId 必须对应一致。PluginList / ToolList 是全量覆盖（非增量），追加时需先取回已有列表合并后整体提交。

AuthType 枚举值：

关键入参：

关键出参：

# 声明插件
plugin_cfg = models.AgentPluginConfig()
plugin_cfg.PluginId = plugin_id
plugin_cfg.AuthType = 0               # 视插件实际鉴权方式而定

# 声明工具
tool_basic = models.AgentToolBasicConfig()
tool_basic.PluginId = plugin_id       # 必须与所属插件一致
tool_basic.ToolId = tool_id
tool_cfg = models.AgentToolConfig()
tool_cfg.Config = tool_basic

# 提交修改
req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentSpec()
req.Agent.PluginList = [plugin_cfg]
req.Agent.ToolList = [tool_cfg]
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["PluginList", "ToolList"]
client.ModifyAgent(req)

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

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

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 模式）。

全流程接口一览