Update model binding¶

Updates the model configuration actually used by the agent in the current workspace. For system agents, the update results are saved as a model binding overlay for the current workspace.

HTTP
PATCH $CLOUDSIGMA_API_BASE/workspaces/{workspace_id}/agents/{agent_id}/bindings/model

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First Query the agent list to obtain the agent ID, and confirm the model configuration ID to be bound.

Set the operation-specific values used in the request:

$AGENT_ID: The agent ID of the model binding to be updated.
$MODEL_CONFIG_ID: Model configuration ID to bind.

Request¶

Input examples

Shell
curl -X PATCH "$CLOUDSIGMA_API_BASE/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/bindings/model" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": {
      "model_config_ref": "'"$MODEL_CONFIG_ID"'"
    }
  }'

Parameter reference

Path parameters

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	The current workspace ID.
`agent_id`	string	Yes	The agent ID of the model binding to be updated.

Query parameters

Parameters	Type	Is it required	Description
`agent_workspace_id`	string	No	ID of the workspace to which the agent definition belongs. If not provided, the current workspace is used; only the current workspace or the system workspace can be specified.

Request body

Field	Type	Is it required	Description
`model`	object	No	Model binding configuration. Omitting or passing an empty object saves an empty model configuration.
`model.model_config_ref`	string	No	Model configuration ID. When provided, it must be resolvable in the current workspace.
`model.default_model`	string	No	Default model name.
`model.params_override`	object	No	Override model call parameters.

Successful response¶

Returns 200 on success. data is the complete resource binding parsed after the update.

Response example

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"
    }
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.workspace_id`	string	Calling workspace and the workspace owning the agent definition.
`data.agent_workspace_id`	string	Calling workspace and the workspace owning the agent definition.
`data.agent_id`	string	Agent ID and resource version.
`data.agent_version`	integer	Agent ID and resource version.
`data.model`	object	Saved and resolved model configuration.
`data.tools`	array	Currently active tool bindings; returned when bindings exist.
`data.skills`	array	Currently active skill bindings; returned when bindings exist.
`data.knowledge_bases`	array	Currently active knowledge base bindings; returned when bindings exist.
`data.channel_bindings`	array	Currently active channel bindings; returned when bindings exist.
`data.warnings`	string[]	Unresolvable resource reference description; not returned when no warnings are generated.
`data.runtime`	object	Currently resolved runtime Provider and Profile; returned when available.
`data.provider`	object	Provider status, capabilities, and configuration summary; returned when available.

[] after a type denotes an array. [] in a field path denotes each item in an array.

Error response¶

Response example

JSON
{
  "code": 2,
  "message": "<error message>"
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	The request body is invalid, the model field does not comply with the constraints, or `model_config_ref` cannot be resolved in the current workspace.	Check JSON, model configuration ID and workspace scope.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`404`	`3`（`NOT_FOUND`）	Agent, model configuration or run provider configuration does not exist.	Check the path, model configuration ID and run target.
`503`	`15`（`UNAVAILABLE`）	The agent resource service is unavailable.	Try again later.

Follow-up operations¶

Use the same agent identifier Query agent details to confirm that the model binding has been updated.

Last updated on Sep 15, 2026