# 生成智能体候选方案

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

提交一个完整的智能体候选配置，由服务校验并保存候选版本。

```text
POST https://api.moi.matrixorigin.cn/v5/workspaces/{workspace_id}/agent-builder/candidates
```

## 调用前准备

先[查询智能体搭建可用资源](list-authoring-resources.md)取得资源清单。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

## 请求示例

示例中的凭据和资源标识需替换为当前调用者的实际值。

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/workspaces/$WORKSPACE_ID/agent-builder/candidates" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "create",
  "conversation_id": "<CONVERSATION_ID>",
  "raw_advice": "创建一个回答产品问题的智能体。",
  "resources": {
    "models": [],
    "tools": [],
    "skills": [],
    "knowledge_bases": []
  },
  "candidate": {
    "agent_id": "<AGENT_ID>",
    "name": "产品助手",
    "description": "回答产品问题。",
    "model_name": "<MODEL_NAME>",
    "tool_names": [],
    "skill_names": [],
    "knowledge_base_names": [],
    "channel_bindings": [],
    "agent_md": "# 产品助手",
    "change_reason": "初始创建"
  }
}'
```

<span id="请求参数"></span>

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `workspace_id` | string | 是 | 工作区 ID。 |

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `mode` | string | 是 | 构建模式；创建新智能体使用 create；取值：`create`、`revise`。 |
| `conversation_id` | string | 是 | 本次搭建所属会话 ID；不能为空。 |
| `task_id` | string | 否 | 关联的任务 ID。 |
| `source_agent_id` | string | 否 | 来源智能体 ID。 |
| `source_agent_workspace_id` | string | 否 | 来源智能体工作区；不能为空。 |
| `source_version` | string | 否 | 来源版本。 |
| `raw_advice` | string | 是 | 本次创建或修改的原始要求。 |
| `advice_user_id` | string | 否 | 提议用户ID。 |
| `resources` | object | 是 | [选择搭建资源](list-authoring-resources.md#选择搭建资源)中返回的资源集合。 |
| `resources.models` | object（对象数组） | 对象提供时 | 模型集合。 |
| `resources.models[].name` | string | 对象提供时 | 名称；不能为空。 |
| `resources.models[].model_name` | string | 否 | 模型名称。 |
| `resources.models[].display_name` | string | 否 | 展示名称。 |
| `resources.models[].model_config_ref` | string | 否 | 模型配置引用。 |
| `resources.tools` | object（对象数组） | 对象提供时 | 工具集合。 |
| `resources.tools[].name` | string | 对象提供时 | 名称；不能为空。 |
| `resources.tools[].id` | string | 对象提供时 | 标识；不能为空。 |
| `resources.tools[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `resources.skills` | object（对象数组） | 对象提供时 | 技能集合。 |
| `resources.skills[].name` | string | 对象提供时 | 名称；不能为空。 |
| `resources.skills[].id` | string | 对象提供时 | 标识；不能为空。 |
| `resources.skills[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `resources.knowledge_bases` | object（对象数组） | 对象提供时 | 知识库引用。 |
| `resources.knowledge_bases[].name` | string | 对象提供时 | 名称；不能为空。 |
| `resources.knowledge_bases[].id` | string | 对象提供时 | 标识；不能为空。 |
| `resources.knowledge_bases[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `candidate` | object | 否 | 完整候选智能体配置。 |
| `candidate.agent_id` | string | 对象提供时 | 新候选的智能体 ID；不能为空。 |
| `candidate.name` | string | 对象提供时 | 智能体名称。 |
| `candidate.description` | string | 对象提供时 | 智能体说明。 |
| `candidate.model_name` | string | 对象提供时 | `resources.models` 中可用的模型名称。 |
| `candidate.model_config_ref` | string | 否 | 模型配置引用。 |
| `candidate.tool_names` | string（字符串数组） | 对象提供时 | 选用的工具名称；没有工具时传空数组。 |
| `candidate.skill_names` | string（字符串数组） | 对象提供时 | 选用的技能名称；没有技能时传空数组。 |
| `candidate.knowledge_base_names` | string（字符串数组） | 对象提供时 | 选用的知识库名称；没有知识库时传空数组。 |
| `candidate.catalog_files` | object（对象数组） | 否 | Catalog文件引用。 |
| `candidate.catalog_files[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `candidate.catalog_files[].volume_id` | integer | 对象提供时 | 卷ID；不小于 1。 |
| `candidate.catalog_files[].file_id` | string | 对象提供时 | 文件ID；不能为空。 |
| `candidate.channel_bindings` | object（对象数组） | 否 | 候选通道绑定，可省略。 |
| `candidate.channel_bindings[].tool_name` | string | 否 | 工具名称。 |
| `candidate.channel_bindings[].tool_workspace_id` | string | 否 | 工具来源工作区ID。 |
| `candidate.channel_bindings[].skill_name` | string | 否 | 技能名称。 |
| `candidate.channel_bindings[].skill_workspace_id` | string | 否 | 技能来源工作区ID。 |
| `candidate.channel_bindings[].provider` | string | 否 | 提供方。 |
| `candidate.channel_bindings[].workspace_id` | string | 对象提供时 | 所属工作区ID。 |
| `candidate.channel_bindings[].instance_id` | string | 对象提供时 | 通道实例ID。 |
| `candidate.agent_md` | string | 对象提供时 | 可编辑的智能体 Markdown 正文。 |
| `candidate.change_reason` | string | 对象提供时 | 本次候选变更原因。 |
| `resource_refs` | object | 否 | 完整资源引用。 |
| `resource_refs.tools` | object（对象数组） | 对象提供时 | 工具集合。 |
| `resource_refs.tools[].id` | string | 对象提供时 | 标识；不能为空。 |
| `resource_refs.tools[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `resource_refs.skills` | object（对象数组） | 对象提供时 | 技能集合。 |
| `resource_refs.skills[].id` | string | 对象提供时 | 标识；不能为空。 |
| `resource_refs.skills[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `resource_refs.knowledge_bases` | object（对象数组） | 对象提供时 | 知识库引用。 |
| `resource_refs.knowledge_bases[].id` | string | 对象提供时 | 标识；不能为空。 |
| `resource_refs.knowledge_bases[].workspace_id` | string | 对象提供时 | 所属工作区ID；不能为空。 |
| `changes` | 任意 JSON | 否 | 变更集合。 |

字段路径中的 `[]` 表示数组中的每一项。

candidate 接受 catalog_files，其条目包含 workspace_id、volume_id、file_id。channel_bindings 可省略，不需要为无绑定候选强制提交。

完整 candidate 与 changes 是互斥的输入方式。修订使用 base_revision 并保留完整资源引用身份；changes 按对应增删资源与配置修改结构提交，不能同时提交完整 candidate。

当前可用知识库清单与候选解析的分页范围不一致。超出解析窗口的知识库可能无法引用；换用 ID 不能保证绕过这一限制。

## 成功响应

请求成功时返回 HTTP 200，响应如下。

候选版本采用 0.2.0 这样的三段数字格式，后续操作使用本次返回值；候选版本与 load_version 不同。render_type 为 agent_candidate。

成功表示候选已生成和保存，不保证候选为 valid 或已加载。新候选可替换旧候选；并行创作上下文可能发生冲突。

```json
{
  "code": 0,
  "data": {
    "render_type": "agent_candidate",
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "candidate_version": "0.2.0",
    "load_version": "0.2.0",
    "source_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "mode": "create",
    "status": "valid",
    "display": {
      "agent_name": "产品助手",
      "agent_id": "agent_01",
      "candidate_version": "0.2.0",
      "load_version": "0.2.0",
      "model": "",
      "tools": null,
      "skills": null,
      "knowledge_bases": null,
      "catalog_files": [],
      "channel_bindings": [],
      "agent_md": "",
      "change_reason": ""
    },
    "resolved_refs": {},
    "package_summary": {
      "manifest_path": "",
      "prompt_path": "",
      "file_paths": []
    }
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `data.render_type` | string | 展示类型；固定为 "agent_candidate"。 |
| `data.workspace_id` | string | 候选所属的工作区和智能体标识。 |
| `data.agent_id` | string | 候选所属的工作区和智能体标识。 |
| `data.candidate_version` | string | 候选版本，用于后续重新生成、确认或取消。 |
| `data.load_version` | string | 成功确认后用于查看已加载智能体配置的版本。 |
| `data.source_digest` | string | 当前候选内容摘要；后续写操作必须回传该值。 |
| `data.mode` | string | 构建模式和候选状态；取值：`create`、`revise`。 |
| `data.status` | string | 构建模式和候选状态；取值：`valid`、`invalid`。 |
| `data.display` | object | 面向展示的候选内容、校验诊断和已解析资源引用。 |
| `data.display.agent_name` | string | 智能体名称。 |
| `data.display.agent_id` | string | 智能体ID。 |
| `data.display.candidate_version` | string | 候选版本。 |
| `data.display.load_version` | string | 加载版本。 |
| `data.display.model` | string | 模型。 |
| `data.display.tools` | string（字符串数组） 或 null | 工具集合。 |
| `data.display.skills` | string（字符串数组） 或 null | 技能集合。 |
| `data.display.knowledge_bases` | string（字符串数组） 或 null | 知识库引用。 |
| `data.display.catalog_files` | object（对象数组） | Catalog文件引用。 |
| `data.display.catalog_files[].workspace_id` | string | 所属工作区ID。 |
| `data.display.catalog_files[].volume_id` | integer | 卷ID；有符号 64 位整数。 |
| `data.display.catalog_files[].file_id` | string | 文件ID。 |
| `data.display.channel_bindings` | object（对象数组） | 通道绑定。 |
| `data.display.channel_bindings[].tool_name` | string | 工具名称。 无值时可省略。 |
| `data.display.channel_bindings[].tool_workspace_id` | string | 工具来源工作区ID。 无值时可省略。 |
| `data.display.channel_bindings[].skill_name` | string | 技能名称。 无值时可省略。 |
| `data.display.channel_bindings[].skill_workspace_id` | string | 技能来源工作区ID。 无值时可省略。 |
| `data.display.channel_bindings[].provider` | string | 提供方。 无值时可省略。 |
| `data.display.channel_bindings[].workspace_id` | string | 所属工作区ID。 |
| `data.display.channel_bindings[].instance_id` | string | 通道实例ID。 |
| `data.display.agent_md` | string | 智能体Markdown正文。 |
| `data.display.change_reason` | string | 变更原因。 |
| `data.diagnostics` | object（对象数组） | 面向展示的候选内容、校验诊断和已解析资源引用；至少 1 项。 无值时可省略。 |
| `data.diagnostics[].severity` | string | 诊断级别。 |
| `data.diagnostics[].code` | string | 错误或诊断代码。 |
| `data.diagnostics[].message` | string | 消息内容。 |
| `data.diagnostics[].field_path` | string | 字段路径。 无值时可省略。 |
| `data.diagnostics[].resource_ref` | string | 资源引用。 无值时可省略。 |
| `data.resolved_refs` | object | 面向展示的候选内容、校验诊断和已解析资源引用。 |
| `data.resolved_refs.model` | object | 模型。 无值时可省略。 |
| `data.resolved_refs.model.name` | string | 名称。 |
| `data.resolved_refs.model.id` | string | 标识。 无值时可省略。 |
| `data.resolved_refs.model.workspace_id` | string | 所属工作区ID。 无值时可省略。 |
| `data.resolved_refs.model.requested_name` | string | 请求时的名称。 无值时可省略。 |
| `data.resolved_refs.tools` | object（对象数组） | 工具集合。 无值时可省略。 |
| `data.resolved_refs.tools[].name` | string | 名称。 |
| `data.resolved_refs.tools[].id` | string | 标识。 无值时可省略。 |
| `data.resolved_refs.tools[].workspace_id` | string | 所属工作区ID。 无值时可省略。 |
| `data.resolved_refs.tools[].requested_name` | string | 请求时的名称。 无值时可省略。 |
| `data.resolved_refs.skills` | object（对象数组） | 技能集合。 无值时可省略。 |
| `data.resolved_refs.skills[].name` | string | 名称。 |
| `data.resolved_refs.skills[].id` | string | 标识。 无值时可省略。 |
| `data.resolved_refs.skills[].workspace_id` | string | 所属工作区ID。 无值时可省略。 |
| `data.resolved_refs.skills[].requested_name` | string | 请求时的名称。 无值时可省略。 |
| `data.resolved_refs.skill_tools` | object（对象数组） | 技能工具映射。 无值时可省略。 |
| `data.resolved_refs.skill_tools[].skill_name` | string | 技能名称。 |
| `data.resolved_refs.skill_tools[].skill_id` | string | 技能ID。 |
| `data.resolved_refs.skill_tools[].skill_workspace_id` | string | 技能来源工作区ID。 无值时可省略。 |
| `data.resolved_refs.skill_tools[].tool_name` | string | 工具名称。 |
| `data.resolved_refs.skill_tools[].tool_id` | string | 工具ID。 |
| `data.resolved_refs.skill_tools[].tool_workspace_id` | string | 工具来源工作区ID。 无值时可省略。 |
| `data.resolved_refs.knowledge_bases` | object（对象数组） | 知识库引用。 无值时可省略。 |
| `data.resolved_refs.knowledge_bases[].name` | string | 名称。 |
| `data.resolved_refs.knowledge_bases[].id` | string | 标识。 无值时可省略。 |
| `data.resolved_refs.knowledge_bases[].workspace_id` | string | 所属工作区ID。 无值时可省略。 |
| `data.resolved_refs.knowledge_bases[].requested_name` | string | 请求时的名称。 无值时可省略。 |
| `data.resolved_refs.catalog_files` | object（对象数组） | Catalog文件引用。 无值时可省略。 |
| `data.resolved_refs.catalog_files[].workspace_id` | string | 所属工作区ID。 |
| `data.resolved_refs.catalog_files[].volume_id` | integer | 卷ID；有符号 64 位整数。 |
| `data.resolved_refs.catalog_files[].file_id` | string | 文件ID。 |
| `data.resolved_refs.channel_bindings` | object（对象数组） | 通道绑定。 无值时可省略。 |
| `data.resolved_refs.channel_bindings[].tool_name` | string | 工具名称。 无值时可省略。 |
| `data.resolved_refs.channel_bindings[].tool_workspace_id` | string | 工具来源工作区ID。 无值时可省略。 |
| `data.resolved_refs.channel_bindings[].skill_name` | string | 技能名称。 无值时可省略。 |
| `data.resolved_refs.channel_bindings[].skill_workspace_id` | string | 技能来源工作区ID。 无值时可省略。 |
| `data.resolved_refs.channel_bindings[].provider` | string | 提供方。 无值时可省略。 |
| `data.resolved_refs.channel_bindings[].workspace_id` | string | 所属工作区ID。 |
| `data.resolved_refs.channel_bindings[].instance_id` | string | 通道实例ID。 |
| `data.package_summary` | object | 候选包文件摘要；可用时返回。 |
| `data.package_summary.manifest_path` | string | 清单文件路径。 |
| `data.package_summary.prompt_path` | string | 提示词文件路径。 |
| `data.package_summary.file_paths` | string（字符串数组） | 文件路径列表。 |

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": 2,
  "message": "<错误信息>"
}
```

:::::
:::::{tab-item} 字段说明

::::{tab-set}
:::{tab-item} 常见 HTTP 错误

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `400` | `2`（`INVALID_ARGUMENT`） | 请求包含未知字段、必填字段缺失，候选配置或资源引用无效。建议：根据错误信息和 `diagnostics` 修正请求。 |
| `401` | `6`（`UNAUTHENTICATED`） | 缺少有效身份凭据。建议：检查 API Key。 |
| `403` | `5`（`PERMISSION_DENIED`） | 当前身份没有创建或修订候选的权限。建议：检查工作区和来源智能体授权。 |
| `409` | `4`（`ALREADY_EXISTS`） | 同一智能体存在并行创作上下文或候选冲突。建议：读取当前候选后重新提交。 |
| `413` | `14`（`RESOURCE_EXHAUSTED`） | `resources` 超过接口允许的大小。建议：减少资源清单后重试。 |
| `500` | `1`（`INTERNAL`） | 候选构建失败。建议：稍后重试；持续失败时联系支持。 |
| `503` | `15`（`UNAVAILABLE`） | 智能体搭建或授权服务暂不可用。建议：先查询当前状态；不要自动重复提交。 |

:::
::::
:::::
::::::
:::::::

## 后续操作

使用响应中的版本与摘要[确认智能体候选方案](commit-candidate.md)。