AgentHub AI Agent 接入指引（孵化新 SaaS 用）

读者：AI coding agent（或人类工程师），正在孵化一款新 SaaS，需要把「AI 多轮会话 Agent + 多模态 + 知识库 + 计费」能力接到自己的产品上，而不是自建。 目的：一次读完即可顺畅衔接 AgentHub 的全部对外能力，避开所有已知坑（坑均带实证编号）。 先读：platform-status.md（能承诺什么）+ llms.txt（索引）。 契约：端点以活 FastAPI + 各 how-to 的 curl 为准。仓库 openapi.yaml 是契约文件，部分 schema 滞后（Agent 注册/发布、KB 创建、users:provision）——不要只抄 openapi 里那几份创建体。 可复制执行版：模式 A 逐条 curl 见 saas-integration-cookbook.md。 状态基准：2026-09-03。PE 代码面已收官；Google / PayPal / 微信真收款未开闸；微信登录后移大陆回迁。

---

0. 心智模型（30 秒）

你的 SaaS = 业务壳（自己的前端 / 可选自有后端 / 可选自有用户体系）；AgentHub = headless 会话 Agent 运行时：

你的 SaaS ──(模式 B: 浏览器 JWT  |  模式 A: API-Key + 影子用户)──► AgentHub
        ├── 模型网关（多供应商 vendor/路由/能力标记）
        ├── 会话 Agent（多轮 + SSE 流式 + 工具 + 护栏）
        ├── 知识库（结构感知分块 / 父子检索 / hybrid）
        ├── 多模态（STT / TTS / 附件 / vision / 文生图）
        └── 积分计费（freeze→settle；充值双通道代码在、开闸另算）

自营 / 孵化走模式 B（mode-b 指南 + 品牌自托管）。只有你已经有自己的用户体系时才走模式 A。

1. 环境与凭据（两条通道，别混）

通道	谁用	凭据	典型端点
管理面（builder）	运营者/开发 agent，建模与发布	Keycloak JWT（用户登录或 M2M client credentials）	/api/v1/builder/*
运行面（app/headless）	模式 A：你的服务端代表终端用户	X-AgentHub-Api-Key: ahk_... + X-AgentHub-On-Behalf-Of: <shadow_user_id>	/api/v1/app/conversations*
运行面（浏览器）	模式 B：终端用户本人	平台 JWT（仅本人，不要把 API-Key 放进前端）	同一组 /api/v1/app/conversations*

• API-Key 经管理面签发（delivery:api_key:write），明文只返回一次，支持 :rotate / :revoke；
• 模式 A：终端用户先映射为影子用户（POST /api/v1/identity/users:provision，username = 你侧不可变用户 ID）。该路径在活 API 上，仓库 openapi 可能尚未收录；
• 积分入账到该租户下的对应用户钱包；域内多项目共享余额，流水带 project_id；
• 品牌产品线：iss 是 https://<品牌域>/auth/realms/<realm>，不是一律 agenthub。token realm ≠ 租户 realm → 403。

2. 一次性资源建模（管理面，按序）

完整 curl 见 hello-agent §2 / §10.1。顺序与约束：

1. Vendor：POST /api/v1/builder/model-vendors——code / api_base / protocol_family（openai_compatible | dashscope）。解析顺序 租户表 > 服务器 env > 内置。
2. 模型注册：POST /api/v1/builder/models——model_type（llm / stt / tts / image_gen / embedding）+ vendor + vault key 引用（key 只入 OpenBao，永不回显）。
   • stt/tts 的 vendor 必须 dashscope；
   • 视觉模型 = 普通 llm + capabilities: ["vision"]；
   • 非 LLM 模态必填 unit_price/price_unit（second/char/image），否则首次调用 500 MODEL_USAGE_METADATA_MISSING。
3. 路由：POST /api/v1/builder/routes（按组 upsert）——chat 路由把 vision 模型放 fallback 位。
4. 知识库（可选）：见 knowledge-base-retrieval.md。创建体是 {project_id,name,embedding_model_id,embedding_dim:1536,chunk_strategy}，不要抄 openapi 里的 scope/slug 形状。
5. 会话 Agent + 发布（活 API AgentCreateIn / AgentPublishIn）：
   • 创建：{"project_id","code","name","agent_type":"conversation"}（model_group_id 不在创建体，绑在发布 bindings）；
   • 发布：{"agent_id","expected_agent_version","role_card","bindings","conversation"}；
   • conversation 必须含 points_per_turn + guardrails 五项全填（max_input_tokens / max_attachments / max_tool_calls / max_sop_invocations / turn_timeout_seconds）；
   • speech 组价与护栏配对（STT：points_per_transcription+max_audio_seconds；TTS：points_per_speech+max_tts_chars，可加 voice）；
   • guardrails.max_images_per_turn 缺席则 generate_image 不注册；
   • turn_timeout_seconds 对画图/SOP 建议 ≥180（默认 60 会掐断在跑工具）。
6. 发布前冒烟：POST /api/v1/builder/agents/{id}/chat-dry-run——零计费零落库。

建项目：web-builder Projects 页，或 POST /api/v1/builder/projects（hello-agent §2.1）。该路径同样可能未进 openapi，以活 API 为准。

3. 运行时：会话与轮次（运行面）

POST /api/v1/app/conversations {"agent_id": "..."}          # → 201 data.id
POST /api/v1/app/conversations/{id}/turns {"content_blocks":[...]}
# 帧序：turn_started → turn_delta* → [turn_card] → [turn_file*] → turn_completed

• 输入块：text / file / page_ref / activity；卡片回传 choice_selection；
• 断连重拉：凭首帧 turn_id GET .../turns/{turn_id}，不重跑不重复扣费；
• 版本冻结：会话钉死打开时的 agent_version，发新版须开新会话；
• client_conversation_key：同 key 返回既有会话；要新会话就换 key；
• 结束：POST .../{id}:end。空闲超时也会闭合。
• JSON 成功路径多为 Envelope；SSE 无信封。

4. 多模态四件套（均已真栈实证）

能力	端点	关键约束 / 已知坑
语音→文字	POST .../transcriptions（multipart audio）	带参 MIME（audio/webm;codecs=opus）已接受；上游高峰 85s+ 正常；data.text 给用户改完再当 text 轮
文字→语音	POST .../messages/{message_id}/speech	(message_id, voice) 缓存零扣点；longanyang 可用；返回签名 URL
附件 + 图片理解	authorize → PUT 直传 → commit	图片：路由有 vision 则原生 image_url parts（7MB/图），否则 vision_deferred。发轮带 {"type":"file","file_id":...}
文生图	自然语言触发 generate_image	快照要有 max_images_per_turn + 可达 image_gen；SSE turn_file；并入轮次价

工具协议：桥内文本 JSON；解析器容忍裸 JSON / markdown fence / <tool_call> / 散文包裹（#299）。

5. 知识库

见 knowledge-base-retrieval.md。接入方要记住：

• 创建后把 KB_ID 放进发布 bindings.knowledge_base_ids；
• 运行时不要自己打 search，让 kb_search 带 chapter_path 回来；
• 改 chunk_strategy 必须 rebuild 才生效；legacy 库不 rebuild 则旧切法不变；
• hybrid:true 是建设态调试检索开关；会话工具默认走服务端检索管线（含父子上卷与体量预算）。

6. 计费、充值、开闸

• 轮次：freeze(operation_id=turn:{turn_id}) → settle（失败 unfreeze）；余额不足 → 402 POINTS_INSUFFICIENT 零副作用；低余额 → balance_warning；
• 按次：stt: / tts:；文生图并入轮次；
• 入账：开闸前 tenant_grant（expires_at 必填）。目录与双通道见 payment-and-recharge.md；
• 不要对用户说「已经可以用 Google 登录 / PayPal 付款 / 微信扫码付款」，除非运维确认闸门已开（platform-status.md §2~§3）。

7. 已知坑速查（全部实证）

症状	根因	处置
STT 返回的是转写指令复读	旧线形纯文本调用（#296 已修）	已修；勿再引用 file_urls+prompt
转写「转写中」很久	上游高峰排队（85s+）	等；UX 提示未做
轮次 60s 后空白「成功」	墙钟掐断在跑工具被静默吞掉	发布时 turn_timeout_seconds ≥ 180
助手回复一堆 JSON 代码	工具协议散文包裹泄漏（#299 已修）	已修
图片「只传了注记」不识图	chat 路由无 vision 端点	注册 vision 模型放 fallback
模型首次调用 500 MODEL_USAGE_METADATA_MISSING	注册缺单价	补 unit_price/price_unit
语音/画图 url error	Token Plan 网关仅服务 chat	语音/画图走经典 DashScope 网关
新版本不生效	会话版本冻结（设计）	开新会话
按 openapi 创建 Agent 422	仓库 schema 滞后	抄 hello-agent §10.1 / cookbook §3
按 openapi 创建 KB 422	仓库 schema 仍是 scope/slug	抄 knowledge-base-retrieval.md §1
终端积分页 403	已过期（saas_user 已含只读 billing scope）	升级后的环境应 200；仍 403 则查角色是否旧种子
PAYPAL_WEB 下单 503	未开闸（设计）	隐藏支付按钮，用 tenant_grant

8. 建议接入顺序（冒烟阶梯）

1. 读 platform-status.md + mode-b 或 cookbook；
2. chat-dry-run 冒烟；
3. 最小会话：开 conversation → 1 轮 text → SSE 三帧齐 → :end；
4. 需要 RAG：建 KB → rebuild → 绑定 → 再问文档题；
5. 逐项多模态：附件 → STT → TTS → vision → 文生图；
6. 计费对账：ledger 的 freeze/settle/unfreeze；
7. 工程化：断连重拉、402、balance_warning；
8. 上线一条产品线：brand-self-hosted-deployment-guide.md。

9. 事实源指针

主题	位置
能力现状	platform-status.md
端点契约	openapi.yaml
curl 级全流程	tutorial/hello-agent.md
知识库	knowledge-base-retrieval.md
支付	payment-and-recharge.md
品牌部署	brand-self-hosted-deployment-guide.md
会话协议	conversation-runtime-protocol.md

纪律：① 创建/发布形状抄 how-to，不要凭记忆或只抄滞后 schema；② 上游延迟（STT 高峰 / T2I 30~90s）纳入超时与 UX；③ 开闸类能力未在 platform-status §2 翻绿前，不要写进面向用户的说明。