# 更新模型绑定

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## 调用前准备

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

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```bash
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"'"
    }
  }'
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 请求字段

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

:::
::::
:::::
::::::
:::::::

## 请求参数

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 请求示例

```bash
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"'"
    }
  }'
```

:::::
:::::{tab-item} 参数说明

::::{tab-set}
:::{tab-item} 路径参数

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

:::
:::{tab-item} 查询参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `agent_workspace_id` | string | 否 | 智能体定义所属工作区 ID。未提供时使用当前工作区；只能指定当前工作区或系统工作区。 |

:::
::::
:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "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"
    }
  }
}
```

:::::
:::::{tab-item} 字段说明

成功时返回 `200`。`data` 返回更新后的模型绑定及当前可解析的运行时信息。未绑定的资源数组和无可用运行时的扩展信息可能省略。

::::{tab-set}
:::{tab-item} 通用字段

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

:::
:::{tab-item} 响应数据

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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 的状态、能力和配置摘要；可用时返回。 |

:::
::::
:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 常见 HTTP 错误

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

:::
::::
:::::
::::::
:::::::

## 后续操作

用同一智能体标识[查询智能体详情](get-agent.md)确认模型绑定已更新。