Sessions & chatCopy Anchor Link

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 sourcesCopy Anchor Link

The runtime stores a source on every session:

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 isolateCopy Anchor Link

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 its transcript and memory per session; client-side history is not replayed.

Durable history and session lifetimeCopy Anchor Link

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 modesCopy Anchor Link

Text deltas are screened by the organization output policy before they reach the wire. Internal model, tool, MCP, and UI events are not part of the public contract.

Lead Agent review gates the terminal resultCopy Anchor Link

When an Action Agent has a Lead Agent and the turn ends through the worker's complete_task protocol, the unreviewed output is withheld:

• Non-streaming: 409 with the OpenAI error envelope, code: "LEAD_REVIEW_PENDING", plus workItemId and revision in error for a gated turn.
• Streaming: the stream ends with the terminal finish_reason: "stop" chunk and [DONE]; content withheld by the gate never arrives. A streamed gated turn carries no workItemId; use the non-streaming request when you need the handle.

The approved submission is delivered later through the Action Agent output-delivery outbox and is recorded on the Lead Review work item, where it is visible in Agent Activity. A new external message is rejected with LEAD_REVIEW_PENDING while a work item is still under review, so poll the work item instead of retrying the send.

DisconnectsCopy Anchor Link

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 metadataCopy Anchor Link

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.

RelatedCopy Anchor Link

• Action Agent lifecycle
• REST API
• TypeScript SDK
• Hosted MCP start session
• Hosted MCP send message
• Limits
• Troubleshooting