创建工作流

在当前工作区创建工作流定义。创建成功后不会自动启动作业。

POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments

调用前准备

权限要求取决于部署方式和引用资源。除工作流创建权限外，还可能需要计算资源和引用资源的使用权限。传入已有工作流 ID 也不能只依靠管理权限完成这个 POST。

准备具有创建工作流权限的个人访问令牌、目标工作区 ID。手写方式准备工作流 DSL。自然语言方式准备已接受的工作流候选。

请求体

示例使用 jq 构造 JSON 请求体。先安装 jq 并设置所需环境变量，不要再次对变量值进行 JSON 编码。

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和示例中的工作流名称、DSL 替换为实际值。

输入示例

单次运行

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "daily-import",
  "dsl_yaml": "workflow:\n  name: daily-import\n  root: main\nroot:\n  chain: []\n",
  "execution_mode": "one_shot"
}'

动态服务

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "order-query-service",
  "dsl_yaml": "workflow:\n  name: order-query-service\n  root: main\nroot:\n  chain: []\n",
  "execution_mode": "dynamic_service",
  "dynamic_service": {
    "service_name": "order-query-service",
    "input_schema": "{\"type\":\"object\"}",
    "output_schema": "{\"type\":\"object\"}"
  }
}'

定时触发

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "daily-import",
  "dsl_yaml": "workflow:\n  name: daily-import\n  root: main\nroot:\n  chain: []\n",
  "execution_mode": "cron",
  "cron_expression": "0 2 * * *"
}'

卷触发

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "volume-import",
  "dsl_yaml": "workflow:\n  name: volume-import\n  root: main\nroot:\n  chain: []\n",
  "execution_mode": "volume_trigger",
  "volume_trigger": {
    "volume_id": 1001,
    "enabled": true
  }
}'

自然语言候选部署

curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-deployments" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg TASK_ID "$TASK_ID" --arg ARTIFACT_ID "$ARTIFACT_ID" '
{
  "name": "ticket-analysis",
  "source_type": "nl2dsl",
  "candidate_ref": {
    "task_id": $TASK_ID,
    "artifact_id": $ARTIFACT_ID
  },
  "execution_mode": "one_shot",
  "default_values": {
    "text": "需要处理的文本"
  }
}
')"

参数说明

手写 DSL 必须包含可部署的根节点和至少一个有效节点，空的 chain: [] 不能部署。 自然语言生成的工作流使用已接受的候选引用部署。

manual_dsl 使用 DSL，manual_mowl 使用工作流对象，自然语言生成使用相应候选定义。填写已有 workflow_id 会进入重新部署处理，而非单纯新建。通知配置的请求头要使用完整原值并保护凭据。

动态服务的输入、输出 Schema 必须以 JSON 文本提供。运行规格文本可省略，结果方式默认 oneshot。JSON 语法通过不等于已经完成完整 Schema 语义校验。

创建工作流时必须提供 name。source_type 省略时按手写 DSL（manual_dsl）处理，此时必须提供 dsl_yaml。使用自然语言候选时，填写 source_type=nl2dsl 和已接受的 candidate_ref，不提交 dsl_yaml。省略 workflow_id 时创建新工作流。提供时进入已有工作流的重新部署分支，仍需创建权限及目标资源权限。不要传 runtime_context。

单次运行

字段	类型	是否必填	说明
name	string	是	工作流名称。
description	string 或 null	否	工作流说明。
execution_mode	string 或 null	否	填写 volume_trigger。
cron_expression	string 或 null	否	Cron 表达式。
dsl_yaml	string 或 null	否	手写 DSL 时必填。自然语言候选部署时不传。
compute_resource_id	string 或 null	否	关联的计算资源 ID。
runtime_fields	object 或 null	否	运行时输入表单配置。
runtime_fields.title	string 或 null	否	标题文本。
runtime_fields.description	string 或 null	否	当前对象的说明。
runtime_fields.fields	object（对象数组） 或 null	否	字段定义。
runtime_fields.fields[].field_id	string 或 null	否	表单字段 ID，用于运行输入和布局关联。
runtime_fields.fields[].label	string 或 null	否	显示标签。
runtime_fields.fields[].description	string 或 null	否	当前对象的说明。
runtime_fields.fields[].widget	string 或 null	否	输入控件类型。
runtime_fields.fields[].json_type	string 或 null	否	JSON 类型。
runtime_fields.fields[].model_type	string 或 null	否	模型类型标签。
runtime_fields.fields[].required	boolean 或 null	否	是否必填。
runtime_fields.fields[].default	JSON 值 或 null	否	默认值。
runtime_fields.fields[].has_default	boolean 或 null	否	是否有默认值。
runtime_fields.fields[].placeholder	string 或 null	否	输入提示。
runtime_fields.fields[].pattern	string 或 null	否	字符串匹配模式。
runtime_fields.fields[].runtime_config_path	string 或 null	否	运行配置中的字段路径。
runtime_fields.fields[].section	string 或 null	否	所属区块。
runtime_fields.fields[].group	string 或 null	否	所属分组。
runtime_fields.fields[].on_value	string 或 null	否	启用时的值。
runtime_fields.fields[].off_value	string 或 null	否	关闭时的值。
runtime_fields.fields[].hidden	boolean 或 null	否	是否隐藏。
runtime_fields.fields[].read_only	boolean 或 null	否	是否只读。
runtime_fields.fields[].sensitive	boolean 或 null	否	是否含敏感值。
runtime_fields.fields[].options	object（对象数组） 或 null	否	可选项。
runtime_fields.fields[].options[].label	string 或 null	否	显示标签。
runtime_fields.fields[].options[].value	JSON 值 或 null	否	值。
runtime_fields.fields[].options[].description	string 或 null	否	当前对象的说明。
runtime_fields.fields[].min	number 或 null	否	最小值。
runtime_fields.fields[].max	number 或 null	否	最大值。
runtime_fields.fields[].accept	string（字符串数组） 或 null	否	允许的文件类型。
runtime_fields.fields[].resource_type	string 或 null	否	资源类型。
runtime_fields.fields[].visible_when	object 或 null	否	显示条件。
runtime_fields.fields[].visible_when.field_id	string 或 null	否	表单字段 ID，用于运行输入和布局关联。
runtime_fields.fields[].visible_when.value	JSON 值 或 null	否	值。
runtime_fields.fields[].bind_to	string 或 object 或 null	否	值绑定位置。
runtime_fields.fields[].owner_node_name	string 或 null	否	该字段所属节点名称。
runtime_fields.fields[].owner_node_id	string 或 null	否	该字段所属节点的定位名。
runtime_layout	object 或 null	否	运行时输入表单的布局配置。
runtime_layout.version	string 或 null	否	当前资源版本。
runtime_layout.groups	object（对象数组） 或 null	否	字段分组。
runtime_layout.groups[].group_id	string 或 null	否	布局分组 ID。
runtime_layout.groups[].title	string 或 null	否	标题文本。
runtime_layout.groups[].node_name	string 或 null	否	显示信息。
runtime_layout.groups[].node_id	string 或 null	否	节点 ID。
runtime_layout.groups[].field_ids	string（字符串数组） 或 null	否	分组内字段 ID。
runtime_layout.guide	object 或 null	否	表单使用指南。
runtime_layout.guide.lead	string 或 null	否	引导说明。
runtime_layout.guide.paths	object（对象数组） 或 null	否	路径列表。
runtime_layout.guide.paths[].id	string 或 null	否	当前对象的 ID。
runtime_layout.guide.paths[].label	string 或 null	否	显示标签。
runtime_layout.guide.paths[].description	string 或 null	否	当前对象的说明。
runtime_layout.guide.paths[].field_ids	string（字符串数组） 或 null	否	分组内字段 ID。
runtime_layout.guide.groups	object（对象数组） 或 null	否	字段分组。
runtime_layout.guide.groups[].id	string 或 null	否	当前对象的 ID。
runtime_layout.guide.groups[].label	string 或 null	否	显示标签。
runtime_layout.guide.groups[].path_ids	string（字符串数组） 或 null	否	路径 ID 列表。
runtime_layout.guide.groups[].field_ids	string（字符串数组） 或 null	否	分组内字段 ID。
runtime_layout.guide.fields	object（对象数组） 或 null	否	字段定义。
runtime_layout.guide.fields[].field_id	string 或 null	否	表单字段 ID，用于运行输入和布局关联。
runtime_layout.guide.fields[].role	string 或 null	否	关联角色。
runtime_layout.guide.fields[].note	string 或 null	否	补充说明。
runtime_layout.guide.fields[].group_id	string 或 null	否	布局分组 ID。
runtime_layout.guide.fixed	object（对象数组） 或 null	否	是否固定。
runtime_layout.guide.fixed[].label	string 或 null	否	显示标签。
runtime_layout.guide.fixed[].value	string 或 null	否	值。
default_values	object 或 null	否	运行时输入表单的默认值。对象允许扩展键。
design_graph	object 或 null	否	工作流设计图配置。对象允许扩展键。
volume_trigger	object 或 null	否	卷触发配置。运行时输入表单未提供卷 ID 时，必须填写其中的 volume_id。
volume_trigger.volume_id	integer 或 null	否	卷 ID。运行时输入表单未提供卷 ID 时必填。
volume_trigger.enabled	boolean 或 null	否	是否启用卷触发。
volume_trigger.auto_dispatch_enabled	boolean 或 null	否	是否自动派发卷触发的运行。
volume_trigger.vars_json	string 或 null	否	卷触发时使用的变量 JSON 文本。
volume_trigger.max_concurrency	integer 或 null	否	卷触发运行的最大并发数。
dynamic_service	object 或 null	否	动态服务配置。
dynamic_service.service_name	string 或 null	否	动态服务名称。
dynamic_service.input_schema	string 或 null	条件必填	显式提交 dynamic_service 时必填的 JSON Schema 文本。只做当前服务支持的格式校验。
dynamic_service.output_schema	string 或 null	条件必填	显式提交 dynamic_service 时必填的 JSON Schema 文本。只做当前服务支持的格式校验。
dynamic_service.result_mode	string 或 null	否	动态服务的结果模式。
dynamic_service.runtime_spec_json	string 或 null	否	动态服务运行时配置的 JSON 文本。
notification_config	object 或 null	否	终态通知配置。
notification_config.type	string	是	类型。
notification_config.url	string	是	通知地址。
notification_config.method	string 或 null	否	HTTP 方法。
notification_config.headers	object 或 null	否	通知请求头。对象允许扩展键。
notification_config.timeout	integer 或 null	否	超时秒数。
notification_config.worker_id	JSON 值	否	Worker ID。取值为 空字符串、null。
notification_config.message	JSON 值	否	通知消息。取值为 空字符串、null。
notification_config.notify_node_states	string（字符串数组） 或 null	否	节点通知状态。
notification_config.notify_node_ids	string（字符串数组） 或 null	否	通知节点 ID。
notification_config.notify_workflow_states	array	是	工作流通知状态。
workflow_id	string 或 null	否	工作流 ID。
source_type	string 或 null	否	本页介绍 manual_dsl（默认）和 nl2dsl。使用记忆治理 WorkItem 的 DSL 填写。
workflow	object 或 null	否	MOWL 工作流定义。
workflow.name	string 或 null	否	当前对象的名称。
workflow.root	string 或 null	否	根网络名称。
workflow.user_id	string 或 null	否	用户身份标识。
workflow.nets	object 或 null	否	网络定义，键为网络名称。对象允许扩展键。
workflow.nets["键"].transient	boolean 或 null	否	是否为临时对象。
workflow.nets["键"].nodes	object 或 null	否	节点列表。对象允许扩展键。
workflow.nets["键"].nodes["键"].id	string 或 null	否	当前对象的 ID。
workflow.nets["键"].nodes["键"].version	string 或 null	否	当前资源版本。
workflow.nets["键"].nodes["键"].in_connector	object 或 null	否	输入连接配置。
workflow.nets["键"].nodes["键"].in_connector.type	string 或 null	否	类型。
workflow.nets["键"].nodes["键"].in_connector.nodes	string（字符串数组） 或 null	否	节点列表。
workflow.nets["键"].nodes["键"].in_connector.queries	string（字符串数组） 或 null	否	查询语句列表。
workflow.nets["键"].nodes["键"].out_connector	object 或 null	否	输出连接配置。
workflow.nets["键"].nodes["键"].out_connector.type	string 或 null	否	类型。
workflow.nets["键"].nodes["键"].out_connector.nodes	string（字符串数组） 或 null	否	节点列表。
workflow.nets["键"].nodes["键"].out_connector.queries	string（字符串数组） 或 null	否	查询语句列表。
workflow.nets["键"].nodes["键"].var_map	object 或 null	否	变量映射。对象允许扩展键。
workflow.provenance	object 或 null	否	定义来源信息，保存时由服务处理。
workflow.provenance.task_id	string 或 null	否	关联标识。
workflow.provenance.artifact_id	string 或 null	否	关联标识。
workflow.provenance.candidate_id	string 或 null	否	关联标识。
workflow.provenance.catalog_revision	string 或 null	否	目录修订号。
workflow.provenance.catalog_snapshot_digest	string 或 null	否	目录快照摘要。
workflow.provenance.source_digest	string 或 null	否	源定义摘要。
workflow.provenance.artifact_digest	string 或 null	否	产物摘要。
workflow.provenance.envelope_digest	string 或 null	否	信封摘要。
workflow.provenance.syntax_version	string 或 null	否	语法版本。
workflow.provenance.compiler_version	string 或 null	否	编译器版本。
workflow.provenance.source_code	string 或 null	否	来源代码。
candidate_ref	object 或 null	否	nl2dsl 时必填，引用已接受的生成候选。
candidate_ref.task_id	string 或 null	否	生成候选的 A2A 任务 ID。
candidate_ref.artifact_id	string 或 null	否	同一任务返回的候选产物 ID。
dsl_yaml	string	条件必填	手写 DSL 时必填。自然语言候选部署时不传。
execution_mode	string	是	填写 dynamic_service。 填写 cron。 填写 volume_trigger。
dynamic_service	object	是	动态服务配置。
dynamic_service.service_name	string	否	动态服务名称。
dynamic_service.input_schema	string	条件必填	显式提交 dynamic_service 时必填的 JSON Schema 文本。只做当前服务支持的格式校验。
dynamic_service.output_schema	string	条件必填	显式提交 dynamic_service 时必填的 JSON Schema 文本。只做当前服务支持的格式校验。
dynamic_service.result_mode	string	否	动态服务的结果模式。
dynamic_service.runtime_spec_json	string	否	动态服务运行时配置的 JSON 文本。
cron_expression	string	是	Cron 表达式。
volume_trigger	object	否	卷触发配置。运行时输入表单未提供卷 ID 时，必须填写其中的 volume_id。
volume_trigger.volume_id	integer	条件必填	卷 ID。运行时输入表单未提供卷 ID 时必填。
volume_trigger.enabled	boolean	否	是否启用卷触发。
volume_trigger.auto_dispatch_enabled	boolean	否	是否自动派发卷触发的运行。
volume_trigger.vars_json	string	否	卷触发时使用的变量 JSON 文本。
volume_trigger.max_concurrency	integer	否	卷触发运行的最大并发数。

其他可选字段可参见“单次运行”页签。

其他可选字段可参见“单次运行”页签。

其他可选字段可参见“单次运行”页签。

本例要求已经取得并接受有效的工作流候选。将接受响应中的 data.candidate_ref.task_id 和 data.candidate_ref.artifact_id 分别保存为 $TASK_ID、$ARTIFACT_ID。

服务端读取该候选的定义。此方式不接受调用方提交 dsl_yaml、runtime_fields、runtime_layout 或 design_graph。需要调整节点或表单时，应重新生成并接受候选。default_values 提供候选运行表单的默认值，字段名称和类型须与候选表单一致。one_shot 候选部署时，必填运行字段必须已经有值。缺失时部署失败，不能等到启动作业时才补充。

候选部署示例假定候选包含必填字符串 text。按实际 runtime_fields.fields 替换。动态服务的调用输入在每次调用时提供，不参与这项部署完整性检查。

候选必须属于当前工作区和调用用户，源任务已完成，并具有匹配的服务端接受记录。未接受候选就部署时，返回 HTTP 409，错误代码为 ErrConflict。不能用任意 YAML、候选对象或自行构造的 ID 代替候选引用。

成功响应

响应示例

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workflow": {
      "id": "wf-001",
      "name": "daily-import",
      "source_type": "manual_dsl",
      "execution_mode": "one_shot",
      "draft_id": "draft-001",
      "status": "ready"
    },
    "deployment": {
      "workflow_app_id": "wf-001",
      "workflow_def_id": "def-001",
      "workflow_version_id": "ver-001",
      "workflow_name": "daily-import",
      "version": 1,
      "execution_mode": "one_shot"
    }
  }
}

字段说明

字段	类型	说明
code	string	成功代码。
msg	string	响应信息。
data	object	本次操作返回的数据。
data.workflow	object	MOWL 工作流定义。
data.workflow.id	string	当前对象的 ID。
data.workflow.name	string	当前对象的名称。
data.workflow.source_type	string	来源类型。取值为 nl2dsl、manual_dsl、manual_mowl、system、agent_automation_task
data.workflow.execution_mode	string	运行方式。取值为 one_shot、volume_trigger、cron、dynamic_service、task_by_version
data.workflow.cron_expression	string	Cron 表达式。
data.workflow.draft_id	string	关联标识。
data.workflow.candidate_id	string	关联标识。
data.workflow.status	string	状态。取值为 ready、disabled、paused
data.deployment	object	部署结果。
data.deployment.workflow_app_id	string	工作流应用 ID。
data.deployment.workflow_def_id	string	工作流定义 ID。
data.deployment.workflow_version_id	string	工作流版本 ID。
data.deployment.workflow_name	string	工作流名称。
data.deployment.version	integer	工作流版本号。
data.deployment.execution_mode	string	已发布的运行方式。取值为 one_shot、volume_trigger、cron、dynamic_service、task_by_version
data.deployment.previous_workflow_version_id	string	上一工作流版本 ID。更新已有工作流版本时返回。
data.deployment.disabled_cron_task_ids	string（字符串数组）	已停用的定时任务 ID。替换定时任务时返回。
data.deployment.volume_trigger	object	卷触发配置。卷触发时返回。
data.deployment.volume_trigger.id	integer	当前对象的 ID。
data.deployment.volume_trigger.volume_id	integer	关联标识。
data.deployment.volume_trigger.workflow_version_id	string	关联标识。
data.deployment.volume_trigger.enabled	boolean	是否启用。
data.deployment.volume_trigger.created_by	string	创建者身份标识。
data.deployment.volume_trigger.updated_by	string	最近更新者身份标识。
data.deployment.volume_trigger.created_at	integer	创建时间。
data.deployment.volume_trigger.updated_at	integer	最近更新时间。
data.deployment.volume_trigger.vars	string	运行变量。
data.deployment.volume_trigger.max_concurrency	integer	最大并发数。
data.deployment.volume_trigger.auto_dispatch_enabled	boolean	是否自动分发。
data.deployment.volume_trigger.workflow_app_id	string	关联标识。
data.deployment.cron_task	object	定时任务信息。定时触发时返回。
data.deployment.cron_task.id	string	当前对象的 ID。
data.deployment.cron_task.workspace_id	string	所属工作区 ID。
data.deployment.cron_task.name	string	当前对象的名称。
data.deployment.cron_task.cron_expression	string	Cron 表达式。
data.deployment.cron_task.data	string	数据内容。
data.deployment.cron_task.vars	string	运行变量。
data.deployment.cron_task.status	integer	状态。
data.deployment.cron_task.created_at	string	创建时间。
data.deployment.cron_task.updated_at	string	最近更新时间。
data.deployment.cron_task.workflow_version_id	string	关联标识。
data.deployment.cron_task.compute_resource_id	string	关联标识。
data.deployment.dynamic_service	object	动态服务信息。动态服务时返回。
data.deployment.dynamic_service.service_name	string	显示信息。
data.deployment.dynamic_service.invoke	object	调用配置。
data.deployment.dynamic_service.invoke.method	string	HTTP 方法。
data.deployment.dynamic_service.invoke.path	string	字段路径。
data.deployment.dynamic_service.invoke.result_mode	string	结果返回方式。
data.deployment.dynamic_service.invoke.body_example	object	请求体示例对象允许扩展键。
data.deployment.dynamic_service.version	object	当前资源版本。
data.deployment.dynamic_service.version.id	string	当前对象的 ID。
data.deployment.dynamic_service.version.workspace_id	string	所属工作区 ID。
data.deployment.dynamic_service.version.workflow_id	string	工作流 ID。
data.deployment.dynamic_service.version.version	integer	当前资源版本。
data.deployment.dynamic_service.version.workflow	JSON 值	MOWL 工作流定义。
data.deployment.dynamic_service.version.status	string	状态。取值为 draft、published、deprecated
data.deployment.dynamic_service.version.created_by	string	创建者身份标识。
data.deployment.dynamic_service.version.created_at	string	创建时间。
data.deployment.dynamic_service.version.published_at	string	时间信息。
data.deployment.dynamic_service.version.type	integer	类型。取值为 1、2
data.deployment.dynamic_service.version.input_schema	string	输入定义的 JSON 文本。
data.deployment.dynamic_service.version.output_schema	string	输出定义的 JSON 文本。
data.deployment.dynamic_service.version.result_mode	integer	结果返回方式。取值为 0、1、2
data.deployment.dynamic_service.version.description	string	当前对象的说明。
data.deployment.dynamic_service.version.runtime_spec_json	string	运行规格的 JSON 文本。
data.warnings	string（字符串数组）	提示信息。

错误响应

部署时会分阶段保存记录并创建关联算子。尚未完成的记录可能处于待处理状态，不出现在列表中。部署失败后，部分记录可能仍保留。请保存请求和追踪标识，供后续排查。

保存响应中的请求和追踪标识。重复提交候选或请求标识仍会检查内容摘要与调用身份。错误后不要更换标识自动重试。

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效"
}

字段说明

字段	类型	说明
code	string	错误代码。
msg	string	错误说明。

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	ErrParamInvalid、ErrWorkspaceRequired	请求字段、工作区或操作前置条件无效。	修正参数后再提交。
401	Unauthorized	认证凭据缺失或无效。	检查凭据类型、有效期及认证头。
403	ErrForbidden	当前身份或有效角色无执行该操作的权限。	使用有权限的身份，或联系管理员授权。
404	ErrNotFound	目标对象或所需引用未找到。	核对对象标识、所属工作区和当前状态。
409	ErrConflict	资源状态、请求内容或并发条件冲突。	重新读取当前状态和版本，按实际结果处理。
500	ErrServer	内部处理失败；写操作可能已有部分效果。	保留请求和追踪信息，先核对当前结果。
503	ErrServiceUnavailable	业务、运行时或授权依赖暂不可用。	恢复依赖后先核对已有结果，不自动重复写入。

最后更新于 2026 年 10 月 19 日