Ask Lagan Stream
POST /api/agents/chat/stream
Streaming freeform chat — NDJSON events from start → complete / error.
Each line of the response body is a JSON-encoded AgentChatStreamEvent.
The generator polls request.is_disconnected() on every heartbeat
tick so aborting the fetch stops the generator within one tick even
while idle-waiting on a long tool run. Timeout enforcement mirrors the
blocking endpoint; overrun emits a terminal error event with the
same settings-guidance message plus the correlation id.
Request Body required
Section titled “Request Body required ”Request body for freeform agent chat across core conversational agents.
object
User’s freeform message to the agent
Prior conversation turns. Capped at 50 so the prompt stays bounded — older turns are dropped by the caller.
A single turn in a freeform agent conversation history.
object
Message role (user or assistant)
Message content
Ambient author context attached to a freeform agent request.
Responses
Section titled “ Responses ”NDJSON stream — one AgentChatStreamEvent per line, camelCase keys. Terminal event is always complete or error. Error events carry a short (id: ...) correlation id matching the backend MimeLogger context.
A single NDJSON event emitted by the streaming chat endpoint.
Events follow a discriminated-union shape keyed on type. The UI
branches on that field and reads only the payload fields relevant to
the variant — unused fields stay None.
Variants:
start: emitted immediately, no payload — lets the UI show a “thinking” indicator before the first tool call or text arrives.iteration_start: the tool loop began a new iteration (1-indexediteration). Emitted before the firstdelta/tool_callof each loop pass; useful for UIs that want to clear the in-flight tool chips between multi-turn tool loops.delta: a chunk of assistant text streamed from the model.deltacarries the token(s); concatenate them in arrival order to build the final response.thinking: a chunk of thinking-mode output (the model’s internal reasoning).deltacarries the token(s). UIs can render these in a collapsible reasoning panel or drop them entirely.tool_call: the agent dispatched a tool.tool_callcarries id, name, and parsed arguments. Fires the moment the tool_use block finishes streaming, before the tool actually runs.tool_result: a previously announced tool call finished.tool_callcarries the same id plusresult_preview;duration_msholds the per-tool elapsed time.complete: terminal event. Carries the fullresponsetext, the final list oftool_calls, and totalduration_ms.error: terminal event on failure.messageholds a user-facing description; no further events follow.heartbeat: keep-alive emitted at a bounded cadence when the stream is idle (e.g. waiting on a slow tool). Carries no payload — the transport proof-of-life is the event itself. UIs can safely ignore it (or use it to refresh an elapsed-time counter).
object
Event variant — see class docstring for payload shape.
A single tool invocation Lagan made during a freeform chat turn.
Richer than a bare tool name — the UI can show arguments (so the author sees what Lagan searched for) and, when the agent reports it, a short preview of the result the tool returned.
A single tool invocation Lagan made during a freeform chat turn.
Richer than a bare tool name — the UI can show arguments (so the author sees what Lagan searched for) and, when the agent reports it, a short preview of the result the tool returned.
Validation Error