Update resource binding

Updates a tool, skill, knowledge base, or channel binding referenced by the agent. It is recommended to use binding_ops for single changes; binding can also be used to update by category.

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

Preparation before calling

First query the agent list to obtain the agent ID, and confirm the resource ID to be bound. Prepare the personal access token, target workspace ID, and agent ID that have access to the target workspace.

The example below uses:

• $AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.

• $WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.

• $AGENT_ID: Agent ID to update.

• $TOOL_ID: Tool ID to add.

Request example

The following example adds a tool to the current binding:

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

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	The current workspace ID.
agent_id	string	Yes	The agent ID to update.

Query parameters

Parameters	Type	Is it required	Description
agent_workspace_id	string	No	ID of the workspace to which the agent definition belongs. When provided at the same time as a field with the same name in the request body, the two must be consistent.

Request body

The request body must be a JSON object. binding_ops cannot be used with a non-empty category replacement field in binding.

Field	Type	Is it required	Description
agent_workspace_id	string	No	The ID of the workspace to which the agent definition belongs. If not provided, the current workspace is used.
binding	object	No	Update bindings by category. Omitting a category retains the category; explicitly passing an empty array clears the category.
binding.tool_refs	array	No	Resource references for tools, skills, and knowledge bases. Each uses at least the id identification resource and may include workspace_id, kind, and config.
binding.skill_refs	array	No	Resource references for tools, skills, and knowledge bases. Each uses at least the id identification resource and may include workspace_id, kind, and config.
binding.knowledge_base_refs	array	No	Resource references for tools, skills, and knowledge bases. Each uses at least the id identification resource and may include workspace_id, kind, and config.
binding.channel_bindings	array	No	Channel binding; each contains provider, channel_type, and channel_instance_ids.
binding_ops	array	No	List of changes by item.
binding_ops[].op	string	Yes	Operation type: add, remove, set_config, or set_channel_binding.
binding_ops[].kind	string	Condition required	Specify the resource category and resource reference respectively for add, remove, and set_config. Category is tool, skill or knowledge_base.
binding_ops[].ref	object	Condition required	Specify the resource category and resource reference respectively for add, remove, and set_config. Category is tool, skill or knowledge_base.
binding_ops[].provider	string	Condition required	set_channel_binding specifies the channel capability range and the instance ID list to be replaced.
binding_ops[].channel_type	string	Condition required	set_channel_binding specifies the channel capability range and the instance ID list to be replaced.
binding_ops[].channel_instance_ids	string[]	Condition required	set_channel_binding specifies the channel capability range and the instance ID list to be replaced.

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

Successful response

Returns 200 on success. The structure of data is the same as query resource binding], which represents a valid binding that has been saved and parsed.

{
  "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": []
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.workspace_id	string	Call the workspace and the workspace to which the agent definition belongs.
data.agent_workspace_id	string	Call the workspace and the workspace to which the agent definition belongs.
data.agent_id	string	Agent ID and updated resource version.
data.agent_version	integer	Agent ID and updated resource version.
data.tools	array	The saved and parsed binding.
data.skills	array	The saved and parsed binding.
data.knowledge_bases	array	The saved and parsed binding.
data.channel_bindings	array	The saved and parsed binding.
data.warnings	string[]	Unresolved reference description.

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

Error response

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

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	The request body is invalid, binding_ops is mixed with category replacement, the resource reference is invalid, or the workspace scope is not allowed.	Check JSON, resource references and workspace scopes.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current caller does not have permission to update the agent.	Check the agent authorization in the workspace.
403	7（FORBIDDEN）	Attempt to directly modify the system read-only agent in the current workspace.	To configure a system agent, create an allowed binding override in the workspace.
404	3（NOT_FOUND）	Agent or run provider configuration does not exist.	Check the agent ID, belonging workspace and run target.
503	15（UNAVAILABLE）	The agent resource service or its authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Use the same resource identifier Query resource binding to confirm the update result.

Last updated on Sep 9, 2026