创建智能体

在当前工作区创建智能体资源。调用者需要在工作区中创建智能体的权限；不要在请求体中传入 workspace_id 或 user_id，服务会从请求上下文确定它们。

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

调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

请求体中引用的模型、工具、技能、知识库和运行环境必须可解析。

请求体

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/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"
    }
  }'

字段说明

请求字段

字段	类型	必填	说明
name	string	是	智能体显示名称。
instruction	object	是	指令配置，例如 system_prompt、behavior_rules。
runtime	object	是	运行目标，包含 provider 和 profile。
description	string	否	智能体说明。
model	object	否	模型配置，可包含 model_config_ref、default_model、params_override。
binding	object	否	工具、技能、知识库和通道等资源绑定。
policy_refs	object	否	运行、审批和护栏策略引用。
workflow_refs	object	否	工作流模板引用。
status	string	否	智能体状态；未提供时创建为 draft。
id	string	否	智能体 ID。未提供时由服务端生成。
avatar_ref	string	否	智能体头像和图标引用。
icon	string	否	智能体头像和图标引用。
display_tags	string（字符串数组）	否	用于展示的标签。
category	string	否	智能体分类。
sort_order	integer	否	展示排序值。
labels	object	否	字符串键值标签和注释。
annotations	object	否	字符串键值标签和注释。
source_type	string	否	智能体来源类型：custom 或 system；未提供时为 custom。
source_ref	string	否	智能体来源引用。
metadata	object	否	扩展元数据。

请求参数

请求示例

curl -X POST "https://api.moi.matrixorigin.cn/v5/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"
    }
  }'

参数说明

路径参数

字段	类型	必填	说明
workspace_id	string	是	要创建智能体的工作区 ID。

成功响应

响应示例

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

字段说明

成功时返回 201。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	指令配置。
data.runtime	object	运行目标，包含 provider、profile 和可选 config。
data.model	object	模型配置和资源绑定；未设置时不返回。
data.binding	object	模型配置和资源绑定；未设置时不返回。
data.policy_refs	object	策略和工作流引用；未设置时不返回。
data.workflow_refs	object	策略和工作流引用；未设置时不返回。
data.lifecycle	object	生命周期信息；未设置时不返回。
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": 2,
  "message": "invalid agent metadata"
}

字段说明

常见 HTTP 错误

字段	类型	说明
400	2（INVALID_ARGUMENT）	请求体、智能体字段、运行目标或资源引用无效。建议：检查请求字段和引用资源。
401	6（UNAUTHENTICATED）	缺少有效身份凭据。建议：检查 API Key。
403	5（PERMISSION_DENIED）	当前身份没有在工作区创建智能体的权限。建议：使用有权限的身份，或联系管理员授权。
409	4（ALREADY_EXISTS）	当前工作区中已存在相同智能体 ID。建议：使用新的 ID，或查询已有智能体。
503	15（UNAVAILABLE）	智能体资源服务或其授权依赖暂不可用。建议：稍后重试。

后续操作

记录 data.id。用该 ID 查询智能体详情确认保存结果；需要查看版本时查询智能体版本，需要配置绑定时查询资源绑定或查询运行策略。

最后更新于 2026 年 9 月 8 日