ReAct Coordinator

The ReAct Coordinator is an orchestration node that answers a question by reasoning and acting in a loop: it thinks, calls a tool, reads the result, and thinks again — until it has enough to answer or a guardrail stops it.

Note

On the agent canvas this component is labelled ReAct Agent. “ReAct Coordinator” is the role it plays: the orchestrating node at the centre of a workflow.

It differs from the Coordinator in one decisive way. The Coordinator decides its whole plan up front and routes to sub-agents along it. The ReAct Coordinator decides one step at a time, using what the last tool actually returned. When you cannot know the second question until you see the answer to the first, this is the component you want.

---

Scenarios

Use the ReAct Coordinator when:

• The next action depends on what the previous one returned — exploratory analysis, debugging, tracing a relationship through data
• The number of steps is genuinely unknown in advance
• You want cost control per step rather than one model for the entire run
• You need hard ceilings on iterations, tokens, spend or wall-clock time
• Tools come from several places at once — canvas components, other saved agents, an HTTP tool server

Use the Coordinator instead when the work decomposes cleanly into known sub-agent calls, since planning it once is cheaper than rediscovering it every turn.

---

How It Works

Phase 1 — Planning

One planning call decomposes the request into ordered steps and assigns each a complexity (LOW / MEDIUM / HIGH) and a tier (low / medium / high). Planning always runs on the high tier — it is the one decision every later step inherits.

The planner is given the recent conversation as context, so follow-ups like “and for the other region?” resolve instead of stalling on a clarification request.

Phase 2 — The ReAct loop

Each turn:

1. Check guardrails. If any cap is spent, the run is forced into a final answer instead of another tool call.

2. Decide. The model reads the transcript so far and returns either a set of tool calls or a final answer, with its reasoning attached.

3. Screen each call. Duplicate, looping, unknown-name, schema-invalid and over-cap calls are refused before execution, each with a reason the model can act on. A consent-gated call is not refused — it pauses the run until the user approves it.

4. Execute and observe. Surviving calls run and their results are appended to the transcript as observations.

5. Repeat until the model answers or a cap fires.

Because the action is written to the transcript before dispatch, the model always sees a coherent thought → action → observation history and does not re-issue a call that has already succeeded. A call that failed stays retryable — see Guardrails.

Phase 3 — Replanning

If a tool fails terminally, the Coordinator replans using what it has learned, rather than continuing down a plan that is already invalid. It will do this up to Max Replans times, which defaults to once.

Phase 4 — Synthesis

The final answer is composed on the high tier. If the run was forced to stop by a cap, it still gets a proper wrap-up turn: the model is told to compose the best answer it can from what it gathered, preserving concrete details, and is offered no further tools.

What the user sees when a cap fires

The wrap-up answer never names the limit that stopped the run — a user cannot act on “it reached its cost limit”, and it exposes how the deployment is budgeted. The reason is still recorded on the decision and in the observability trace.

---

Model Tiering

The Coordinator right-sizes the model per step instead of paying top-tier rates for routine decisions. Configure Model Tiers with a model per tier; leave it empty and every call uses the base model.

Step type	Default tier	Why
Planning / Replanning	high	Sets up everything that follows
Synthesis	high	Composing the final answer is worth paying for
Tool selection	low	Reading the last observation and picking the next call is routing work
Argument filling	low	Mechanical
Routing	low	Mechanical

An explicit tier from the planner overrides these defaults, so a step that genuinely needs more reasoning can ask for it.

Complexity is not the step tier

Task complexity governs how hard the planner thinks — not which model picks the next tool thirty times over. Letting a HIGH complexity verdict promote every tool step roughly doubles run cost and exhausts the cost cap before the run can answer.

Set Model Pricing (USD per 1k tokens, per model) to enable the cost cap. Without it, spend cannot be measured and Max Cost USD has no effect.

---

Where Tools Come From

The Coordinator assembles one flat tool registry from several sources:

Source	What it contributes
Canvas components	Downstream components wired to the node, auto-discovered as callable tools
Connected Agents	Other saved agents, each callable as a single tool
External Toolsets	HTTP/MCP tool servers. Tools are discovered at run start and dispatched over HTTP
Python Toolsets	In-process tool groups, resolved by name. These carry real typed schemas, which canvas components cannot
Web Search	A synthetic web_search tool, when enabled — no canvas node needed
fetch_result	Built in. Lets the model re-fetch an oversized tool result that was clipped in the transcript

Tool Overrides reshapes any of them per tool: hide, rename, requires_consent, per_tool_limit, json_schema.

Observation size

Tool results over 20,000 characters are clipped in the transcript and retained separately. The model fetches the rest with fetch_result — so a large result costs context only when it is actually needed.

---

Configuration

Caution

Max Iterations is the only cap that is on by default. Every other budget cap defaults to 0, meaning unlimited — set them before pointing the agent at expensive tools.

Parameter	Type	Default	Description
Model	string	—	Base model, used when tiering is off or a tier model is unavailable
System Prompt	string	""	Instructions carried on every turn of the loop
Planner Prompt	string	""	Overrides the default planning prompt. Supports {task_input} and {available_tools}
Temperature	number	0.1	Randomness in orchestration decisions
Top P	number	0.3	Nucleus sampling cutoff
Max Output Tokens	number	8192	Output cap per call
Model Tiers	object	{}	{low, medium, high} → model name. Empty disables tiering
Model Pricing	object	{}	USD per 1k tokens per model. Required for the cost cap
Tier Floor / Tier Ceiling	string	low / high	Clamp the tier range the router may use
Max Iterations	number	15	Hard ceiling on loop turns
Max Tokens Budget	number	0	Token budget for the run. 0 = unlimited
Max Cost USD	number	0.0	Spend ceiling. 0 = unlimited. Needs Model Pricing
Max Wall Clock (s)	number	0	Elapsed-time ceiling. 0 = unlimited
Max Tool Calls	number	0	Total tool calls allowed. 0 = unlimited
Max Replans	number	1	Replans allowed after a terminal tool failure
Message History Window	number	6	Prior conversation turns fed to the run so follow-ups resolve
Connected Agents	array	[]	Saved agents exposed as tools
Tool Overrides	object	{}	Per-tool hide / rename / requires_consent / per_tool_limit / json_schema
External Toolsets	array	[]	HTTP/MCP tool servers. Credentials are named as environment variables, never inlined
Python Toolsets	array	[]	In-process tool groups with typed schemas
Consent Agents	array	[]	Tools that must be approved by the user before they run
Web Search	boolean	false	Expose the built-in web_search tool
Use Native Function Calling	boolean	false	Use the provider’s structured tool-call API instead of prompted JSON. More robust on capable models
Execution Mode	string	inprocess	inprocess or distributed
State Store	string	auto	auto, postgres or memory. auto picks Postgres when reachable
Generate Insight	boolean	true	Run the insight pass over large tabular results
Code Gen Prompt	string	""	Overrides the insight code-generation prompt
Insight Prompt	string	""	Overrides the insight prompt

---

Guardrails

These run on every turn and every call, and each refusal is phrased so the model can recover from it rather than repeat it.

Guard	Trigger	Effect
Cap reached	Iterations, tokens, cost, tool calls or wall-clock spent	Forces a high-tier final answer from what was gathered
Duplicate call	The same tool with byte-identical arguments already succeeded	Denied — the answer is already in the transcript
Failure loop	The same call has failed 3 times with identical arguments	Denied, with a redirect to a different tool or to answering
Unknown tool	The name does not resolve	Denied, with the 3 closest real names suggested
Naming loop	8 calls in one run named tools that do not exist	Forces a final answer
Missing argument	A required schema field is absent	Denied, naming the missing field
SQL rejected	The optional SQL validator refuses the query	Denied, with the reason
Per-tool cap	A tool exceeded its per_tool_limit	Denied
Consent required	The tool is consent-gated	Run pauses and waits for user approval

Why a failed call is retried at all

A failure is counted, not banned outright. An identical retry can legitimately succeed — text-to-SQL generates fresh SQL from the same natural-language arguments, and transient tool errors clear. Three attempts cover those; beyond that the call is refused.

---

Execution Modes

Mode	Behaviour
inprocess	Runs in a single process. State lives in memory. Fastest; no persistence, no resume
distributed	Persisted state store with a queue and worker. The run is checkpointed and can be resumed

If any registered tool is consent-gated, the run uses distributed regardless of this setting — a paused run has to be persisted to be resumable.

---

Usage

1. Add the ReAct Agent component to your canvas.

2. Wire the tools it may call downstream of it, and add any Connected Agents, External Toolsets or Python Toolsets.

3. Write a System Prompt describing the agent’s job and when to use which tool.

4. Set Max Iterations, and set Max Cost USD with Model Pricing if the agent has access to expensive tools.

5. Configure Model Tiers to control cost per step. Leave empty to run everything on the base model.

6. Connect the output to an Interact component to return the answer to the user.

---

Best Practices

• Write tool descriptions carefully — they are the only signal the model has when choosing between tools, and a vague one produces wrong calls that still cost a turn.
• Set a cost cap before pointing the agent at expensive tools. Only Max Iterations is capped by default.
• Configure model tiers. Running tool selection on the cheap tier and synthesis on the strong one is where the savings are.
• Prefer typed toolsets over bare canvas components when argument correctness matters — a real schema lets a bad call be refused before it runs.
• Keep Message History Window modest. More context costs tokens on every turn of the loop, not once.
• Turn off downstream auto-repair. Components with their own retry logic (such as ExeSQL’s Loop) should surface errors to the Coordinator instead, since it already restructures and retries failed calls.

---

Troubleshooting

The run stops without a real answer

• Symptom: the reply is a generic “I couldn’t generate an answer for that.”
• Cause: a cap fired before anything usable was gathered. Check the trace for the recorded reason.
• Fix: raise the cap that fired, or narrow the question so fewer steps are needed.

The agent loops on one tool

• Symptom: the same call repeats until the run ends.
• Cause: the tool errors on its arguments, or the model is guessing a name that does not exist.
• Fix: check the tool’s schema and description. The 3-failure and 8-unknown-name guards bound the damage but do not fix the cause.

Runs are more expensive than expected

• Symptom: cost cap hit early, or spend well above a comparable Coordinator run.
• Cause: tiering is off, so every tool step runs on the base model.
• Fix: set Model Tiers. Compare total input tokens per run, not per step — a weaker model that needs more steps can erase the saving.

The cost cap never fires

• Cause: Model Pricing is empty, so spend cannot be computed.
• Fix: add per-model pricing.

Follow-up questions lose context

• Symptom: the agent asks which items you meant.
• Fix: raise Message History Window. It defaults to 6 turns.

Consent prompts never appear

• Cause: the tool is not listed in Consent Agents, or not marked requires_consent in Tool Overrides.
• Fix: add it. The run switches to distributed execution automatically so it can pause and resume.