更新模型绑定¶

更新当前工作区中智能体实际使用的模型配置。对于系统智能体，更新结果作为当前工作区的模型绑定覆盖保存。

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

调用前准备¶

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

请求体¶

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/bindings/model" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": {
      "model_config_ref": "'"$MODEL_CONFIG_ID"'"
    }
  }'

字段说明

请求字段

字段	类型	必填	说明
`model`	object	否	模型绑定配置。省略或传入空对象会保存空模型配置。
`model.model_config_ref`	string	否	模型配置 ID。提供时必须能在当前工作区中解析。
`model.default_model`	string	否	默认模型名称。
`model.params_override`	object	否	覆盖模型调用参数。

请求参数¶

请求示例

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/bindings/model" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": {
      "model_config_ref": "'"$MODEL_CONFIG_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,
    "model": {
      "model_config_ref": "mc_01"
    }
  }
}

字段说明

成功时返回 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.model`	object	保存并解析后的模型配置。
`data.tools`	array	当前有效的工具绑定；存在绑定时返回。
`data.skills`	array	当前有效的技能绑定；存在绑定时返回。
`data.knowledge_bases`	array	当前有效的知识库绑定；存在绑定时返回。
`data.channel_bindings`	array	当前有效的通道绑定；存在绑定时返回。
`data.warnings`	array of string	不能解析的资源引用说明；未产生警告时不返回。
`data.runtime`	object	当前解析出的运行时 Provider 和 Profile；可用时返回。
`data.provider`	object	Provider 的状态、能力和配置摘要；可用时返回。

错误响应¶

响应示例

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

字段说明

常见 HTTP 错误

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	请求体无效，模型字段不符合约束，或 `model_config_ref` 无法在当前工作区中解析。建议：检查 JSON、模型配置 ID 和工作区范围。
`401`	`6`（`UNAUTHENTICATED`）	缺少有效身份凭据。建议：检查 API Key。
`404`	`3`（`NOT_FOUND`）	智能体、模型配置或运行提供商配置不存在。建议：检查路径、模型配置 ID 和运行目标。
`503`	`15`（`UNAVAILABLE`）	智能体资源服务不可用。建议：稍后重试。

后续操作¶

用同一智能体标识查询智能体详情确认模型绑定已更新。

最后更新于 2026 年 9 月 11 日