Run agent
Step · Stable
Invoke an agent’s full act-and-report loop and surface its RunResult (state / response / outputs / run_id) in context.
Runs a configured agent synchronously in the same DB connection. The agent executes its tool-calling loop (up to max_iters rounds) and returns a final text response. Optionally coerce that reply to a type (bool, number, enum, JSON) so a downstream Branch / Switch gets a typed value instead of prose. Budget-guarded against deep nesting via __run_budget in context. Agent FAILED halts the parent. Result stored under step label as {state, response, parsed, outputs, run_id}.
When to use
Section titled “When to use”Use when a step requires open-ended reasoning or multi-step tool use that cannot be expressed as a fixed sequence — e.g. “research this company and summarise what you find”. The agent’s response text and any outputs it produced are available under the step label for downstream steps to consume.
When not to use
Section titled “When not to use”If the task is a deterministic sequence of known steps, use Run flow — it is cheaper, auditable, and does not consume LLM tokens. For a single LLM call with a structured prompt, use Ask AI instead. Not a vision path: the task input is text only, so an image cannot be handed to the agent directly — use Ask AI (which takes an image input) to read the picture first and pass its text findings in, or grant the agent the OCR / Ask AI skills so it can reach the file itself.
Inputs
Section titled “Inputs”choice · required
The slug (not display name) of a configured agent on this instance — see /agents for the list. The agent runs its own tool-calling loop with its own granted skills, independent of this flow.
Example: research-assistant
- ✓
research-assistant— a general-purpose research agent slug - ✗
Research Assistant— the display name, not the slug — use the lowercase-hyphen slug shown next to the agent in Settings
string · required
The task handed to the agent as its opening instruction — plain prose, not a rigid schema. Template refs pull in upstream values so each run gets a fresh, specific brief instead of a generic one.
Example: Research {{ crm_lookup.name }}'s company and summarise the last funding round in 3 bullets.
- ✓
Research {{ crm_lookup.name }} and summarise recent news.— a concrete, single task with an upstream reference - ✗
Help.— too vague for the agent to act on — give it a concrete task and any facts it needs, it has no memory of this flow
response_format
Section titled “response_format”choice · optional · one of text, int, float, bool, json, json_list, enum
Leave as “text” (free text) unless a downstream Branch/Switch needs a typed value to compare against. “enum” requires the Enum values field below; JSON/JSON list require the JSON fields field below.
Example: text
- ✓
text— default — pass the reply through unchanged - ✓
bool— coerces to yes/no for a downstream Branch - ✗
markdown— not a supported format — choose from the listed options only
response_options
Section titled “response_options”list · optional
Only read when Response format is “enum” — the exact set of strings the agent’s reply is coerced into. Leave empty for any other format.
Example: ["approve", "reject", "escalate"]
- ✓
["approve", "reject", "escalate"]— a tight closed set a Switch step can branch on - ✗
approve, reject, escalate— must be a JSON list, not a comma-separated string
response_schema
Section titled “response_schema”string · optional
Only read when Response format is “json” or “json_list” — the field names/types the agent’s reply is coerced into. Leave empty for any other format.
Example: {"summary": "string", "risk_score": "int"}
- ✓
{"summary": "string", "risk_score": "int"}— two typed fields the agent must fill in its JSON reply - ✗
summary, risk_score— not a schema — needs field:type pairs as JSON, not a bare list
Outputs
Section titled “Outputs”Auto-generated from the skill registry (load_skills()). Do not edit by hand.