生成智能体候选方案

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

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

调用前准备

先查询智能体搭建可用资源取得资源清单。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

candidate 应包含智能体标识、名称、模型及所引用的工具、技能、知识库或通道等配置。引用必须可在 resources 或工作区的可解析范围中找到。创建候选时使用 candidate.agent_id，不要使用 candidate.id。不要发送文档未定义的字段；当前服务会将 candidate.catalog_files 判定为未知字段并返回错误。

请求体

请求示例

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": "初始创建"
    }
  }'

字段说明

请求字段

字段	类型	必填	说明
mode	string	是	构建模式；创建新智能体使用 create。
conversation_id	string	是	本次搭建所属会话 ID。
raw_advice	string	是	本次创建或修改的原始要求。
resources	object	是	选择搭建资源中返回的资源集合。
candidate	object	是	完整候选智能体配置。
candidate.agent_id	string	是	新候选的智能体 ID。
candidate.name	string	是	智能体名称。
candidate.description	string	是	智能体说明。
candidate.model_name	string	是	resources.models 中可用的模型名称。
candidate.tool_names	array of string	是	选用的工具名称；没有工具时传空数组。
candidate.skill_names	array of string	是	选用的技能名称；没有技能时传空数组。
candidate.knowledge_base_names	array of string	是	选用的知识库名称；没有知识库时传空数组。
candidate.channel_bindings	array	是	候选的通道绑定；没有绑定时传空数组。
candidate.agent_md	string	是	可编辑的智能体 Markdown 正文。
candidate.change_reason	string	是	本次候选变更原因。
task_id	string	否	关联的任务 ID。
source_agent_id	string	修订模式需要	来源智能体 ID。
source_agent_workspace_id	string	否	来源智能体工作区。
source_version	string	修订模式需要	来源版本。

请求参数

请求示例

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": {
      "id": "<AGENT_ID>",
      "name": "产品助手"
    }
  }'

参数说明

路径参数

字段	类型	必填	说明
workspace_id	string	是	工作区 ID。

成功响应

响应示例

{
  "code": 0,
  "data": {
    "render_type": "candidate",
    "workspace_id": "ws_01",
    "agent_id": "agent_01",
    "candidate_version": "cand_01",
    "load_version": "v1",
    "source_digest": "sha256:<HEX_DIGEST>",
    "mode": "create",
    "status": "valid",
    "display": {
      "agent_name": "产品助手",
      "agent_id": "agent_01"
    },
    "diagnostics": []
  }
}

字段说明

成功时返回 200。候选已生成不表示已成为当前可运行版本。

通用字段

字段	类型	说明
code	integer	成功时为 0。

响应数据

字段	类型	说明
data.workspace_id	string	候选所属的工作区和智能体标识。
data.agent_id	string	候选所属的工作区和智能体标识。
data.candidate_version	string	候选版本，用于后续重新生成、确认或取消。
data.load_version	string	成功确认后用于查看已加载智能体配置的版本。
data.source_digest	string	当前候选内容摘要；后续写操作必须回传该值。
data.mode	string	构建模式和候选状态。
data.status	string	构建模式和候选状态。
data.display	object	面向展示的候选内容、校验诊断和已解析资源引用。
data.diagnostics	array	面向展示的候选内容、校验诊断和已解析资源引用。
data.resolved_refs	object	面向展示的候选内容、校验诊断和已解析资源引用。
data.package_summary	object	候选包文件摘要；可用时返回。

错误响应

响应示例

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

字段说明

常见 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）	智能体搭建或授权服务暂不可用。建议：稍后重试。

后续操作

使用响应中的版本与摘要确认智能体候选方案。

最后更新于 2026 年 9 月 11 日