Update running strategy¶

Replace the agent’s policy reference. policy_refs in the request is saved as a complete set of policy references; using an empty object clears all references.

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

Preparation before calling¶

First query the agent list to obtain the agent ID, and confirm the running policy configuration 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.
$RUNTIME_POLICY_ID: Run policy configuration ID to save.

$ denotes a shell variable reference; it is not part of the actual token or resource ID. Before running the example, set these variables in your terminal, or replace each complete variable name, including $, with its actual value.

Request example¶

curl -X PUT "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/policies" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "policy_refs": {
      "runtime_policy_ref": "'"$RUNTIME_POLICY_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 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¶

Field	Type	Is it required	Description
`policy_refs`	object	No	The collection of policy references to save. When `{}` is omitted or passed in, an empty collection is saved.
`policy_refs.runtime_policy_ref`	string	No	Run policy configuration ID. When provided, it must be parsable in the workspace to which the agent belongs.
`policy_refs.approval_policy_ref`	string	No	Approval policy reference.
`policy_refs.guardrail_policy_ref`	string	No	Guardrail policy reference.

Successful response¶

Returns 200 on success. data is the saved policy details.

{
  "code": 0,
  "data": {
    "agent_id": "agent_01",
    "agent_version": 2,
    "policy_refs": {
      "runtime_policy_ref": "rp_01"
    },
    "runtime_policy": {
      "id": "rp_01"
    },
    "warnings": []
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.agent_id`	string	Agent ID and updated resource version.
`data.agent_version`	integer	Agent ID and updated resource version.
`data.policy_refs`	object	The saved policy reference collection.
`data.runtime_policy`	object	The run policy configuration returned when parsable.
`data.warnings`	string[]	Unresolved reference or description of a currently unresolved policy type.

[] 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, the policy reference contains path delimiters, or `runtime_policy_ref` does not exist in the workspace.	Check JSON and policy references.
`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¶

Confirm the update result using the same resource identifier Query execution strategy.

Last updated on Sep 6, 2026