更新智能体¶

部分更新智能体元数据和配置。只提交需要修改的字段；返回更新后的完整智能体对象。

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

调用前准备¶

先查询智能体列表取得智能体 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和智能体 ID。

请求体¶

请求示例

curl -X PATCH "https://moi.matrixorigin.cn/newmoi/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": "区域销售助手"
  }'

字段说明

请求字段

字段	类型	必填	说明
`name`	string	否	智能体名称和说明。
`description`	string	否	智能体名称和说明。
`avatar_ref`	string	否	展示元数据。
`icon`	string	否	展示元数据。
`display_tags`	string（字符串数组）	否	展示元数据。
`category`	string	否	展示元数据。
`sort_order`	integer	否	展示元数据。
`instruction`	object	否	指令配置，可包含 system_prompt、behavior_rules、output_contract_ref 和 variables_schema。
`runtime`	object	否	运行目标，包含 provider、profile 和可选 config。
`model`	object	否	模型配置，可包含 model_config_ref、default_model 和 params_override。
`binding`	object	否	资源绑定，可包含工具、技能、知识库引用和通道绑定。
`policy_refs`	object	否	策略和工作流引用。
`workflow_refs`	object	否	策略和工作流引用。
`status`	string	否	智能体状态。
`labels`	object	否	扩展标签、注释和元数据。
`annotations`	object	否	扩展标签、注释和元数据。
`metadata`	object	否	扩展标签、注释和元数据。
`source_type`	string	否	来源类型和来源引用。
`source_ref`	string	否	来源类型和来源引用。

请求参数¶

请求示例

curl -X PATCH "https://moi.matrixorigin.cn/newmoi/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": "区域销售助手"
  }'

参数说明

路径参数

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

查询参数

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

成功响应¶

响应示例

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

字段说明

成功时返回 200。data 为更新后的智能体完整元数据。

通用字段

字段	类型	说明
`code`	integer	成功时为 0。
`data`	object	与查询智能体详情返回的完整元数据字段一致。

响应数据

字段	类型	说明
`data.id`	string	智能体 ID 和所属工作区 ID。
`data.workspace_id`	string	智能体 ID 和所属工作区 ID。
`data.name`	string	更新后的名称和状态。
`data.status`	string	更新后的名称和状态。
`data.version`	integer	更新后的智能体资源版本。
`data.updated_at`	string	最近更新时间，使用 RFC 3339 格式。
`data 的其他字段`	object	与确认智能体详情返回的完整元数据字段一致。

错误响应¶

响应示例

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

字段说明

常见 HTTP 错误

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	请求体不是有效 JSON，字段值无效，或指定的模型、资源或策略引用无法使用。建议：检查请求字段和引用资源。
`401`	`6`（`UNAUTHENTICATED`）	缺少有效身份凭据。建议：检查 API Key。
`403`	`5`（`PERMISSION_DENIED`）	当前调用者没有更新智能体的权限。建议：检查工作区中的智能体授权。
`403`	`7`（`FORBIDDEN`）	通过 `agent_workspace_id` 指定了系统工作区中的只读智能体。建议：仅更新当前工作区中的智能体。
`404`	`3`（`NOT_FOUND`）	指定工作区范围内不存在该智能体。建议：检查智能体 ID 和所属工作区。
`503`	`15`（`UNAVAILABLE`）	智能体资源服务或其授权依赖暂不可用。建议：稍后重试。

后续操作¶

用同一资源标识查询智能体详情确认更新结果。

最后更新于 2026 年 9 月 3 日