Your First ReAct Agent

Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: crates/cheng-nodes/src/nodes/builtin/agent, deploy/workflow-templates/tools-user/, crates/cheng-nodes/src/nodes/builtin/tools/tool_hub

Your first workflow built a graph where you decided the order. This one builds an agent: you give it a goal and some tools, and it decides the order at runtime.

About fifteen minutes. You need a running installation and a configured model provider.

When an agent is the right answer

An agent costs more, runs slower, and is less predictable than a plain graph. It earns that when the steps genuinely depend on what earlier steps find — "look through these files and tell me which ones mention X" has no fixed sequence, because the agent cannot know which file to open second until it has read the first.

If you already know the sequence, draw the graph.

The shape

Six nodes. This is the tools-user template's structure, and it is the standard agent layout:

chat/input ─────────────────► agent/react_agent ──► chat/output
                                 ▲       ▲
                  ai/llm_config ─┘       └─ tools/tool_hub ──► tools/file_ops_hub

chat/input receives the user's message.
ai/llm_config holds the model choice, wired into the agent rather than typed into it — so one config node can serve several nodes.
agent/react_agent is the loop.
tools/tool_hub presents many tools behind one stable function.
tools/file_ops_hub is the actual capability, in this example file operations.
chat/output returns the answer.

Step 1 — Start from the template

Rather than building from scratch, install the tools-user template — see Workflow Templates. You get the layout above, already wired, and can read it before you change it. Open it in the editor.

If you prefer to build it by hand, drag the six nodes on and connect them as drawn: input to the agent's task input, llm_config to the agent's llm_config, the tool hub to the agent's tools port, and the agent's answer to chat/output.

Step 2 — Configure the model

Select ai/llm_config and pick a provider and model.

One thing to check before going further: the agent's use_function_calling defaults to true, and not every provider declares native tool calling. In the shipped providers.toml, Anthropic and Ollama do not declare native_tool_calling, so an agent with use_function_calling = true will not work on those. Pick a provider that declares it — see LLM & Model Configuration. This is the single most common reason a first agent does nothing.

Step 3 — Give it tools

Select tools/file_ops_hub and turn on the operations you want it to have. Read operations are safe to enable; leave writes off for a first run.

Then look at tools/tool_hub. Its job is to put many tools behind one function the model calls, instead of growing the model's tool list until the list itself eats the context window. For a first agent the defaults are fine.

Step 4 — Set the iteration budget

Select agent/react_agent:

Setting	For a first agent
`max_iterations`	`10` (the default) is plenty
`use_function_calling`	Leave `true` — see step 2
`use_llm_evaluation`	Leave `false` for now
`task_run_mode`	`short` (the default)

short mode means: when the iteration budget runs out, pause and ask you rather than stopping silently. That is what you want while learning — an agent that quietly gives up is much harder to debug than one that says it ran out of room.

Step 5 — Run it

Use the chat panel beside the canvas and ask for something that genuinely requires looking around, for example:

List the files in the workspace and tell me which one is the largest.

Watch the run. Each iteration renders as its own group: the reasoning, the tool call with its arguments, the result, then the next iteration. This is the part worth staring at — you are seeing the agent's actual decisions, not a summary of them.

Step 6 — Read the trace

The agent returns more than an answer:

Output	Use it for
`final_answer`	The result
`trace`	Every reasoning step and tool call
`iterations_used`	How much of the budget it needed
`total_tokens`	Cost
`success`	Whether it completed

iterations_used is the number to watch. Hitting max_iterations every time means the task is too big for the budget or the tools are wrong for it — raising the ceiling usually treats the symptom.

When it goes wrong

Symptom	Cause
The agent does nothing, or replies without calling tools	The provider does not support native tool calling — see step 2
It calls a tool with nonsense arguments	The tool description is unclear; a skill with usage guidance fixes this better than prompt tweaks
It loops on the same call	The tool is returning an error the agent cannot interpret; check the trace for the actual result text
It stops too early	Its completion judgment is wrong; try `use_llm_evaluation = true`
It runs forever	You are in `long` mode without progress limits, or the task has no terminal state

Where to go next

Once the loop works, the useful upgrades are:

Better tools. An agent is only as good as what it can call. Add MCP servers or skills.
Approval gates. Before enabling write operations, put an approval gate in front of them so you confirm each dangerous action.
long mode. For multi-step autonomous work, switch task_run_mode to long, which renews the agent's budget as long as it is making progress.

Next steps

ReAct Agent Guide — every setting in depth.
Tool Discovery & Tool Hub — scaling past a handful of tools.
Approvals & Human Review — before you enable writes.