SDK-to-server flow

The SDK is a client wrapper over HTTP and SSE: create sessions, issue prompts, subscribe to events. The server still runs the same SessionPrompt and Bus; the SDK does not add a second execution engine. Choosing sync vs async prompt only changes whether the caller blocks until this turn ends.

Typical connection

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

Create a client with baseUrl, optional directory, custom headers, and fetch. directory travels as a scope header; on GET/HEAD it may also appear in the query so gateways and multi-directory instances can route. When Server is embedded in-process, custom fetch often points at loopback.

Sessions and prompt

Common order: session.create → open event.subscribe → session.prompt or session.promptAsync.

Method	Server	Caller
session.prompt	POST /session/{id}/message, finish this turn then return assistant message	Blocks until done; deltas still via SSE
session.promptAsync	POST .../prompt_async, accept first (for example 204), run in background	Returns immediately; progress only via SSE or later message reads

Without an event subscription first, sync prompt only yields a full blob at the end; async prompt shows almost no intermediate state. Mechanism: HTTP streaming and SSE.

Event subscribe

event.subscribe maps to SSE: connection ack first, periodic heartbeat, then bus events (Part deltas, permission asks, session errors, busy/idle, and so on). A global event channel serves control plane and sync scenarios; in-app session UI main path uses instance-level subscribe.

Auth and scope headers

If the server sets AGENTFORGE_SERVER_PASSWORD, site-wide HTTP Basic Auth applies (except a few health and bootstrap paths). The SDK does not auto-fill the password; put it in headers yourself.

Optional scope headers (enter request context):

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

With identity binding enabled, tenant and role are forced by server account maps; client headers cannot forge privilege escalation. Multi-tenant and RLS: see deployment and isolation notes in the reliability and architecture series.

Minimal integration checklist

1. baseUrl reaches a live runtime; auth headers are correct.
2. event.subscribe before prompt / promptAsync.
3. Handle permission-ask events, or ask tools wait forever.
4. On the async path, listen for session error events; do not only poll the final message.
5. In multi-directory setups, pass directory explicitly to avoid the wrong Instance.

---

Related reading:

• HTTP streaming and SSE
• End-to-end request lifecycle
• Instance boundaries and concurrency