智能体构建 API 参考

本页汇总读取构建资源、生成候选版本和提交可运行版本的接口。完整任务流程见构建并提交智能体。

接口

方法	相对路径	用途
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，不要自行构造。

任务指南

• 构建并提交智能体

• 调用已经发布的智能体

最后更新于 2026 年 8 月 14 日