start_action_agent_session
Start one isolated ActionFlows Action Agent session and receive the sessionId required by send_action_agent_message.
start_action_agent_session
Start a new session with an active ActionFlows agent. The tool is non-streaming and returns the identifiers for later send_action_agent_message calls.
Use list_action_agents or get_action_agent first. If you already have a sessionId, call send_action_agent_message instead.
See Installation for authentication and response_format.
A hosted MCP client must authenticate to ActionFlows with a scoped API key. Store that key in the client's secret-managed or environment-backed MCP configuration and inject it as the bearer Authorization header. Do not commit it, place it in source code, or pass it in prompts or tool arguments. This caller key is separate from the provider and runtime credentials that ActionFlows keeps on the server.
Hosted MCP starts always create an internal api source session. They do not create or update the agent, and they do not accept an Action Agent Studio source value.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actionAgentId | string | Yes | Agent ID from list_action_agents or get_action_agent. |
organizationId | string | Unless the API key is organization-scoped | Organization used for authorization and agent lookup. |
endUserId | string | No | Optional correlation label for the end user in your product. |
response_format | json or markdown | No | json by default. |
The tool rejects a passive agent. Action Agent Studio chat can start a session for a passive agent because it uses the internal studio source, but hosted MCP always uses the active-only public start path.
Example
{
"actionAgentId": "agent_123",
"organizationId": "org_123",
"endUserId": "user_abc"
}Session ownership
endUserId is optional correlation metadata, not an ownership or authentication field. If your MCP integration models end users or 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. Every call to this tool creates a new session, and endUserId does not deduplicate or reopen one.
The session belongs to the authorized organization and the selected agent. A message call with another organization, agent, or session fails instead of opening a different conversation.
Return value
With the default JSON format, the tool returns:
{
"success": true,
"session": {
"sessionId": "sess_...",
"externalId": "..."
}
}Use session.sessionId with send_action_agent_message. externalId is an opaque runtime correlation value. The tool does not return an internal runtime token, provider key, prompt, tool configuration, or MCP configuration.
This tool does not stream and has no hosted-MCP resume tool. Use the REST SSE API or TypeScript SDK when you need live tokens or stream resume.