Sessions & chat
How ActionFlows Agent sessions work: starting a session, sending messages, streaming SSE, resuming streams, and how config updates apply.
Sessions & chat
A session is one chat session with an agent. It belongs to an organization, optionally tags an endUserId, and can be started from Studio or the public API. Create and configure the agent itself in Action Agent Studio: the public API only starts sessions and exchanges messages.
Lifecycle
- Start: create a session for an agent. You receive a
sessionId(and an opaqueexternalIdfor internals). No Trigger credentials are returned. - Message: send user text; wait for
{ text }or stream SSE deltas. - Continue: send more messages on the same
sessionId; history is carried by the durable runtime. - Resume (optional): if a stream drops, reconnect with
Last-Event-ID/lastEventId.
Your backend ActionFlows API Agent runtime
| | |
|-- start session --------------->| |
|<-- sessionId -------------------| |
| | |
|-- send message --------------->|-- turn --------------------->|
|<-- text / SSE -----------------|<- tokens / tools ------------|Streaming
Two modes:
| Mode | How | Result |
|---|---|---|
| Wait for reply | POST .../messages with JSON Accept | { "text": "..." } |
| Stream | Same path with Accept: text/event-stream | SSE text-delta then done |
| Resume | GET .../stream + Last-Event-ID | Continue SSE from cursor |
SSE event shapes (public API):
text-delta:{ "type": "text-delta", "delta": "..." }done:{ "type": "done", "text": "..." }(full text)error:{ "type": "error", "message": "..." }
Isolation
Each sessionId maps to one durable Trigger chat session. Do not reuse a session across customers or tenants: start a new session per end user / thread.
Config updates
Saving agent config in Studio bumps configVersion. In-flight turns finish on the version they started with; the next turn loads the latest config.