Agents in Flows
Conversational Agents are in Beta and available on Professional, Scale and Enterprise.
The Run AI Assistant node hands the conversation to an agent for a bounded conversation, then continues the Flow on a branch. With an agent target, the node can:
- start the agent with a specific skill,
- give it a task (a goal prompt, input variables and an output schema), or use the skill's own goal,
- write the results to flow variables and continue on the
donebranch.
When this node hands the conversation to the agent, the agent answers as part of the flow, whatever the agent's flow_running_behavior or the flow's agent_while_running says. Those settings only govern the agent answering on its own while a run is active, and an agent turned off by stop is turned back on by this node.
The message that started the flow
Whether the agent may also answer, on its own, the incoming message that started the flow is set per flow with agent_reply_to_trigger (auto, always or never; new flows default to auto, flows created before the setting existed behave as never). With auto, a Run AI Assistant node reached before the flow first waits counts as the flow handling the message, so the agent does not answer it separately. The steps agent_reply_allow and agent_reply_silence decide it explicitly when they run before the flow first waits.
We recommend this pattern: let the flow start the agent with this node, instead of letting a flow and an agent both react to the same message.
Node configuration
{
"type": "run_assistant",
"config": {
"target": {"type": "agent", "id": "AGENT_ID"},
"skill_slug": "qualify-lead",
"goal_source": "skill",
"output_variable_prefix": "lead",
"max_turns": 20,
"timeout_enabled": true,
"timeout_seconds": 3600,
"allow_stop_keyword": true
}
}
| Field | Notes |
|---|---|
target | {"type": "agent", "id": "<agent id>"}. Use the agent id, not its bot_id. A bot_id (or target.type: "bot") that belongs to an agent also runs as that agent. |
skill_slug | Optional. The skill to start with. Required for a flow_only skill. |
goal_source | Where the goal comes from: skill, node or none. See below. |
goal_prompt | Task for the agent. Max 4,000 characters. Flow variables are substituted. |
input_variables | Up to 30 values passed to the agent. |
output_schema | The results the agent must return (max 20 properties). |
output_variable_prefix | Results are written to vars.<prefix>.<key>. Default agent. ^[A-Za-z][A-Za-z0-9_]{0,63}$; reserved variable names are rejected when saving. |
max_turns, escalation_threshold, timeout_enabled, timeout_seconds, allow_stop_keyword | As for any Run AI Assistant node. |
The full field reference, including the output_schema format, is on the Run AI Assistant node page.
Goal source
goal_source | The agent works towards |
|---|---|
skill | The goal of the selected skill (the agent's pinned version of it, else the current version). It replaces the node's task. Completing the goal takes the done branch. |
node | The node's own goal_prompt and output_schema. The agent finishes with complete_task. |
none | No skill goal. With a goal_prompt/output_schema the node task is used, otherwise the agent simply converses. |
| not set | skill when the node sets neither goal_prompt nor output_schema properties, otherwise node. |
- With
skill, but the skill has no goal, the node behaves as without a skill goal. - The goal is fixed when the agent starts. Editing the skill later does not change a running session.
- With a skill goal, completion actions still run (save fields, assign, webhook), but
afteris skipped: the Flow continues ondone.
Output variables
When the agent completes, its results are merged into the flow variables:
| Variable | Content |
|---|---|
{{vars.<prefix>.<key>}} | One per output key (task outputs or goal outputs) |
{{vars.<prefix>.goal_completed}} | true when a skill goal was completed |
Only scalar values are written; text is cut at 4,000 characters, at most 20 keys, and multi-select answers at 50 items.
Branches
| Branch | When |
|---|---|
done | The agent completed its task or skill goal. Falls back to completed when not wired. |
completed | max_turns reached, or the session ended. |
escalated | The agent handed over to a human, or the contact used a stop keyword. Also taken when the agent cannot start. Falls back to completed. |
timeout | The contact did not reply within timeout_seconds. |
When the agent cannot start
| Error code | Cause |
|---|---|
plan_not_allowed | The plan does not include Conversational Agents |
agent_not_found | The agent was deleted |
bot_not_found | The agent's bot record is missing |
bot_inactive | The agent is inactive |
The node then takes escalated (or completed if escalated is not wired). With escalated wired, the conversation is opened for your team as an escalation.
Publish checks
| Check | Result |
|---|---|
| The plan does not include Conversational Agents | Error |
| The agent does not exist | Error |
skill_slug does not exist or is archived | Error |
| The agent is inactive | Warning: the node "will take its 'escalated' (or 'completed') branch until it is activated" |
goal_source: "skill" but the skill has no goal for this agent | Warning |
| A branch is not wired | Warning |
Test before publishing
Simulate the node in the test console by sending skill_slug and task:
{
"message": "Hi, I'd like a quote",
"skill_slug": "qualify-lead",
"task": {"goal_prompt": "Collect company size and budget.", "output_schema": {"type": "object", "properties": {"company_size": {"type": "string"}, "budget": {"type": "number"}}, "required": ["company_size"]}}
}
When the agent completes, the response has outcome: "task_completed" and the results in outputs.