# 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= ``` 变量说明： | 变量 | 是否 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: Cookie: csrf_token= Authorization: Bearer ``` CSRF Token 由客户端实例临时生成，不写入配置，也不能当作 Secret 长期保存。 ### 4.3 Session 请求示例 ```json { "external_subject_id": "", "idempotency_key": "-superagent-session-", "metadata": { "source": "", "purpose": "provider-connectivity-test" } } ``` ### 4.4 SSE 消息请求示例 ```json { "message": "请介绍一下你是谁。", "idempotency_key": "-superagent-message-", "metadata": { "source": "", "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 GET ?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. 最小落地顺序 ### 阶段 1：SuperAgent 连通性 目标： ```text 后端探针 → 创建 SuperAgent Session → 发送一条无敏感信息测试消息 → 解析 SSE 最终回答 → 返回非敏感元数据 ``` 验收： - HTTP 连接成功。 - SSE 收到结束事件。 - 最终回答非空。 - 日志不出现 API Key、Cookie、Session 原始值或个人信息。 ### 阶段 2：AgentBus 连接 目标： ```text AgentBus WebSocket → session.ready → 状态接口可见 connected/sessionReady ``` 验收： - 连接成功。 - 可断线重连。 - 不发送用户回复。 - 不保存本地 raw sample，除非临时排障。 ### 阶段 3：SourceMessage 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 调用失败。