查询智能体详情¶

读取一个智能体的完整元数据、运行目标、模型配置、资源绑定和策略引用。可选地指定智能体所属工作区；该值只能是当前工作区或系统工作区。

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

调用前准备¶

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

请求参数¶

请求示例

curl --get "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" \
  --data-urlencode "agent_workspace_id=$WORKSPACE_ID"

参数说明

路径参数

字段	类型	必填	说明
`workspace_id`	string	是	当前工作区 ID，必须与 X-Workspace-ID 一致。
`agent_id`	string	是	要查看的智能体 ID。

查询参数

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

成功响应¶

响应示例

{
  "code": 0,
  "data": {
    "id": "agent_01",
    "workspace_id": "ws_01",
    "schema_version": 1,
    "name": "销售助手",
    "description": "销售数据分析",
    "instruction": {
      "system_prompt": "分析销售数据",
      "behavior_rules": []
    },
    "runtime": {
      "provider": "matrixone",
      "profile": "default"
    },
    "model": {
      "model_config_ref": "mc_01"
    },
    "binding": {
      "tool_refs": [],
      "skill_refs": [],
      "knowledge_base_refs": [],
      "channel_bindings": []
    },
    "policy_refs": {},
    "workflow_refs": {},
    "status": "active",
    "version": 1,
    "source_type": "custom",
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-15T10:00:00Z"
  }
}

字段说明

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

通用字段

字段	类型	说明
`code`	integer	成功时为 0。

响应数据

字段	类型	说明
`data.id`	string	智能体 ID 和所属工作区 ID。
`data.workspace_id`	string	智能体 ID 和所属工作区 ID。
`data.schema_version`	integer	智能体元数据结构版本。
`data.name`	string	智能体名称和说明；未设置说明时不返回。
`data.description`	string	智能体名称和说明；未设置说明时不返回。
`data.avatar_ref`	string	展示元数据；未设置时不返回。
`data.icon`	string	展示元数据；未设置时不返回。
`data.display_tags`	string（字符串数组）	展示元数据；未设置时不返回。
`data.category`	string	分类和展示排序值；未设置时不返回。
`data.sort_order`	integer	分类和展示排序值；未设置时不返回。
`data.instruction`	object	指令配置，可包含 system_prompt、behavior_rules、output_contract_ref 和 variables_schema。
`data.runtime`	object	运行目标，包含 provider、profile 和可选 config。
`data.model`	object	模型配置，可包含 model_config_ref、default_model 和 params_override；未设置时不返回。
`data.binding`	object	资源绑定，可包含工具、技能、知识库引用和通道绑定；未设置时不返回。
`data.policy_refs`	object	策略和工作流引用；未设置时不返回。
`data.workflow_refs`	object	策略和工作流引用；未设置时不返回。
`data.lifecycle`	object	生命周期信息，可包含 draft_ref 和 published_version；未设置时不返回。
`data.status`	string	智能体状态和资源版本。
`data.version`	integer	智能体状态和资源版本。
`data.source_type`	string	来源类型和来源引用；未设置来源引用时不返回。
`data.source_ref`	string	来源类型和来源引用；未设置来源引用时不返回。
`data.labels`	object	扩展标签、注释和元数据；未设置时不返回。
`data.annotations`	object	扩展标签、注释和元数据；未设置时不返回。
`data.metadata`	object	扩展标签、注释和元数据；未设置时不返回。
`data.created_by`	string	创建者和最近更新者 ID；未设置时不返回。
`data.updated_by`	string	创建者和最近更新者 ID；未设置时不返回。
`data.created_at`	string	创建和最近更新时间，采用 RFC 3339 格式。
`data.updated_at`	string	创建和最近更新时间，采用 RFC 3339 格式。

错误响应¶

响应示例

{
  "code": "ErrNotFound",
  "msg": null,
  "data": null
}

字段说明

常见 HTTP 错误

字段	类型	说明
`400`	`2`（`INVALID_ARGUMENT`）	路径参数或 `agent_workspace_id` 无效，或工作区范围不允许。建议：检查路径和查询参数。
`401`	`6`（`UNAUTHENTICATED`）	缺少有效身份凭据。建议：检查 API Key。
`403`	`5`（`PERMISSION_DENIED`）	当前身份没有读取智能体的权限。建议：使用有权限的身份，或联系管理员授权。
`404`	`ErrNotFound`	指定工作区范围内不存在该智能体。建议：检查智能体 ID 和所属工作区。
`503`	`15`（`UNAVAILABLE`）	智能体资源服务或其授权依赖暂不可用。建议：稍后重试。

后续操作¶

使用 data.id 调用查询智能体版本、查询资源绑定或查询运行策略。

最后更新于 2026 年 9 月 3 日