更新资源绑定¶

更新智能体引用的工具、技能、知识库或通道绑定。推荐使用 binding_ops 进行单项变更；也可用 binding 按类别更新。

PATCH https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agents/{agent_id}/bindings

调用前准备¶

先查询智能体列表取得智能体 ID，并确认要绑定的资源 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和智能体 ID。

请求体¶

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/bindings" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "binding_ops": [
      {
        "op": "add",
        "kind": "tool",
        "ref": {
          "id": "'"$TOOL_ID"'"
        }
      }
    ]
  }'

字段说明

请求字段

字段	类型	必填	说明
`agent_workspace_id`	string	否	智能体定义所属工作区 ID。与请求体中的同名字段同时提供时，两者必须一致。
`binding`	object	否	按类别替换的绑定。
`binding.tool_refs`	array	否	工具绑定的资源引用列表。
`binding.skill_refs`	array	否	技能绑定的资源引用列表。
`binding.knowledge_base_refs`	array	否	知识库绑定的资源引用列表。
`binding.channel_bindings`	array	否	通道绑定列表。
`binding_ops`	array	否	按项变更列表。
`binding_ops[].op`	string	是	按项变更的操作类型。
`binding_ops[].kind`	string	条件必填	按项变更的资源类别。
`binding_ops[].ref`	object	条件必填	按项变更的资源引用。
`binding_ops[].provider`	string	条件必填	按项变更的通道提供方。
`binding_ops[].channel_type`	string	条件必填	按项变更的通道类型。
`binding_ops[].channel_instance_ids`	array of string	条件必填	按项变更的通道实例 ID 列表。

请求参数¶

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/bindings" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "binding_ops": [
      {
        "op": "add",
        "kind": "tool",
        "ref": {
          "id": "'"$TOOL_ID"'"
        }
      }
    ]
  }'

参数说明

路径参数

字段	类型	必填	说明
`workspace_id`	string	是	当前工作区 ID。
`agent_id`	string	是	要更新的智能体 ID。

查询参数

字段	类型	必填	说明
`agent_workspace_id`	string	否	智能体定义所属的工作区 ID。未提供时使用当前工作区。

成功响应¶

响应示例

{
  "code": 0,
  "data": {
    "workspace_id": "ws_01",
    "agent_workspace_id": "ws_01",
    "agent_id": "agent_01",
    "agent_version": 3,
    "tools": [
      {
        "id": "tool_01",
        "kind": "tool"
      }
    ],
    "skills": [],
    "knowledge_bases": [],
    "channel_bindings": [],
    "warnings": []
  }
}

字段说明

成功时返回 200。data 的结构与查询资源绑定相同，表示已保存并解析后的有效绑定。

通用字段

字段	类型	说明
`code`	integer	成功时为 0。

响应数据

字段	类型	说明
`data.workspace_id`	string	调用工作区和智能体定义所属工作区。
`data.agent_workspace_id`	string	调用工作区和智能体定义所属工作区。
`data.agent_id`	string	智能体 ID 和更新后的资源版本。
`data.agent_version`	integer	智能体 ID 和更新后的资源版本。
`data.tools`	array	保存并解析后的绑定。
`data.skills`	array	保存并解析后的绑定。
`data.knowledge_bases`	array	保存并解析后的绑定。
`data.channel_bindings`	array	保存并解析后的绑定。
`data.warnings`	array of string	未能解析的引用说明。

错误响应¶

响应示例

{
  "code": 2,
  "message": "<错误信息>"
}

字段说明

常见 HTTP 错误

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	请求体无效、`binding_ops` 与类别替换混用，资源引用无效，或工作区范围不允许。建议：检查 JSON、资源引用和工作区范围。
`401`	`6`（`UNAUTHENTICATED`）	缺少有效身份凭据。建议：检查 API Key。
`403`	`5`（`PERMISSION_DENIED`）	当前调用者没有更新智能体的权限。建议：检查工作区中的智能体授权。
`403`	`7`（`FORBIDDEN`）	尝试直接修改当前工作区中的系统只读智能体。建议：如需配置系统智能体，请在工作区中创建允许的绑定覆盖。
`404`	`3`（`NOT_FOUND`）	智能体或运行提供商配置不存在。建议：检查智能体 ID、所属工作区和运行目标。
`503`	`15`（`UNAVAILABLE`）	智能体资源服务或其授权依赖暂不可用。建议：稍后重试。

后续操作¶

用同一资源标识查询资源绑定确认更新结果。

最后更新于 2026 年 9 月 11 日