Open a plan; stream SSE of the orchestration.
Accepts a user question + agent catalog, starts (or resumes) a session, and streams Server-Sent Events as the planner runs.
Session continuation
Pass session_id to resume an existing session — history persists,
the planner sees prior turns. Omit to start a fresh session. The
server returns the resolved session_id in the first SSE frame
(event: session), even for new sessions, so clients can cache it.
Catalog immutability per session
The agents catalog is stored on first plan and refreshed on each
subsequent call; agents added or removed between plans take effect
immediately but don’t retroactively change prior turns’ tool sets.
Streaming & abort
Closing the HTTP connection aborts the plan — in-flight A2A calls
receive an AbortSignal and the planner loop terminates. Clients
that want a partial result should buffer text.delta frames
client-side rather than relying on final.
Authorizations
Shared-secret bearer token(s) configured via config.gateway.auth.tokens.
Validated in constant time against a SHA-256 hash of each configured
token, so neither timing nor length leaks which token matched. Set
gateway.auth.mode: "none" in config to disable bearer auth
(not recommended outside of localhost).
Body
The user's natural-language question. Non-empty — an empty
string is rejected upstream because some LLM providers
(Anthropic) reject empty user messages with a 400 mid-stream,
surfacing as a vague "Provider returned error". Validating
here gives a clean 400 with invalid_request instead.
1"Summarize the latest quarterly results for Apple."
Catalog of A2A peers the planner may call. Empty array = planner runs with no tools (useful for questions the configured planner LLM can answer on its own, e.g., general knowledge).
Caps and shaping hints. All keys are snake_case; an earlier
draft declared them camelCase, which caused docs-compliant clients
to silently lose the caps — the schema is now strict on casing
and unknown keys pass through via additionalProperties: true
for forward compatibility.
Opaque external session identifier. If provided AND a session
row exists with the matching external_session_id, that
session is resumed (history persists). If omitted or
unmatched, a new session is created and its server-assigned
id is surfaced in the first SSE session event.
"client-session-42"
Response
SSE stream of the plan. Each event is one of the types
documented under SSEEvent below. The stream closes after
event: done.
The text/event-stream body is a sequence of event: / data:
pairs. Each data: value is a JSON object matching one of the
SSEEvent_* schemas below. OpenAPI doesn't model SSE natively;
$ref the per-event schemas to generate typed consumers.