Files
th-hotel-simple/docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md
2026-07-10 17:36:56 +08:00

569 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# SuperAgent 与 AgentBus 通用对接指南
## 1. 文档定位
本文记录 SuperAgent 与 AgentBus 接入时可复用的工程边界、配置清单、验证顺序和安全要求。
本文不是官方协议文档,也不保存任何真实 Token、API Key、Session ID、Run ID、消息正文、附件 URL 或个人信息。接入新项目时,应以提供方最新协议、真实测试响应和当前项目业务规则为准。
如果新项目不使用 SuperAgent 或 AgentBus可以不复制本文。
## 2. 职责边界
SuperAgent 和 AgentBus 不应被设计成同一个模块。
推荐边界:
```text
AgentBus
→ 接收外部渠道消息
→ 保存 SourceMessage Inbox
→ 受控 Replay 为业务可消费事件
→ 调用 AI 能力端口
→ SuperAgent Provider Adapter
→ 保存 AI 调用审计
→ 业务 Schema 校验
→ 人工确认或业务规则确认
→ 正式业务写操作
```
| 能力 | 定位 | 负责什么 | 不负责什么 |
| --- | --- | --- | --- |
| AgentBus | 外部消息通道适配器 | WebSocket 连接、接收入站 frame、保存原始来源事实 | 不做 AI 抽取、不创建正式业务任务、不自动回复用户、不调用业务写接口 |
| SuperAgent | 外部 AI / Agent 能力提供方 | 创建 Agent Session、发送消息、解析 SSE、返回建议或回答 | 不决定业务动作、不绕过确认、不直接写业务系统 |
| SourceMessage Inbox | 入站缓冲层 | 不可变保存来源消息和捕获状态 | 不表达 AI 结论或业务归属 |
| AgentCapabilityPort | AI 能力端口 | 隔离业务层和具体 Provider SDK / HTTP 协议 | 不暴露 Provider DTO 给领域层 |
核心原则:
- 前端不直接调用 SuperAgent 或 AgentBus不接触任何 Provider Secret。
- AgentBus 实时链路只落来源事实,不直接生成正式业务结果。
- SuperAgent 返回内容只能作为建议、证据或审计结果,不能直接改变业务最终状态。
- 业务写操作必须经过规则校验、权限控制、幂等控制和人工确认或业务确认。
## 3. 推荐模块拆分
Java / Spring Boot 项目接入时,建议按以下模块复制思路:
```text
support
├── message
│ ├── SourceMessageInbox
│ ├── MessageEvent
│ └── Evidence
├── ai
│ ├── AgentCapabilityPort
│ ├── AgentCapabilityRequest
│ ├── AgentCapabilityResult
│ └── AiCapabilityInvocation
└── system
├── SuperAgentProbeController
├── AgentBusProbeStatusController
└── SourceMessageReplayController
integrations
├── ai
│ └── superagent
└── messaging
└── agentbus
```
模块规则:
- `support.message` 保存入站消息、回放和证据等平台能力。
- `support.ai` 保存 AI 能力端口、请求响应模型和调用审计。
- `integrations.ai.superagent` 保存 SuperAgent HTTP、SSE、认证和 DTO 细节。
- `integrations.messaging.agentbus` 保存 AgentBus WebSocket、frame 解析和入站映射。
- 业务模块只依赖 `AgentCapabilityPort` 和受控消息事件,不依赖 SuperAgent 或 AgentBus DTO。
## 4. SuperAgent 对接
### 4.1 运行时配置
最小配置建议:
```text
AI_PROVIDER_ENABLED=false
SUPERAGENT_BASE_URL=
SUPERAGENT_OPEN_API_KEY=
SUPERAGENT_PROBE_ENABLED=false
SUPERAGENT_PROBE_ACCESS_KEY=
SUPERAGENT_CONNECT_TIMEOUT=15s
SUPERAGENT_READ_TIMEOUT=180s
SUPERAGENT_MAX_MESSAGE_CHARS=4000
SUPERAGENT_EXTERNAL_SUBJECT_ID=<project-subject-id>
```
变量说明:
| 变量 | 是否 Secret | 说明 |
| --- | --- | --- |
| `AI_PROVIDER_ENABLED` | 否 | 是否启用真实 SuperAgent Provider Adapter。默认关闭。 |
| `SUPERAGENT_BASE_URL` | 否 | SuperAgent Open API 地址。 |
| `SUPERAGENT_OPEN_API_KEY` | 是 | Open API Key只能存在后端环境变量或 Secret Manager。 |
| `SUPERAGENT_PROBE_ENABLED` | 否 | 是否开放本项目自己的探针接口。生产默认关闭。 |
| `SUPERAGENT_PROBE_ACCESS_KEY` | 是 | 调用探针接口的本地访问密钥,不是 Provider API Key。 |
| `SUPERAGENT_CONNECT_TIMEOUT` | 否 | 建立连接超时。 |
| `SUPERAGENT_READ_TIMEOUT` | 否 | SSE 读取超时。 |
| `SUPERAGENT_MAX_MESSAGE_CHARS` | 否 | 单次发送给 Provider 的消息长度上限。 |
| `SUPERAGENT_EXTERNAL_SUBJECT_ID` | 否 | 创建 Agent Session 时使用的外部主体标识。 |
### 4.2 Open API 调用形态
常见流程:
```text
POST /api/open/agent-sessions
→ 获取 session_id
→ POST /api/open/agent-sessions/{sessionId}/messages/stream
→ 读取 text/event-stream
→ 解析最终 answer、run、profile、model、token usage
```
如果提供方要求 CSRF double-submit应保证 Header 与 Cookie 使用同一个临时随机值:
```text
X-CSRF-Token: <random-csrf-token>
Cookie: csrf_token=<same-random-csrf-token>
Authorization: Bearer <SUPERAGENT_OPEN_API_KEY>
```
CSRF Token 由客户端实例临时生成,不写入配置,也不能当作 Secret 长期保存。
### 4.3 Session 请求示例
```json
{
"external_subject_id": "<project-subject-id>",
"idempotency_key": "<project-code>-superagent-session-<correlation-id>",
"metadata": {
"source": "<project-code>",
"purpose": "provider-connectivity-test"
}
}
```
### 4.4 SSE 消息请求示例
```json
{
"message": "请介绍一下你是谁。",
"idempotency_key": "<project-code>-superagent-message-<correlation-id>",
"metadata": {
"source": "<project-code>",
"purpose": "provider-flow-test"
}
}
```
### 4.5 SSE 解析口径
建议至少处理:
- 调用元数据,例如 Run、Thread、Profile。
- 流式消息增量或中间消息。
- 阶段性或最终聚合状态。
- SSE 正常结束标志。
解析最终答案时,不要简单拼接所有消息增量。应以提供方协议中明确的最终回答字段为准,并记录:
- provider request id 或 run id。
- profile id 与 profile version id。
- model id 或 model name。
- input tokens、output tokens 和 total tokens。
- 已出现的 SSE event types。
如果没有收到结束事件,或无法找到最终 AI 回答,应视为协议失败,不要伪造成成功结果。
### 4.6 平台能力端口
建议定义稳定端口:
```java
public interface AgentCapabilityPort {
AgentCapabilityResult invoke(AgentCapabilityRequest request);
}
```
领域层只依赖这个端口,不依赖 SuperAgent HTTP DTO、SSE event、Profile ID 或厂商 SDK。
建议 `AgentCapabilityResult` 至少包含:
```text
providerCode
responseSchemaVersion
providerSessionId
providerRequestId
providerProfileId
providerProfileVersionId
providerModelId
outputText 或 outputReference
usageMetadata
```
### 4.7 调用审计
建议每次外部能力调用都写入不可变审计表。
审计表应记录:
- provider code。
- capability code。
- request id / run id。
- profile / model 信息。
- 请求状态、耗时、错误代码。
- token usage 或成本元数据。
- 脱敏后的输入输出摘要。
审计表不应记录:
- Provider API Key。
- Cookie。
- Authorization。
- Chain of Thought。
- Provider 内部 Plan / Memory。
- 未脱敏的个人信息。
## 5. AgentBus 对接
### 5.1 运行时配置
最小配置建议:
```text
AGENTBUS_PROBE_ENABLED=false
AGENTBUS_WS_URL=
AGENTBUS_WS_TOKEN=
AGENTBUS_BOT_ADDRESS=
AGENTBUS_WS_RECONNECT_DELAY=5s
AGENTBUS_CONNECT_TIMEOUT=15s
AGENTBUS_SAMPLE_ENABLED=false
AGENTBUS_SAMPLE_DIR=var/agentbus-samples
AGENTBUS_MAX_FRAME_BYTES=1048576
AGENTBUS_MAX_SAMPLES=100
AGENTBUS_CAPTURE_ENABLED=true
AGENTBUS_DEFAULT_CONTEXT_ID=
AGENTBUS_REPLY_MODE=NONE
```
变量说明:
| 变量 | 是否 Secret | 说明 |
| --- | --- | --- |
| `AGENTBUS_PROBE_ENABLED` | 否 | 是否启用 AgentBus WebSocket 监听。默认关闭。 |
| `AGENTBUS_WS_URL` | 否 | AgentBus WebSocket 地址。 |
| `AGENTBUS_WS_TOKEN` | 是 | WebSocket 鉴权 Token。 |
| `AGENTBUS_BOT_ADDRESS` | 否 | 当前 Bot / Listener 地址。 |
| `AGENTBUS_WS_RECONNECT_DELAY` | 否 | 断线后的重连间隔。 |
| `AGENTBUS_CONNECT_TIMEOUT` | 否 | WebSocket 连接超时。 |
| `AGENTBUS_SAMPLE_ENABLED` | 否 | 是否保存本地原始 frame 样本。生产应默认关闭。 |
| `AGENTBUS_SAMPLE_DIR` | 否 | 本地样本目录,可能含敏感信息,不得提交。 |
| `AGENTBUS_MAX_FRAME_BYTES` | 否 | 单个入站 frame 最大字节数。 |
| `AGENTBUS_MAX_SAMPLES` | 否 | 最多保留的本地样本数。 |
| `AGENTBUS_CAPTURE_ENABLED` | 否 | 是否写入 SourceMessage Inbox。 |
| `AGENTBUS_DEFAULT_CONTEXT_ID` | 否 | Provider 未提供业务上下文时的默认上下文。 |
| `AGENTBUS_REPLY_MODE` | 否 | 调试回复模式。真实用户渠道应保持 `NONE`。 |
### 5.2 WebSocket 连接
常见连接形态:
```text
Authorization: Bearer <AGENTBUS_WS_TOKEN>
GET <AGENTBUS_WS_URL>?ready=1
```
连接成功后应能收到 `session.ready` 或等价就绪事件。
状态查询接口只应返回连接状态、计数器和最近错误代码,不返回 Token 或原始消息。
### 5.3 入站 frame 处理边界
推荐处理顺序:
```text
收到 raw WebSocket frame
→ 限制单帧大小
→ 可选本地采样
→ JSON 解析
→ 忽略 session.ready / task.progress / task.result 等控制事件
→ 将业务 payload 映射为 CaptureSourceMessageCommand
→ 写入 SourceMessage Inbox
```
实时链路禁止:
- 自动发送 ACK。
- 自动发送 `task.result`
- 自动回复用户。
- 直接创建正式业务事件、业务任务、业务操作或业务回执。
- 直接调用 ERP、支付系统、订单系统等业务写接口。
### 5.4 Payload 字段确认
接入前必须通过真实测试响应确认 payload 字段,不根据字段名猜测业务语义。
建议至少确认:
- `source.channel`
- `source.external_message_id`
- `source.external_conversation_id`
- payload 或 source 中的 `received_at`
- `source.sent_at`
- frame id
- session id
- sender
- subject 或标题
- text / html / attachments 等消息内容字段
- reply policy 或回复策略
捕获层只依赖少量稳定字段:
| Provider 字段 | 平台字段 |
| --- | --- |
| `source.channel` | `channel` |
| `source.external_message_id` | `externalMessageId`,作为幂等键组成部分 |
| `source.external_conversation_id` | `externalConversationId` |
| payload 或 source 中的 `received_at` | `receivedAt`,作为消息来源接收时间 |
| `source.sent_at` | `sourceSentAt`,作为消息来源发送时间 |
| sender | `senderSummary`,是否打码由项目业务和权限策略决定 |
| frame id | `providerFrameId` |
| session id | `providerSessionId` |
| payload 规范 JSON | `payloadJson``payloadSha256` |
不要根据 envelope 的 `from``to``conversation_id` 猜测业务归属或下游任务。
### 5.5 SourceMessage Inbox
建议单独建表保存 AgentBus 入站事实。
推荐幂等键:
```text
context_id + provider + channel + external_message_id
```
重复投递时返回已有 Inbox不覆盖原始 payload不创建重复记录。
如果 payload 缺少必要字段或格式不符合预期,也应保存为 `FAILED` Inbox并记录安全错误摘要。错误摘要不得包含
- 消息正文。
- HTML。
- 附件 URL。
- 完整邮箱地址或手机号。
- Token / Cookie / Secret。
### 5.6 Replay 到业务事件
SourceMessage Inbox 不应等同于正式业务消息。建议增加受控 Replay
```text
POST /api/system/source-message-inbox/{inboxId}/replay
Header: X-Source-Message-Replay-Key
```
Replay 负责:
- 从 Inbox payload 提取业务可消费字段。
- 保存正文或正文引用。
- 保存证据摘要或附件引用。
- 记录 replay attempt。
- 返回业务事件 ID 和状态。
Replay 接口默认关闭仅在本地、UAT 或受控生产运维场景开启。
## 6. 最小落地顺序
### 阶段 1SuperAgent 连通性
目标:
```text
后端探针
→ 创建 SuperAgent Session
→ 发送一条无敏感信息测试消息
→ 解析 SSE 最终回答
→ 返回非敏感元数据
```
验收:
- HTTP 连接成功。
- SSE 收到结束事件。
- 最终回答非空。
- 日志不出现 API Key、Cookie、Session 原始值或个人信息。
### 阶段 2AgentBus 连接
目标:
```text
AgentBus WebSocket
→ session.ready
→ 状态接口可见 connected/sessionReady
```
验收:
- 连接成功。
- 可断线重连。
- 不发送用户回复。
- 不保存本地 raw sample除非临时排障。
### 阶段 3SourceMessage Inbox
目标:
```text
AgentBus 入站业务 frame
→ SourceMessage Inbox
```
验收:
- 正常 payload 保存为 `RECEIVED`
- 无效 payload 保存为 `FAILED`
- 重复外部消息不重复入库。
- 查询接口只返回安全摘要。
### 阶段 4手动 Replay
目标:
```text
SourceMessage Inbox
→ 业务可消费事件 / Evidence
```
验收:
- 同一 Inbox 可以按不同 `replayRunId` 多次 replay。
- 相同 `replayRunId` 幂等。
- Replay 失败有 attempt 记录。
- 响应不返回消息正文、HTML、附件 URL 或 Token。
### 阶段 5业务接入 SuperAgent
目标:
```text
业务事件
→ AgentCapabilityPort
→ SuperAgent Adapter
→ AI 调用审计
→ 业务 Schema 校验
```
验收:
- Provider 返回记录为审计,不直接触发业务写操作。
- 结构化输出必须通过 Schema 校验。
- 无法映射或不可信结果进入人工处理。
## 7. 安全与日志清单
必须放入 Secret 管理,不得提交仓库:
- `SUPERAGENT_OPEN_API_KEY`
- `SUPERAGENT_PROBE_ACCESS_KEY`
- `AGENTBUS_WS_TOKEN`
- `SOURCE_MESSAGE_REPLAY_ACCESS_KEY`
- 数据库密码
- 任何真实用户渠道 Token
普通日志和错误响应不得输出:
- Authorization。
- Cookie。
- CSRF Token。
- Provider API Key。
- AgentBus Token。
- 消息正文和 HTML。
- 附件 URL。
- 姓名、邮箱、电话、证件号。
- 支付信息。
本地采样要求:
- `AGENTBUS_SAMPLE_ENABLED` 默认 `false`
- 只在隔离测试或排障时临时开启。
- 样本目录必须被 `.gitignore` 忽略。
- 排障结束后删除样本。
## 8. 测试建议
SuperAgent 建议覆盖:
- 缺失 API Key 时启动或调用失败。
- CSRF Header / Cookie 不一致时转换为受控错误。
- 创建 Session 成功。
- SSE 正常结束并解析最终回答。
- SSE 缺少结束事件时失败。
- SSE 缺少最终回答时失败。
- HTTP 401 / 403 / 404 / 409 / 5xx 错误转换。
- 连接超时和读取超时。
AgentBus 建议覆盖:
- `session.ready` 只更新状态,不写 Inbox。
- 控制事件不写 Inbox。
- 正常 payload 写入 Inbox。
- `captureEnabled=false` 时忽略业务 frame。
- 无效 payload 写入 `FAILED` Inbox。
- 超大 frame 被拒绝并记录错误代码。
- 重复外部消息保持幂等。
- 查询接口不返回原始 payload。
- Replay 相同 run id 幂等。
## 9. 常见误区
### 9.1 把 AgentBus 当 AI Provider
AgentBus 是消息入口,不是抽取模型。它可以传递外部渠道原始事实,但不应该直接产生业务最终判断。
### 9.2 把 SuperAgent 返回当业务事实
SuperAgent 返回的是 Provider 输出。即使返回结构化 JSON也必须经过 Schema、业务规则、业务对象匹配和人工确认或业务确认。
### 9.3 让浏览器直接调用 Provider
浏览器不能持有 Provider Key、AgentBus Token 或 replay access key。前端只调用本项目后端。
### 9.4 实时入口直接生成正式业务任务
实时 AgentBus 链路如果直接创建正式业务任务,会导致重复投递、字段不完整、后续协议变化和人工回溯都难处理。先落 Inbox再 Replay是更稳的路线。
### 9.5 在文档或测试里保存真实消息
真实消息、附件 URL、姓名和联系方式都可能是敏感数据。测试夹具应使用合成数据。
## 10. 接入前检查清单
接入 SuperAgent 前确认:
- [ ] 已获得 Open API Key 和允许访问的 Base URL。
- [ ] 已确认是否需要 CSRF double-submit。
- [ ] 已确认 Session、Message、Run 的生命周期。
- [ ] 已确认 SSE 最终答案或结构化结果所在字段。
- [ ] 已定义 `AgentCapabilityPort` 和调用审计表。
- [ ] 已确认 Provider 输出不会直接触发业务写操作。
接入 AgentBus 前确认:
- [ ] 已获得 WebSocket URL、Token 和 Bot Address。
- [ ] 已确认真实渠道 payload 字段。
- [ ] 已确认外部消息稳定幂等键。
- [ ] 已确认断线重连和重复投递语义。
- [ ] 已确认是否允许 ACK 或用户回复;默认按禁止处理。
- [ ] 已建立 SourceMessage Inbox 和 Replay attempt。
- [ ] 已定义原始 payload 的保存、访问、保留和删除策略。
进入生产前确认:
- [ ] 所有 Secret 均通过环境变量或 Secret Manager 注入。
- [ ] `.env.example` 只有占位值。
- [ ] 日志脱敏已验证。
- [ ] 自动回复保持关闭。
- [ ] 自动业务写操作保持关闭,除非经过单独评审。
- [ ] 监控至少覆盖连接状态、失败次数、Replay 失败和 Provider 调用失败。