Update agent

Partially updates agent metadata and configuration. Submit only the fields that need to be modified; return the updated complete agent object.

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

Preparation before calling

First query the agent list to obtain the agent ID. 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.

Request example

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "区域销售助手"
  }'

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 belongs. If not provided, the current workspace is used; only the current workspace or the system workspace can be specified. Agents in the system workspace cannot be updated.

Request body

The request body must be a JSON object. All fields are optional; fields not provided remain unchanged.

Field	Type	Is it required	Description
name	string	No	Agent name and description.
description	string	No	Agent name and description.
avatar_ref	string	No	Display metadata.
icon	string	No	Display metadata.
display_tags	string[]	No	Display metadata.
category	string	No	Display metadata.
sort_order	integer	No	Display metadata.
instruction	object	No	Command configuration, which can include system_prompt, behavior_rules, output_contract_ref and variables_schema.
runtime	object	No	Run target containing provider, profile, and optionally config.
model	object	No	Model configuration, can contain model_config_ref, default_model, and params_override.
binding	object	No	Resource binding, which can include tools, skills, knowledge base references, and channel bindings.
policy_refs	object	No	Policy and workflow reference.
workflow_refs	object	No	Policy and workflow reference.
status	string	No	Agent state.
labels	object	No	Extended tags, comments, and metadata.
annotations	object	No	Extended tags, comments, and metadata.
metadata	object	No	Extended tags, comments, and metadata.
source_type	string	No	Source type and source reference.
source_ref	string	No	Source type and source reference.

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

Successful response

Returns 200 on success. data is the updated complete metadata of the agent.

{
  "code": 0,
  "data": {
    "id": "agent_01",
    "workspace_id": "ws_01",
    "name": "区域销售助手",
    "status": "active",
    "version": 2,
    "updated_at": "2026-01-02T15:04:05Z"
  }
}

The response fields are as follows.

Field	Type	Description
code	integer	0 on success.
data.id	string	Agent ID and workspace ID.
data.workspace_id	string	Agent ID and workspace ID.
data.name	string	The updated name and status.
data.status	string	The updated name and status.
data.version	integer	Updated agent resource version.
data.updated_at	string	Last updated time, using RFC 3339 format.
Other fields of data	object	Are consistent with the complete metadata fields returned by Query agent details.

[] 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 not valid JSON, the field value is invalid, or the specified model, resource, or policy reference cannot be used.	Check request fields and referenced resources.
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）	Specified a read-only agent in the system workspace via agent_workspace_id.	Only updates agents in the current workspace.
404	3（NOT_FOUND）	The agent does not exist within the specified workspace.	Check the agent ID and the workspace it belongs to.
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 agent details to confirm the update result.

Last updated on Sep 9, 2026