---
orphan: true
---

# 接受工作流候选

接受工作流助手生成并校验的候选，保存后续部署需要的确认记录。本接口不部署或运行工作流。

```text
POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/accept
```

## 调用前准备

先[通过 API 用自然语言搭建工作流](build-with-api.md#跟踪生成并检查候选)，取得已完成任务中的有效候选。候选必须属于当前工作区及当前调用用户。

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

## 请求示例

`$TASK_ID` 来自生成任务的 `result.id`，`$ARTIFACT_ID` 来自同一任务候选产物的 `artifactId`。`$AI_STUDIO_API_KEY` 和 `$WORKSPACE_ID` 分别为调用凭据与目标工作区。

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-candidates/accept" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "candidate_ref": {
      "task_id": "'"$TASK_ID"'",
      "artifact_id": "'"$ARTIFACT_ID"'"
    }
  }'
```

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `candidate_ref` | object | 是 | 待接受的服务端候选引用。 |
| `candidate_ref.task_id` | string | 是 | 生成候选的已完成 A2A 任务 ID。 |
| `candidate_ref.artifact_id` | string | 是 | 该任务中的工作流候选产物 ID。 |

只提交引用。不要提交候选正文、DSL、表单、画布或 `runtime_context`。服务端读取并检查原始产物，不能使用客户端构造的候选替换它。

## 成功响应

成功时返回 HTTP 200 和接受记录，其中保留完整候选。接受记录用于后续部署；接受成功不表示已经创建工作流。

以下节选用于后续部署的引用和接受时间；实际响应还包含下表所列的 `data.candidate`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "candidate_ref": {
      "task_id": "task_01",
      "artifact_id": "workflow_candidate_01"
    },
    "accepted_at": "2026-09-15T02:00:00Z"
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 响应说明。 |
| `data.candidate_ref` | object | 已接受的候选引用。 |
| `data.candidate_ref.task_id` | string | 生成任务 ID。 |
| `data.candidate_ref.artifact_id` | string | 候选产物 ID。 |
| `data.accepted_at` | string | 服务端记录的接受时间。 |
| `data.candidate` | object | 服务端保存的候选内容。 |
| `data.candidate.ok` | boolean | 候选是否有效。 |
| `data.candidate.candidate_id` | string | 候选标识。 |
| `data.candidate.summary` | string | 候选摘要；有值时返回。 |
| `data.candidate.message` | string | 候选说明；有值时返回。 |
| `data.candidate.workflow` | object | 用于部署的工作流定义。 |
| `data.candidate.runtime_fields` | object | 运行输入表单；有配置时返回。 |
| `data.candidate.runtime_layout` | object | 表单布局；有配置时返回。 |
| `data.candidate.diagnostics` | object（对象数组） | 编译诊断；有值时返回。 |
| `data.candidate.diagnostics[].message` | string | 诊断说明。 |
| `data.candidate.diagnostics[].severity` | string | 诊断级别；有值时返回。 |
| `data.candidate.diagnostics[].suggestion` | string | 修改建议；有值时返回。 |

字段路径中的 `[]` 表示数组中的每一项。例如，`diagnostics[].message` 表示每项诊断的说明。候选还可包含源码、编译版本、摘要及自定义算子快照；保留原始响应用于核对，不将这些内容重新作为部署请求提交。

## 错误响应

```json
{
  "code": "ErrParamInvalid",
  "data": null,
  "msg": "候选 task_id 和 artifact_id 不能为空"
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - 400
  - `ErrParamInvalid`
  - 引用缺失、候选校验失败，或请求包含不支持的字段。
  - 核对任务和产物来源，只提交候选引用。
* - 409
  - `workflow_candidate_not_accepted`
  - 候选接受状态不满足当前操作。
  - 核对实际候选及其接受记录，不自行构造接受状态。
* - 500
  - `ErrServer`
  - 服务端处理失败。
  - 保留请求时间与错误响应，联系管理员排查。
* - 503
  - `ErrServiceUnavailable`
  - 依赖服务不可用。
  - 恢复服务后再操作。
```

## 后续操作

使用 `data.candidate_ref` [创建工作流](create-workflow.md#自然语言候选部署)，选择自然语言候选部署方式。