Query agent details

Read an agent’s complete metadata, run targets, model configuration, resource bindings and policy references. Optionally specify the workspace to which the agent belongs; this value can only be the current workspace or the system workspace.

GET 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 the X-Workspace-ID Header and as workspace_id in the path.

• $AGENT_ID: The agent ID to query, as agent_id in the path.

Request example

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

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	Current workspace ID, must be consistent with X-Workspace-ID.
agent_id	string	Yes	The agent ID to be queried.

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.

Successful response

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

{
  "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"
  }
}

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	Workspace where the agent definition belongs.
data.schema_version	integer	Agent metadata structure version.
data.name	string	Agent name and description; will not be returned if no description is set.
data.description	string	Agent name and description; will not be returned if no description is set.
data.avatar_ref	string	Display metadata; does not return if not set.
data.icon	string	Display metadata; does not return if not set.
data.display_tags	array of string	Display tags; does not return if not set.
data.category	string	Classification and display sorting value; not returned if not set.
data.sort_order	integer	Classification and display sorting value; not returned if not set.
data.instruction	object	Command configuration, which can include system_prompt, behavior_rules, output_contract_ref and variables_schema.
data.runtime	object	Run target containing provider, profile, and optionally config.
data.model	object	Model configuration, can contain model_config_ref, default_model and params_override; does not return if not set.
data.binding	object	Resource binding, which can include tools, skills, knowledge base references and channel bindings; does not return if not set.
data.policy_refs	object	Policy and workflow reference; not returned if not set.
data.workflow_refs	object	Policy and workflow reference; not returned if not set.
data.lifecycle	object	Life cycle information, which can include draft_ref and published_version; does not return if not set.
data.status	string	Agent status.
data.version	integer	Current resource version of the agent definition.
data.source_type	string	Source type and source reference; not returned when source reference is not set.
data.source_ref	string	Source type and source reference; not returned when source reference is not set.
data.labels	object	Extended tags, comments, and metadata; not returned if not set.
data.annotations	object	Extended tags, comments, and metadata; not returned if not set.
data.metadata	object	Extended tags, comments, and metadata; not returned if not set.
data.created_by	string	Creator and last updater ID; not returned if not set.
data.updated_by	string	Creator and last updater ID; not returned if not set.
data.created_at	string	Creation and last update times, in RFC 3339 format.
data.updated_at	string	Creation and last update times, in RFC 3339 format.

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

Error response

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

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	The path parameter or agent_workspace_id is invalid, or the workspace scope does not allow it.	Check path and query parameters.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to read the agent.	Use an authorized identity, or contact the administrator for authorization.
404	ErrNotFound	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 data.id to call Query the agent version, Query resource binding or Query execution strategy.

Last updated on Sep 11, 2026