# 构建并提交智能体

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

## 开始之前

- 准备 Product API Base URL、个人访问令牌和工作区 ID；
- 确认目标模型、工具、技能和知识库在当前工作区可见；
- 为本次构建准备会话 ID、智能体 ID、名称和行为说明；
- 修改现有智能体时，保存来源智能体 ID 和版本。

## 1. 获取可用资源

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

```bash
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. 创建候选版本

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

```bash
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. 提交候选版本

```bash
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. 确认当前智能体

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

```bash
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` 是否与提交内容一致。最后通过[调用智能体](../../product-api/agents-a2a/call-agent-a2a.md)发起一次低风险调用，确认智能体运行时可以加载该版本。

## 常见问题

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| 候选版本无效 | `diagnostics` 和 `resolved_refs` | 修正资源名称、引用或候选配置后重新生成。 |
| 提交返回冲突 | 当前候选状态和 `source_digest` | 重新读取或生成候选版本，不复用旧摘要。 |
| 提交成功但调用失败 | 当前生效版本、模型和工具凭据 | 读取当前智能体配置，再检查运行时依赖。 |
| 修改了错误的智能体 | `source_agent_id`、来源版本和工作区 | 停止提交，重新从目标智能体的当前版本创建修订。 |

## 下一步

- [查询智能体构建 API](api-reference.md)
- [创建和管理技能](../skills/manage-skills.md)
- [调用智能体](../../product-api/agents-a2a/call-agent-a2a.md)