Agents in Flows

Beta

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 done branch.

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 after is skipped: the Flow continues on done.

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.

Node configuration​

Goal source​

Output variables​

Branches​

When the agent cannot start​

Publish checks​

Test before publishing​