# 智能体构建 API 参考

本页汇总读取构建资源、生成候选版本和提交可运行版本的接口。完整任务流程见[构建并提交智能体](build-publish-agent.md)。

## 接口

| 方法 | 相对路径 | 用途 |
| --- | --- | --- |
| `GET` | `/workspaces/{workspace_id}/agent-builder/resources` | 读取可用于构建的模型、工具、技能和知识库。 |
| `POST` | `/workspaces/{workspace_id}/agent-builder/candidates` | 创建或修订候选版本。 |
| `POST` | `/workspaces/{workspace_id}/agent-builder/candidates/{agent_id}/candidate-versions/{candidate_version}/repropose` | 使用覆盖字段重新生成候选版本。 |
| `POST` | `/workspaces/{workspace_id}/agent-builder/candidates/{agent_id}/candidate-versions/{candidate_version}/cancel` | 取消候选版本。 |
| `POST` | `/workspaces/{workspace_id}/agent-builder/candidates/{agent_id}/candidate-versions/{candidate_version}/commit` | 提交候选版本。 |
| `GET` | `/workspaces/{workspace_id}/agent-builder/agents/{agent_id}/versions/{version}/current-agent` | 读取指定版本的当前智能体配置。 |

## 候选请求

| 字段 | 类型 | 必需 | 说明 |
| --- | --- | --- | --- |
| `mode` | string | 是 | 创建或修订模式。创建新智能体时使用 `create`。 |
| `conversation_id` | string | 是 | 产生本次构建请求的会话 ID。 |
| `task_id` | string | 否 | 与本次构建关联的任务 ID。 |
| `source_agent_id` | string | 修订时使用 | 来源智能体。 |
| `source_agent_workspace_id` | string | 跨工作区来源时使用 | 来源智能体工作区。 |
| `source_version` | string | 修订时使用 | 来源版本。 |
| `raw_advice` | string | 是 | 本次创建或修改的原始要求。 |
| `resources` | object | 是 | 当前可用的模型、工具、技能和知识库集合。 |
| `candidate` | object | 是 | 候选智能体配置。 |

`candidate` 至少描述智能体 ID、名称、说明、模型、工具、技能、知识库、Catalog 文件、通道绑定、`agent_md` 和变更原因。引用的资源必须存在于 `resources` 或当前工作区可解析范围中。

## 候选响应

| 字段 | 类型 | 返回条件 | 说明 |
| --- | --- | --- | --- |
| `agent_id` | string | 始终返回 | 候选版本所属智能体。 |
| `candidate_version` | string | 始终返回 | 候选版本。 |
| `load_version` | string | 已分配加载版本时返回 | 提交后的版本读取入口。 |
| `source_digest` | string | 始终返回 | 重新生成、取消和提交时使用。 |
| `status` | string | 始终返回 | 候选版本当前状态。 |
| `display` | object | 始终返回 | 面向检查的候选摘要。 |
| `diagnostics` | array | 存在诊断时返回 | 严重程度、代码、消息和字段路径。 |
| `resolved_refs` | object | 资源完成解析时返回 | 已解析的模型、工具、技能、知识库、文件和通道引用。 |
| `package_summary` | object | 已生成候选包时返回 | Manifest、提示词和文件路径摘要。 |

## 重新生成、取消和提交

三个操作都使用路径中的智能体 ID、候选版本以及请求体中的 `source_digest`。重新生成还接受需要覆盖的候选字段；提交可以携带元数据或绑定覆盖。

提交成功后返回工作区、智能体、名称、`load_version`、`source_digest` 和 `package_digest`。随后读取当前智能体配置并完成一次运行验证。

## 错误和限制

| 现象 | 检查信息 | 恢复方式 |
| --- | --- | --- |
| 资源无法解析 | `diagnostics[].resource_ref` 和 Builder 资源列表 | 重新取得资源列表并修正候选引用。 |
| 候选版本冲突 | `source_digest`、候选状态和版本 | 使用最新候选响应重新执行操作。 |
| 构建或加载失败 | `status` 和诊断消息 | 修正候选内容或依赖资源后重新生成。 |
| 当前版本不存在 | `agent_id` 和 `version` | 使用提交响应中的 `load_version`，不要自行构造。 |

## 任务指南

- [构建并提交智能体](build-publish-agent.md)
- [调用已经发布的智能体](../../product-api/agents-a2a/index.md)