send_action_agent_message
Send one user message to an existing ActionFlows Action Agent session and wait for the completed non-streaming assistant reply.
send_action_agent_message
Send a user message to an existing Action Agent session and wait for the completed assistant reply.
This tool is non-streaming and can take a while. For live text, use the OpenAI-compatible POST /v1/chat/completions endpoint with stream: true (see REST API). Hosted MCP does not stream.
send_action_agent_message never creates a session. Call start_action_agent_session first and pass the returned sessionId.
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.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
actionAgentId | string | Yes | Agent ID that owns the session. |
sessionId | string | Yes | Session ID returned by start_action_agent_session. |
message | string | Yes | Non-empty user text, up to 100,000 characters. |
organizationId | string | Unless the API key is organization-scoped | Same authorized organization used for the session. |
response_format | json or markdown | No | json by default. |
The tool does not accept a source value. Hosted MCP sessions use the same internal api source and sessionId lifecycle as the OpenAI-compatible chat endpoint and the other programmatic surfaces.
This tool is non-streaming and uses the shared gateway message schema. The schema trims the message, rejects empty text, and enforces the 100,000-character maximum. The POST /v1/chat/completions endpoint applies the same trim, empty-text, and 100,000-character checks in both JSON and streaming modes.
Example
{
"actionAgentId": "agent_123",
"sessionId": "sess_123",
"organizationId": "org_123",
"message": "Where is my invoice?"
}Session checks
The actionAgentId, organizationId, and sessionId must identify the same authorized session. A wrong, closed, deleted, or foreign session fails. The tool does not open a replacement conversation.
A public session must have been started while the agent was active. The current runtime does not re-check active when this tool continues an existing session. Deactivation blocks new public starts and new trigger ingress, but it is not session revocation. See Action Agent lifecycle.
endUserId is optional metadata. If your integration models end users or conversation threads, use one session per end user or thread as a recommended convention, and reuse that sessionId only for the same conversation. Sessions can also be anonymous; the runtime does not require an end-user or thread owner.
Return value
With the default JSON format, the tool returns:
{
"success": true,
"result": {
"text": "Your latest invoice is paid."
}
}The current result contains the completed assistant text. It does not expose internal model, tool, MCP, or runtime-credential events.
Streaming and resume
Use one of these surfaces when token-by-token delivery or reconnect behavior is required:
- OpenAI-compatible chat:
POST /v1/chat/completionswith"stream": true. There is no stream-reconnect endpoint; continue the conversation with the same session header.
Do not resend a user message only to recover a disconnected stream. Continue with the same session, as described in Sessions & chat.