通过 API 用自然语言搭建工作流¶

把数据来源、处理要求和结果保存位置发送给工作流助手，检查它生成的候选，接受候选后部署并运行。生成候选、接受候选、部署和运行是四个独立步骤。

准备环境和工作流助手¶

准备具有目标工作区访问和工作流创建权限的个人访问令牌及工作区 ID。示例使用 $AI_STUDIO_API_KEY 和 $WORKSPACE_ID。

查询智能体列表，查找活动的系统工作流助手。查询时不指定仅面向普通聊天的展示场景，以免遗漏目标。
保存同一列表项的 id 和 workspace_id，分别作为 $AGENT_ID 和 $AGENT_WORKSPACE_ID。智能体所属工作区与当前工作区可能不同。
获取智能体调用说明，使用目标工作区和智能体 ID 的路径，并在查询参数中指定智能体所属工作区。检查文本输入和 A2A 调用能力。
查询可用模型，从返回项的 model 取得 $MODEL。工作流助手生成请求必须填写 params.model；它用于生成工作流，与工作流中 AI 节点运行时选择的模型不同。模型配置列表不是可用模型列表，前者为空不能据此判断没有可用模型。

以下示例使用工作区级 A2A 路径。路径中的 $WORKSPACE_ID 是本次任务所在工作区，必须与请求头一致；查询参数 $AGENT_WORKSPACE_ID 才是智能体所属工作区。系统助手所属工作区为 system 时，仍将实际目标工作区填入路径。

如果 Agent Card 的 url 返回部署内部地址，使用本页的公开工作区级路径，不将凭据发送到该内部地址。通用 /v5/agents/card 与 /v5/agents/a2a 也是独立入口；其错误响应不能替代工作区级接口的具体诊断。

提交自然语言要求¶

通过 A2A message/send 发送需求。$MESSAGE_ID 是调用方为本条消息生成的唯一字符串；conversation_purpose 将此次对话标记为工作流用途。已有会话不是首次发送的必需条件。需要在同一会话中修订时，将上一任务的 result.contextId 填入新消息的 params.message.contextId，生成新的 messageId，并继续提供 params.model。

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/a2a?agent_workspace_id=$AGENT_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "generate-workflow-1",
    "method": "message/send",
    "params": {
      "model": "'"$MODEL"'",
      "metadata": {
        "conversation_purpose": "workflow"
      },
      "message": {
        "kind": "message",
        "role": "user",
        "messageId": "'"$MESSAGE_ID"'",
        "parts": [
          {
            "kind": "text",
            "text": "创建一条手动运行的文本清洗工作流：接收必填字符串 text，使用已注册的文本清洗算子，默认启用去除 HTML 标签。请实际提交可部署候选和运行表单，不要直接部署或运行。"
          }
        ]
      }
    }
  }'

将示例文本替换为实际需求。说明输入类型、全部处理步骤、输出格式、目标资源及失败处理。本页文本清洗示例不依赖外部业务数据或保存位置；需要文件产物时再增加保存步骤与目标资源。凭据应按平台支持的方式配置，不写入需求文本。

跟踪生成并检查候选¶

返回 A2A 任务时，将 result.id 保存为 $TASK_ID，使用同一智能体选择器查询：

curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/a2a?agent_workspace_id=$AGENT_WORKSPACE_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "get-workflow-candidate-1",
    "method": "tasks/get",
    "params": {
      "id": "'"$TASK_ID"'"
    }
  }'

submitted 和 working 表示尚未完成；input-required 和 auth-required 需要按返回要求补充信息或授权。failed、canceled、rejected 时停止进入部署步骤。完整调用和状态说明见由其他智能体调用。

任务 completed 后还要检查 result.artifacts 中是否存在可部署的 workflow.candidate 产物。候选的 metadata.matrixflow_type 标识其类型；数据分段 parts 中 kind=data 的 data 承载候选内容。保存该产物的 artifactId 为 $ARTIFACT_ID，不要使用会话 ID、消息 ID 或 JSON-RPC 请求 ID 替代它。

检查候选的 ok、workflow、runtime_fields、runtime_layout 和 diagnostics：

节点及输入绑定覆盖全部需求，引用的算子、模型和资源可用。
运行表单的必填字段、类型和保存位置正确。
候选可用，且没有阻止部署的诊断。

仅返回文字说明、工具日志或没有有效候选的完成任务，不能进入部署。需要修改时继续向工作流助手描述修改要求；使用新生成的候选引用重新接受，不修改候选对象后冒充原产物。

接受候选并部署¶

调用接受工作流候选，提交 $TASK_ID 与 $ARTIFACT_ID。接受操作保存候选的确认记录，不启动工作流。
按候选 runtime_fields.fields 准备 default_values，填写每个必填字段的真实值。调用创建工作流，提交 source_type=nl2dsl、已接受的 candidate_ref、execution_mode=one_shot 和这些默认值。必填运行值不齐全时无法部署；此分支不提交 dsl_yaml、runtime_fields、runtime_layout 或 design_graph，定义和表单来自服务端候选。
保存响应中的 data.workflow.id 和部署版本，通过查看工作流详情核对保存结果。

运行并验证结果¶

使用工作流 ID 启动工作流作业，通过 values 传入与候选运行表单一致的实际值，并按需设置 trigger_now=true。不提交 run_once；单次运行方式已由部署时的 execution_mode=one_shot 确定。

保存 data.workflow_run.execution_id，通过查看工作流作业详情和查看工作流作业结果核验终态和产物。部署成功或任务排队不代表处理成功；需要文件产物时，还应确认文件真实保存且能够下载。

无法继续时检查什么¶

返回 workflow agent model is required：补充 params.model，值来自可用模型列表，不是模型配置 ID。
返回任务完成但没有 workflow.candidate：保存任务与工具结果，在同一会话中要求助手继续生成或修订；不能仅凭 completed 部署。
返回 HTTP 500 和通用 ErrServer：保存请求时间、响应请求/追踪 ID 和 JSON-RPC ID。按由其他智能体调用的工作区级接口核对具体错误，不将 500 直接解释为模型、权限或智能体不存在。
发送请求后未取得确定结果：可先查询运行时任务列表，按智能体、上下文和输入摘要核对任务；也可查询会话列表，查找本次会话与活动任务，取得真实任务 ID 后查询。不要把 JSON-RPC ID、消息 ID 或会话 ID 当作 task ID，也不要盲目重复生成。

最后更新于 2026 年 9 月 15 日