SDK 到 Server 完整流程

SDK 是对 HTTP 与 SSE 的客户端封装：创建会话、发起 prompt、订阅事件。服务端仍走同一套 SessionPrompt 与 Bus；SDK 不另起执行引擎。选同步还是异步 prompt，只影响调用方是否阻塞等待本轮结束。

典型连接

flowchart LR
  App[应用] --> SDK[SDK Client]
  SDK -->|HTTP| API[Server 路由]
  SDK -->|SSE| Ev[GET /event]
  API --> SP[SessionPrompt]
  SP --> Bus[Bus]
  Bus --> Ev

创建客户端时指定 baseUrl，可选 directory、自定义 headers 与 fetch。directory 会以作用域头传递；在 GET/HEAD 上也可能反映到 query，便于网关与多目录实例路由。同进程内嵌 Server 时常用自定义 fetch 指向回环。

会话与 prompt

常见顺序：session.create → 建立 event.subscribe → session.prompt 或 session.promptAsync。

方法	服务端	调用方
session.prompt	POST /session/{id}/message，跑完本轮再返回助手消息	阻塞至结束；增量仍靠 SSE
session.promptAsync	POST .../prompt_async，先受理（如 204），后台执行	立即返回；进度只靠 SSE 或事后读消息

未先订阅事件时，同步 prompt 只能在结束时拿到整包；异步 prompt 则几乎看不到中间态。机制见HTTP 流式与 SSE。

事件订阅

event.subscribe 对应 SSE：先收到连接确认，周期性 heartbeat，其余为总线事件（Part 增量、权限询问、会话错误、忙闲状态等）。另有全局事件通道服务控制面与同步场景；应用内会话 UI 主路径用实例级订阅即可。

认证与作用域头

若服务配置了 AGENTFORGE_SERVER_PASSWORD，全站（少数健康与引导路径除外）使用 HTTP Basic Auth。SDK 不会自动填密码，需在 headers 中自行携带。

可选作用域头（进入请求上下文）：

• X-AgentForge-Tenant-Id
• X-AgentForge-Owner-Id
• X-AgentForge-Model-Id
• X-AgentForge-Role
• X-AgentForge-Channel

开启身份绑定后，租户与角色等由服务端账号映射强制，客户端头不能用来伪造提权。多租户与 RLS 见可靠性与架构专栏中的部署与隔离说明。

最小集成检查清单

1. baseUrl 指向可达的运行时，认证头正确。
2. 先 event.subscribe，再 prompt / promptAsync。
3. 处理权限询问类事件，否则 ask 工具会一直等待。
4. 异步路径监听会话错误事件，避免只轮询最终消息。
5. 多目录场景显式传 directory，避免打到错误 Instance。

---

相关阅读：

• HTTP 流式与 SSE
• 端到端主链路
• 实例边界与并发调度