Create an agent

Create an agent resource in the current workspace. The caller needs permission to create agents in the workspace; do not pass workspace_id or user_id in the request body, the service will determine them from the request context.

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

Preparation before calling

Prepare a personal access token and target workspace ID that has 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: The workspace ID of the agent to be created, passed via the X-Workspace-ID Header and as workspace_id in the path.

Models, tools, skills, knowledge bases, and runtime environments referenced in the request body must be parsable.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/agents" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "销售助手",
    "instruction": {
      "system_prompt": "分析销售数据"
    },
    "runtime": {
      "provider": "astra",
      "profile": "default"
    }
  }'

Path parameters

Parameters	Type	Is it required	Description
workspace_id	string	Yes	The ID of the workspace where the agent is to be created.

Request body

Field	Type	Is it required	Description
name	string	Yes	Agent display name.
instruction	object	Yes	Command configuration, such as system_prompt, behavior_rules.
runtime	object	Yes	Run target containing provider and profile.
description	string	No	Agent description.
model	object	No	Model configuration, which can include model_config_ref, default_model, params_override.
binding	object	No	Resource bindings such as tools, skills, knowledge bases, and channels.
policy_refs	object	No	Operation, approval, and guardrail policy references.
workflow_refs	object	No	Workflow template reference.
status	string	No	Agent state; created as draft if not provided.
id	string	No	Agent ID. Generated by the server if not provided.
avatar_ref	string	No	Agent avatar and icon reference.
icon	string	No	Agent avatar and icon reference.
display_tags	string[]	No	Label used for display.
category	string	No	Agent classification.
sort_order	integer	No	Display the sort value.
labels	object	No	String key-value label and comment.
annotations	object	No	String key-value label and comment.
source_type	string	No	Agent source type: custom or system; if not provided, custom.
source_ref	string	No	Agent source reference.
metadata	object	No	Extended metadata.

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

Successful response

Returns 201 on success. data is a new agent.

{
  "code": 0,
  "data": {
    "id": "agent_01",
    "workspace_id": "ws_01",
    "schema_version": 1,
    "name": "销售助手",
    "instruction": {
      "system_prompt": "分析销售数据"
    },
    "runtime": {
      "provider": "matrixone",
      "profile": "default"
    },
    "status": "draft",
    "version": 1,
    "source_type": "custom",
    "created_by": "user_01",
    "updated_by": "user_01",
    "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	Agent ID and workspace ID.
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	Avatar reference; does not return if not set.
data.icon	string	Icon reference; does not return if not set.
data.display_tags	string[]	Display tag; does not return if not set.
data.category	string	Agent classification; does not return if not set.
data.sort_order	integer	Displays the sorting value; does not return if not set.
data.instruction	object	Command configuration.
data.runtime	object	Run target containing provider, profile, and optionally config.
data.model	object	Model configuration and resource binding; does not return if not set.
data.binding	object	Model configuration and resource binding; 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; does not return if not set.
data.status	string	Agent status and resource version.
data.version	integer	Agent status and resource version.
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": 2,
  "message": "invalid agent metadata"
}

Common HTTP errors

HTTP status code	error code	Common causes	Recommended actions
400	2（INVALID_ARGUMENT）	The request body, agent field, run target, or resource reference is invalid.	Check request fields and referenced resources.
401	6（UNAUTHENTICATED）	Lack of valid identity credentials.	Check API Key.
403	5（PERMISSION_DENIED）	The current identity does not have permission to create agents in the workspace.	Use an authorized identity, or contact the administrator for authorization.
409	4（ALREADY_EXISTS）	The same agent ID already exists in the current workspace.	Use a new ID, or query an existing agent.
503	15（UNAVAILABLE）	The agent resource service or its authorized dependencies are temporarily unavailable.	Try again later.

Follow-up operations

Log data.id. Use the ID to Query agent details to confirm the saving result; when you need to view the version, Query the agent version, when you need to configure binding, Query resource binding or Query execution strategy.

Last updated on Sep 3, 2026