创建或修改候选版本¶

接口用途¶

创建或修订智能体构建器候选版本。创建时使用 mode=create；修改核心配置走 revise 与后续提交。

请求方式¶

POST

接口地址¶

https://moi.matrixorigin.cn/newmoi/workspaces/<workspace_id>/agent-builder/candidates

身份认证¶

使用工作区 API Key，在请求头中携带 X-API-Key: <WORKSPACE_API_KEY>，并设置 Content-Type: application/json。

路径参数¶

无。

查询参数¶

无。

请求体¶

创建时 mode=create；修改核心配置走 revise/commit。resources 与 candidate 为必填。

字段	类型	必填	说明
`mode`	string	是	`create` 或 revise 相关模式
`conversation_id`	string	是	会话 ID
`raw_advice`	string	是	自然语言建议/需求
`resources`	object	是	含 `models` / `tools` / `skills` / `knowledge_bases` 数组
`candidate`	object	是	候选配置，见下
`candidate.agent_id`	string	是	智能体 ID
`candidate.name`	string	是	名称
`candidate.description`	string	是	描述
`candidate.model_name`	string	是	模型名
`candidate.tool_names`	array	是	工具名列表
`candidate.skill_names`	array	是	技能名列表
`candidate.knowledge_base_names`	array	是	知识库名列表
`candidate.catalog_files`	array	是	目录文件引用
`candidate.channel_bindings`	array	是	渠道绑定
`candidate.agent_md`	string	是	Agent Markdown 正文
`candidate.change_reason`	string	是	变更原因
`task_id`	string	否	关联任务
`source_agent_id`	string	否	来源智能体（revise）
`source_version`	string	否	来源版本

请求示例¶

curl -X POST 'https://moi.matrixorigin.cn/newmoi/workspaces/<workspace_id>/agent-builder/candidates' \
  -H 'X-API-Key: <WORKSPACE_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{"mode":"create","conversation_id":"<conversation_id>","raw_advice":"Create a support agent","resources":{"models":[{"name":"deepseek-v4-pro"}],"tools":[],"skills":[],"knowledge_bases":[]},"candidate":{"agent_id":"<agent_id>","name":"support-agent","description":"Support","model_name":"deepseek-v4-pro","tool_names":[],"skill_names":[],"knowledge_base_names":[],"catalog_files":[],"channel_bindings":[],"agent_md":"# Support agent","change_reason":"initial"}}'

响应说明¶

除 A2A JSON-RPC 外，多数工作区接口成功响应形如 {"code":0,"data":...}；下列字段描述 data（或 HTTP 202 时的 data）。

候选视图主要字段（后续 commit 需要）：

字段	类型	说明
`agent_id`	string	智能体 ID
`candidate_version`	string	候选版本号
`load_version`	string	加载版本
`source_digest`	string	提交时必填的摘要
`mode`	string	模式
`status`	string	候选状态
`display`	object	展示用摘要（名称、模型、工具等）
`diagnostics`	array	诊断信息
`resolved_refs`	object	解析后的资源引用

使用限制¶

不要使用 POST /agents 作为创建可运行智能体的主路径。
候选版本在提交前 generatable package version 尚未形成。