构建 Single Agent

Single Agent 是 Agent Business 的两种 Capability 类型之一。当一个有界、由模型支持的推理单元足以交付业务承诺时，选择 Single Agent。需要显式多步骤编排、分支或结构化中间结果时，请选择 Workflow DAG。

1. 打开 Definition 编辑器

在创作者控制台打开 Agent Business，然后选择 Capability。一个 Single Agent 只有一份权威的 v1 Definition。业务身份、可见性、定价、Offer 和 Publication 位于各自的 Workspace，不会在这里重复编辑。

2. 配置五个区域

编辑器把运行时契约分成五个聚焦区域：

1. Instructions 包含 System Instructions 和 User Message Template。{{topic}} 这类模板变量应与输入 Schema 的字段一致。
2. Contract 定义用于验证、文档和机器客户端的输入输出 JSON Schema。
3. Model 选择 Completion 或 Chat、提供商与模型、采样参数以及执行限制。
4. Tools 固定 Tool ID、类型、版本、Endpoint 和可选的服务端凭据引用。绝不要把 API Key、密码、Cookie、Authorization Header 或 Token 粘贴到 Definition。
5. Preview 接受一个 JSON Object，只显示脱敏结果和 Trace 摘要。

内置提供商不需要 Provider Credential Reference。外部提供商和 Tool 可以引用平台托管的 Secret，但浏览器永远不会读取或保存原始值。

3. Save Draft

选择 Save Draft 保存可编辑 Definition。保存时会使用编辑器加载的 Base Revision。如果另一个编辑器先保存，控制台会保留你的本地变更并报告冲突，让你重新加载后明确合并。

第一次打开旧配置时，控制台可能只在内存中进行适配。这个状态会被明确标记；在你选择 Save Draft 前，v1 Definition 不会写入存储。

保存不会改变生产行为，也不会创建 Release。

4. Preview 未保存的变更

输入符合 Input Contract 的 Object，然后选择 Preview definition。Preview 会执行浏览器当前显示的 Definition，包括未保存的变更。它不会保存、发布或激活任何内容。

响应只显示有界结果，以及状态、耗时、提供商、模型、交互模式和 Execution ID。提供商错误详情、凭据、认证 Header 和私有配置不会暴露。

5. Create Release

只有 Definition 与已保存 Draft 一致时，Create Release 才可用。先保存或放弃本地变更，再选择 Create Release，创建并激活不可变 Capability Release。

每个 Release Digest 都覆盖完整可执行 Definition，包括模型配置、限制、Schema 和 Tool 引用。Workflow Agent 节点会同时固定所选 Single Agent Release ID 与 SHA-256 Digest。后续创建新的 Single Agent Release，不会静默改变已有 Workflow。

控制面与运行时 Endpoint

创作者控制台使用以下 Canonical Endpoint：

GET   https://api.agentaab.com/api/app/{business-slug}/single-agent/
PATCH https://api.agentaab.com/api/app/{business-slug}/single-agent/
POST  https://api.agentaab.com/api/app/{business-slug}/single-agent/preview/

公开调用方通过 Completion 或 Chat 运行时路由调用当前激活 Release：

POST https://api.agentaab.com/api/app/{business-slug}/completion-messages
POST https://api.agentaab.com/api/app/{business-slug}/chat-messages

旧 /prompt/ 控制面路径继续作为兼容别名。新集成应使用 /single-agent/。公开认证与错误处理请参考运行时客户端指南。

故障排除

Create Release 不可用

Definition 存在未保存变更，或旧配置仍处于待保存适配状态。先选择 Save Draft，并等待保存确认。

Save 提示存在更新的 Draft

另一次保存先通过了乐观并发检查。浏览器会保留本地 Definition。必要时先复制内容，重新加载更新的 Revision，再明确合并。

生产环境仍在运行旧行为

Save Draft 和 Preview 都不会替换生产行为。请确认已经创建并激活新的 Capability Release。

Workflow 无法选择这个 Single Agent

Workflow Agent 节点只能固定一个可访问、已激活、Digest 可解析且运行时配置受支持的 Release。可变 Draft 不能作为目标。