---
orphan: true
---

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

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

## 准备环境和工作流助手

准备具有目标工作区访问和工作流创建权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)及[工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id)。示例使用 `$AI_STUDIO_API_KEY` 和 `$WORKSPACE_ID`。

1. [查询智能体列表](../../agents/agents/list-agents.md)，查找活动的系统工作流助手。查询时不指定仅面向普通聊天的展示场景，以免遗漏目标。
2. 保存同一列表项的 `id` 和 `workspace_id`，分别作为 `$AGENT_ID` 和 `$AGENT_WORKSPACE_ID`。智能体所属工作区与当前工作区可能不同。
3. [获取智能体调用说明](../../agents/agent-invocation/get-agent-card.md)，使用目标工作区和智能体 ID 的路径，并在查询参数中指定智能体所属工作区。检查文本输入和 A2A 调用能力。
4. [查询可用模型](../../agents/model-configurations/list-available-models.md)，从返回项的 `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`。

```bash
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`，使用同一智能体选择器查询：

```bash
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` 时停止进入部署步骤。完整调用和状态说明见[由其他智能体调用](../../agents/agent-invocation/call-agent-from-agent.md)。

任务 `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`：

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

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

## 接受候选并部署

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

## 运行并验证结果

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

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

## 无法继续时检查什么

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