构建并提交智能体

智能体构建由候选版本和提交两个阶段组成。先读取当前可用资源并生成候选版本；检查候选状态和诊断信息后，再提交为可运行版本。

开始之前

  • 准备 Product API Base URL、个人访问令牌和工作区 ID；

  • 确认目标模型、工具、技能和知识库在当前工作区可见；

  • 为本次构建准备会话 ID、智能体 ID、名称和行为说明；

  • 修改现有智能体时，保存来源智能体 ID 和版本。

1. 获取可用资源

候选请求必须使用当前工作区可以解析的资源。先读取 Builder 资源：

curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-builder/resources" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

响应分别返回可用于构建的模型、工具、技能和知识库。使用响应中的正式名称或引用构造候选配置，不根据界面显示名称猜测资源 ID。

2. 创建候选版本

下面的示例创建一个最小候选版本：

curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-builder/candidates" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "create",
    "conversation_id": "<CONVERSATION_ID>",
    "raw_advice": "Create a support agent",
    "resources": {
      "models": [{"name": "<MODEL_NAME>"}],
      "tools": [],
      "skills": [],
      "knowledge_bases": []
    },
    "candidate": {
      "agent_id": "<AGENT_ID>",
      "name": "support-agent",
      "description": "Answer product support questions",
      "model_name": "<MODEL_NAME>",
      "tool_names": [],
      "skill_names": [],
      "knowledge_base_names": [],
      "catalog_files": [],
      "channel_bindings": [],
      "agent_md": "# Support agent\nAnswer only from available product information.",
      "change_reason": "Initial version"
    }
  }'

成功后保存 data.agent_id、data.candidate_version 和 data.source_digest。提交候选版本时必须使用同一次候选响应返回的摘要。

3. 检查候选版本

字段

需要检查的内容

status

候选版本是否有效，是否正在提交或已经失败。

diagnostics

错误或警告涉及的字段和资源引用。

resolved_refs

模型、工具、技能和知识库是否解析到预期资源。

display

名称、模型、资源列表和行为说明是否符合预期。

source_digest

后续重新生成、取消和提交使用的并发保护摘要。

候选状态为无效或包含阻塞性诊断时，不要直接提交。修正候选配置或资源后，使用重新生成接口创建新的候选版本。放弃本次候选时调用取消接口。

4. 提交候选版本

curl -X POST \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-builder/candidates/<AGENT_ID>/candidate-versions/<CANDIDATE_VERSION>/commit" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"source_digest":"<SOURCE_DIGEST>"}'

成功响应返回 load_version 和 package_digest。保存 load_version，用于确认当前生效配置和定位后续调用使用的版本。

5. 确认当前智能体

提交成功只表示候选版本已经生成可运行包。再读取当前智能体配置：

curl \
  "$PRODUCT_API_BASE_URL/workspaces/$WORKSPACE_ID/agent-builder/agents/<AGENT_ID>/versions/<LOAD_VERSION>/current-agent" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

检查名称、模型、工具、技能、知识库和 agent_md 是否与提交内容一致。最后通过调用智能体发起一次低风险调用，确认智能体运行时可以加载该版本。

常见问题

现象

先检查

下一步

候选版本无效

diagnostics 和 resolved_refs

修正资源名称、引用或候选配置后重新生成。

提交返回冲突

当前候选状态和 source_digest

重新读取或生成候选版本，不复用旧摘要。

提交成功但调用失败

当前生效版本、模型和工具凭据

读取当前智能体配置，再检查运行时依赖。

修改了错误的智能体

source_agent_id、来源版本和工作区

停止提交，重新从目标智能体的当前版本创建修订。

下一步

最后更新于