Action Agents
Build, test, activate, trigger, and integrate ActionFlows Action Agents through Action Agent Studio, REST, the TypeScript SDK, and hosted MCP.
Action Agents
An Action Agent is a hosted, multi-turn assistant. You configure it in Action Agent Studio, test it in the Action Agent Studio Chat dock, and set it to Active when REST, SDK, hosted MCP, channel triggers, schedules, or ActionFlow nodes should start sessions.
The model, tools, MCP calls, and Knowledge Base search run on ActionFlows servers in every surface. The browser only hosts the Action Agent Studio interface.
Passive agents can be edited and tested in Action Agent Studio. REST, SDK, hosted MCP, and trigger execution require an active agent when they start a new session. See the full lifecycle for the exact active-state checks.
Build an agent
- Create or open an agent. New agents start passive so you can configure them without accepting outside events.
- Choose a model and write the prompt. Use a function-calling model when the agent needs tools or MCP. See Model selection.
- Attach capabilities. Add Knowledge Base, skills, MCP servers, and named HTTP tools.
- Save and test in Action Agent Studio. The Chat dock runs a durable cloud session and works while the agent is passive. Reloading resumes your latest open Action Agent Studio session for that agent.
- Review the result. Check the transcript, artifacts, and the agent's Usage view in Action Agent Studio. Fix the saved configuration and run another turn.
- Activate the agent. Set it to Active when it is ready for external execution. The organization plan must allow another active agent.
- Bind triggers or integrate. Add channel and scheduled triggers, then connect an application through REST, the TypeScript SDK, or hosted MCP.
- Operate the integration. If your product maps users or conversation threads, use one session per end user or thread as a recommended convention. Store its
sessionIdand use the documented stream resume behavior after disconnects.
Lifecycle rules that affect developers
- Draft is a product state, not a database status. Draft and passive agents both store
active: false. - Action Agent Studio chat is the passive exception. It still uses the ActionFlows cloud runtime, but it can start a session without activating the agent. The Chat dock is not a configurable trigger binding.
- Agent-owned writes increment
configVersion. Runtime phases can reload configuration during the same in-flight turn, soconfigVersionis not an immutable whole-turn snapshot. - An active agent is not a deployment. The model, provider credentials, organization credits, tool connections, and trigger binding must also be ready when a turn runs.
endUserIdis optional metadata. Integrations that model users or threads can use one session per end user or thread as a convention; it is not a required session property or authorization boundary.- Deactivation is not session revocation. It blocks new external starts and new trigger ingress, but the current runtime does not re-check
activewhen an existing public session continues. - Caller authentication and runtime secrets use different boundaries. REST and SDK API keys stay in backend secret management. A hosted MCP client stores a scoped API key in secret-managed MCP configuration. Provider and internal runtime credentials remain on ActionFlows servers, and public discovery metadata omits prompts, tools, MCP configuration, and
configVersion.
Read Action Agent lifecycle for the full state, configuration, readiness, credential, and credit contract.
Choose an integration
| Surface | Use it when | Streaming | Session start |
|---|---|---|---|
| REST API | Your backend calls ActionFlows over HTTP | OpenAI-compatible JSON reply or SSE chunks | POST /v1/chat/completions |
| TypeScript SDK | Your TypeScript service lists and inspects agents | Discovery metadata | listActionAgents(...), getActionAgent(...) |
| Hosted MCP | An MCP client calls ActionFlows tools | Non-streaming only | start_action_agent_session |
All three surfaces use the same public agent ID, organization scope, and sessionId lifecycle. REST, SDK, and MCP start requests create an internal api source session. They do not let callers select an Action Agent Studio session source.
Capability map
| Area | Guide |
|---|---|
| Model, prompt, reasoning, and fast mode | Model selection |
| Slack, Discord, Teams, email, and scheduled ingress | Triggers |
| Knowledge Base collections and search tools | Knowledge |
| Organization and platform prompt skills | Skills |
| Outbound MCP servers and tools | MCP |
| Builtin and named HTTP tools | Tools |
| Files generated by agent turns | Artifacts |
| Durable conversations and OpenAI-compatible chat | Sessions & chat |
| Message, session, concurrency, and plan limits | Limits |
| Setup and runtime failures | Troubleshooting |
Public metadata
List and get endpoints return discovery metadata such as id, name, description, active, organizationId, service and model names, tags, and timestamps. They do not return the system prompt, Action Agent Studio layout, tool configuration, MCP configuration, or configVersion. Use Action Agent Studio to change configuration; use the public surfaces to run the saved agent.