th-hotel-simple/docs/import/reusable/integrations/superagent-agentbus-portable-integration-guide.md

SuperAgent 与 AgentBus 通用对接指南

1. 文档定位

本文记录 SuperAgent 与 AgentBus 接入时可复用的工程边界、配置清单、验证顺序和安全要求。

本文不是官方协议文档，也不保存任何真实 Token、API Key、Session ID、Run ID、消息正文、附件 URL 或个人信息。接入新项目时，应以提供方最新协议、真实测试响应和当前项目业务规则为准。

如果新项目不使用 SuperAgent 或 AgentBus，可以不复制本文。

2. 职责边界

SuperAgent 和 AgentBus 不应被设计成同一个模块。

推荐边界：

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 项目接入时，建议按以下模块复制思路：

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 运行时配置

最小配置建议：

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 调用形态

常见流程：

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 使用同一个临时随机值：

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 请求示例

{
  "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 消息请求示例

{
  "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 平台能力端口

建议定义稳定端口：

public interface AgentCapabilityPort {
    AgentCapabilityResult invoke(AgentCapabilityRequest request);
}

领域层只依赖这个端口，不依赖 SuperAgent HTTP DTO、SSE event、Profile ID 或厂商 SDK。

建议 AgentCapabilityResult 至少包含：

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 运行时配置

最小配置建议：

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 连接

常见连接形态：

Authorization: Bearer <AGENTBUS_WS_TOKEN>
GET <AGENTBUS_WS_URL>?ready=1

连接成功后应能收到 session.ready 或等价就绪事件。

状态查询接口只应返回连接状态、计数器和最近错误代码，不返回 Token 或原始消息。

5.3 入站 frame 处理边界

推荐处理顺序：

收到 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 入站事实。

推荐幂等键：

context_id + provider + channel + external_message_id

重复投递时返回已有 Inbox，不覆盖原始 payload，不创建重复记录。

如果 payload 缺少必要字段或格式不符合预期，也应保存为 FAILED Inbox，并记录安全错误摘要。错误摘要不得包含：

• 消息正文。
• HTML。
• 附件 URL。
• 完整邮箱地址或手机号。
• Token / Cookie / Secret。

5.6 Replay 到业务事件

SourceMessage Inbox 不应等同于正式业务消息。建议增加受控 Replay：

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 连通性

目标：

后端探针
→ 创建 SuperAgent Session
→ 发送一条无敏感信息测试消息
→ 解析 SSE 最终回答
→ 返回非敏感元数据

验收：

• HTTP 连接成功。
• SSE 收到结束事件。
• 最终回答非空。
• 日志不出现 API Key、Cookie、Session 原始值或个人信息。

阶段 2：AgentBus 连接

目标：

AgentBus WebSocket
→ session.ready
→ 状态接口可见 connected/sessionReady

验收：

• 连接成功。
• 可断线重连。
• 不发送用户回复。
• 不保存本地 raw sample，除非临时排障。

阶段 3：SourceMessage Inbox

目标：

AgentBus 入站业务 frame
→ SourceMessage Inbox

验收：

• 正常 payload 保存为 RECEIVED。
• 无效 payload 保存为 FAILED。
• 重复外部消息不重复入库。
• 查询接口只返回安全摘要。

阶段 4：手动 Replay

目标：

SourceMessage Inbox
→ 业务可消费事件 / Evidence

验收：

• 同一 Inbox 可以按不同 replayRunId 多次 replay。
• 相同 replayRunId 幂等。
• Replay 失败有 attempt 记录。
• 响应不返回消息正文、HTML、附件 URL 或 Token。

阶段 5：业务接入 SuperAgent

目标：

业务事件
→ 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 调用失败。