Action Agent lifecycle
How an Action Agent moves from passive Action Agent Studio work to active cloud execution, including configVersion, session isolation, credentials, and credits.
Action Agent lifecycle
An Action Agent moves from configuration to execution without a separate build or deployment. You save its configuration in Action Agent Studio, test it in the Action Agent Studio chat dock, and then set it to Active when outside callers and triggers should be able to start work.
The runtime always runs on ActionFlows servers. Action Agent Studio chat and cloud integrations use the same model, tools, Knowledge Base search, and transcript runtime. The active flag controls external session starts and trigger ingress; it does not move model execution into the browser.
Draft, passive, and active
A new agent starts with active: false. The product calls an agent that is still being designed a draft, but the database stores draft and passive as the same state.
| State | Stored value | What works | What does not start |
|---|---|---|---|
| Draft or passive | active: false | Save configuration, run Action Agent Studio chat, inspect sessions and artifacts | New REST, SDK, or hosted MCP sessions; channel or scheduled triggers; Action Agent nodes inside ActionFlows |
| Active | active: true | Action Agent Studio chat, public API/SDK/MCP session starts, eligible trigger ingress, and Action Agent nodes | A turn still fails if its model, credentials, credits, or required tool connection is not ready |
Action Agent Studio is the only session source that can start while the agent is passive. A programmatic start records the internal source as api and rejects a passive agent. Channel and scheduled execution also require an active agent.
Current limitation: active is checked when an external session starts and when trigger ingress is accepted. The runtime does not re-check active when an existing API, SDK, or MCP session sends another message. Deactivation blocks new external starts and new trigger events, but it is not a revocation switch for an existing sessionId.
Activation also checks the organization's active-agent allowance. A plan limit can prevent the transition from passive to active, but activation does not prove that every model, credential, tool, or trigger binding can run a turn.
Configuration ownership
Action Agent Studio owns the agent's runtime configuration:
- the system prompt, model selection, model settings, and Action Agent Studio layout;
- Knowledge Base collections and prompt skills;
- named HTTP tools and outbound MCP attachments; and
- channel and scheduled trigger bindings.
Credential ownership is source-specific. Organization connections own secrets used by organization integrations and triggers, while a named HTTP tool stores its own encrypted authentication payload on the tool record rather than in an organization connection. The agent references these configured resources, but public agent metadata does not copy secret values. See Credential management.
REST, the TypeScript SDK, and hosted MCP are execution surfaces. They can discover an agent and exchange messages, but they cannot create, update, activate, or delete the agent or its Action Agent Studio configuration.
Saving and configVersion
Action Agent Studio autosaves each panel. A successful agent-owned configuration write increments the internal configVersion counter. Skill, tool, MCP, trigger-binding, and Agent settings writes also increment it.
configVersion is a runtime cache invalidation marker. It is not a user-supplied deployment number, an immutable snapshot for a whole turn, or a field in public agent metadata.
The runtime calls the configuration loader during several phases, including worker boot, turn start, tool resolution, provider execution, API relay, and turn completion. A later phase can reload configuration after an agent-owned write. Do not assume that an in-flight turn is frozen to the version observed by its first phase.
Catalog-side edits to linked Service or ServiceModel records do not increment an agent's configVersion. Because those rows are outside the version check, catalog changes can take up to the current 60-second configuration cache TTL to converge in the runtime.
A session does not stay pinned to the configVersion that existed when the session was created. See Model selection and MCP.
Message validation by transport
The currently validated non-streaming REST and hosted MCP message paths trim the message, reject empty text, and enforce a maximum of 100,000 characters. The SDK wait methods use the validated non-streaming REST path. An invalid non-streaming REST request returns 400; hosted MCP reports a tool validation error.
The REST SSE route and the SDK streamActionAgentChat method currently bypass that shared request schema. Do not rely on the 100,000-character limit or a specific 400 response for streaming. Validate streaming messages separately in your application and expect runtime-level errors to differ from the non-streaming path.
Trigger readiness
An active agent is necessary but not sufficient for trigger execution. Before a channel event runs an agent, the runtime also checks:
- the agent is active and belongs to the requested organization;
- the channel binding is active and has the required organization connection or credential;
- the event is enabled and matches the binding scope; and
- the turn can obtain its model configuration, provider credentials, organization credits when applicable, and tool connections.
Binding readiness is derived from channel-specific configuration. For example, a scheduled binding needs a valid schedule and prompt, while an email binding needs a connection and mailbox. See Triggers and Troubleshooting.
The same readiness checks can fail a new public session. A successful POST that starts a session means the session was created, not that a later model turn is guaranteed to succeed.
Action Agent Studio chat and cloud execution
| Action Agent Studio chat | Cloud execution | |
|---|---|---|
| Entry point | The Chat dock in Action Agent Studio | Trigger ingress, REST, TypeScript SDK, hosted MCP, or an Action Agent node in an ActionFlow |
| Active requirement | No | Required when the session starts |
| Session context | The signed-in organization member's latest open Action Agent Studio session for that agent | Integration-defined context; endUserId is optional metadata |
| Configuration | The saved agent configuration | The saved agent configuration, reloaded at multiple runtime phases |
| Runtime location | ActionFlows servers | ActionFlows servers |
| Credentials | Provider and runtime credentials are not exposed to the browser chat UI | Provider and runtime credentials are not returned; the caller's API key remains in its own secret-managed client configuration |
Action Agent Studio chat is an in-product test surface, not a local model. Passive Action Agent Studio chat starts a durable studio session. Reloading the dock resumes that member's latest open Action Agent Studio session for the agent. The Chat dock is not a user-configurable trigger binding. The internal inAppChat source remains for compatibility, while current Action Agent Studio sessions use studio. Public integrations and ActionFlow Action Agent nodes start api source sessions.
Session ownership and isolation
Every session belongs to one organization and one agent. Message, stream, and reconnect operations require the matching organization, agent, and session identifiers. A wrong or foreign sessionId fails instead of creating or opening another conversation.
Sessions can be anonymous or carry optional metadata. endUserId is a correlation label; it is not required, does not authenticate the end user, and does not establish ownership. For an integration that maps product users and conversation threads, use one session per end user or thread as a recommended convention. Store the returned sessionId and reuse it only for that conversation. Do not share a session across organizations or tenants.
Every public start request creates a new session. endUserId does not look up or reopen an existing public session. See Sessions & chat.
Runtime credentials
ActionFlows keeps model-provider keys, organization connections, named HTTP tool authentication payloads, outbound MCP authentication, and the internal chat-runtime credentials on the server. Clients receive only public session identifiers and chat results.
For REST and SDK integrations, keep the organization API key in backend secret management. A hosted MCP client must also authenticate to ActionFlows, but it should store a scoped API key in its secret-managed or environment-backed MCP configuration and inject it as the bearer Authorization header documented in MCP installation. Do not commit the key, place it in source code, or pass it in prompts or tool arguments.
This caller-authentication key is separate from the model-provider keys, organization connection secrets, named HTTP tool authentication payloads, outbound MCP authentication, and internal chat-runtime credentials that ActionFlows keeps on the server. Public agent discovery metadata omits the system prompt, Action Agent Studio layout, tool configuration, MCP configuration, and configVersion.
Credits and usage
Platform-backed agent turns require available organization credits. The runtime checks credits before starting billed model work and records token usage after a completed turn. Open the agent's Usage view in Action Agent Studio to inspect its credit spend. See Usage & cost.
An agent configured with your own model-provider key uses BYOK and does not use ActionFlows platform chat credits. Tool and MCP providers can still have their own external usage or costs. Plan and concurrency limits can also affect activation and session admission; see Limits.
Developer path
- Create an agent and keep it passive while you configure it.
- Select a function-calling model and write the system prompt.
- Attach only the required Knowledge Base collections, skills, tools, and MCP servers.
- Save, then test one or more turns in Action Agent Studio chat.
- Review the transcript and agent Usage view.
- Set the agent to Active when the plan allows it.
- Bind channel or scheduled triggers, or integrate through REST, SDK, or hosted MCP.
- If your product maps users or threads, store one
sessionIdper end user or thread and use the stream resume route after disconnects.