ActionFlows Action Agent session sources, durable history, isolation, limits, and the OpenAI-compatible chat completions contract.

Sessions & chat

An Action Agent session is one durable conversation. It belongs to one organization and one agent, stores user and assistant messages, and is driven by the OpenAI-compatible chat endpoint.

Session sources

The runtime stores a source on every session:

Source	Created by	Current behavior
`studio`	The Action Agent Studio Chat dock	A signed-in member continues their latest open Action Agent Studio session for that agent. Action Agent Studio sessions can start while the agent is passive.
`api`	`POST /v1/chat/completions`, hosted MCP, and ActionFlow Action Agent nodes	These execution surfaces record `api`.
`slack`, `teams`, `discord`, `email`	Configurable agent trigger ingress	The source identifies the external channel that created the session.
`inAppChat`	Internal or legacy compatibility paths	The enum and channel mapping remain; Action Agent Studio does not offer in-app chat as a configurable trigger.
`scheduled`	Scheduled agent runs	Each due schedule tick creates a new scheduled session.
`explore`	Explore and visitor-facing agent chat	The surface can resume an open visitor session by its stored visitor key.
`dashboardChat`	A signed-in member's dashboard agent chat	`/chat/sessions/{sessionId}` is this source. The operator thread at `/chat` is not an Action Agent session.
`leadReview`	A Lead Agent review execution	Created for the review attempt. Callers cannot select this source. See Lead Review.
`inWebChat`	Defined by the current internal session-source enum	This value is internal. It is not a public request field.

source is not an authorization field and is not accepted as a supported integration choice. The OpenAI-compatible endpoint, hosted MCP, and ActionFlow Action Agent nodes all record api.

Start, continue, and isolate

Your backend                     ActionFlows API                 Agent runtime
     |                                 |                              |
     |-- POST /v1/chat/completions --->|                              |
     |<-- 200 + X-ActionFlows-Session-Id                              |
     |<-- JSON reply or OpenAI SSE ----|<- tokens and tools ----------|

A request without X-ActionFlows-Session-Id starts a new session for an active agent. The response header carries the new sessionId. Optional user is stored as endUserId correlation metadata; it is not an ownership or authentication field.
A request with X-ActionFlows-Session-Id continues that session. The session must belong to the same agent and the caller's organization and be open. A wrong, closed, deleted, or foreign id returns 404 (session_not_found); it never creates a replacement session.
Only the last user message of the OpenAI messages array drives the turn. The agent owns the transcript for that session; client-side history is not replayed. Opt-in facts about a signed-in member are a separate store. See Memory.

A public session can start only while the agent is active. The current runtime does not check active again when that session sends another message. Deactivation blocks new public starts and trigger ingress, but it does not revoke an existing sessionId. See Action Agent lifecycle.

Durable history and session lifetime

User and assistant messages are stored in the session transcript. When the same session continues, the runtime loads that history for the next turn. The authenticated API has no session-list, close, or full-transcript endpoint.

Action Agent Studio restores a bounded page from the signed-in member's latest open Action Agent Studio session. The separate public Explore visitor route, POST /api/explore/action-agents/{slug}/session, can return a bounded transcript (up to 50 newest non-empty messages, oldest first) when it resumes an open visitor session. It is not part of the authenticated surface.

The chat worker has separate execution limits:

Idle timeout: 10 minutes without a message. The worker suspends and can resume on a later message or preload.
Maximum chat-run duration: 1 hour.
Turn timeout: 10 minutes.

These values limit a runtime worker. They do not delete the durable transcript and are not a public close operation.

POST /v1/chat/completions trims the last user message, rejects empty text, and enforces a maximum of 100,000 characters in both JSON and streaming modes.

Response modes

Mode	Request	Result
Wait for reply	`stream` omitted or `false`	`chat.completion` JSON after the turn completes
Stream a new turn	`"stream": true`	OpenAI `chat.completion.chunk` frames followed by `data: [DONE]`, or one `{"error": ...}` frame on failure
Lead Agent review	Either mode, after the worker calls `complete_task`, or while a review is already open	The unreviewed terminal result is withheld. JSON returns `409` with `LEAD_REVIEW_PENDING`. OpenAI SSE ends with `finish_reason: "stop"` and no further content. A lead-enabled turn that never calls `complete_task` returns the assistant text.

Published output guardrail rules screen text before it reaches the wire. With no published output rules, that screen does not run and deltas go out as produced. Internal model, tool, MCP, and UI events are not part of the public contract.

Lead Agent review gates the terminal result

When the worker calls complete_task on an inProgress Lead Review work item, the unreviewed output is withheld. The same 409 is returned when the session already has a non-terminal work item that is no longer inProgress.

Non-streaming, gated complete_task: 409 with the OpenAI error envelope and code: "LEAD_REVIEW_PENDING". workItemId and revision are included and are null.
Non-streaming, review already open: the same status and code. Those two fields are omitted.
Streaming: a gated turn ends with finish_reason: "stop" and [DONE]. It carries no work-item id. A busy intake returns 409 before the stream starts.

For api and Action Agent Studio, approval reveals the stored assistant message in the transcript. The original HTTP response is not sent again. There is no public endpoint to poll the work item. See Lead Review.

Disconnects

There is no stream-reconnect endpoint. If the connection drops mid-turn, the turn still completes and persists; send the next request with the same X-ActionFlows-Session-Id header to continue the conversation. Do not resend a message that already produced a reply unless your integration is safe to duplicate; sessions do not deduplicate by client message id.

Runtime credentials and metadata

The endpoint never returns or accepts an internal chat-runtime token; keep REST and MCP API keys in backend secret management. Public list and get operations return discovery metadata only; they omit the system prompt, Action Agent Studio layout, tools, MCP configuration, and configVersion.

Sessions & chat

Sessions & chatCopy Anchor Link

Session sourcesCopy Anchor Link

Start, continue, and isolateCopy Anchor Link

Durable history and session lifetimeCopy Anchor Link

Response modesCopy Anchor Link

Lead Agent review gates the terminal resultCopy Anchor Link

DisconnectsCopy Anchor Link

Runtime credentials and metadataCopy Anchor Link

RelatedCopy Anchor Link

On this page

Sessions & chat

Session sources

Start, continue, and isolate

Durable history and session lifetime

Response modes

Lead Agent review gates the terminal result

Disconnects

Runtime credentials and metadata

Related