Reasoning Modes

The Reasoner setting controls how an agent turns a message into its next action. It affects model selection, response time, token usage, and how reliably the agent can handle complex requests.

Early-stage notice: Agent configuration is under active development. Labels and editor workflows may change. This page describes the current Node-RED runtime behavior.

For most agents, start with Direct. Use Thinker when the selected model benefits from reasoning in plain text before another model converts that reasoning into structured agent actions.

Where To Configure It

In a Smartunit instance:

1. Open Flows.
2. Open the flow containing the agent.
3. Double-click the agent node.
4. Find Reasoner under Properties.
5. Select Direct or Thinker.

The available model fields change with the selected mode:

Mode	Model fields
Direct	Model
Thinker	Think Model and optional Schema Model

Reasoning modes are part of the agent configuration. They do not change the flow wiring or the message format used to call the agent.

Compare The Modes

	Direct	Thinker
Model calls per reasoning step	One	Two
Primary model output	Structured agent actions	Plain-text reasoning
Second model	Not used	Converts reasoning into agent actions
Typical response time	Lower	Higher
Typical token usage	Lower	Higher
Recommended starting point	Yes	For models or tasks that need more reasoning freedom

Direct

Direct uses one model call for each reasoning step.

message and agent context
  -> model reasons and selects actions
  -> structured agent actions
  -> response, skill call, memory action, or another step

The selected Model receives the agent instructions, conversation context, memory, available skills, and the required action format. It must decide what to do and return valid structured actions in the same response.

Choose Direct when:

• You are configuring a new agent and need a reliable baseline.
• The model follows structured-output instructions well.
• Lower latency and token usage are important.
• Requests are usually straightforward or use a small set of skills.

Direct is the default because it is the simplest and most economical mode. A capable model can still plan, use skills, and complete multi-step requests in Direct mode.

Thinker

Thinker separates reasoning from action formatting. Each reasoning step makes two sequential model calls.

message and agent context
  -> Think Model reasons in plain text
  -> Schema Model converts the reasoning
  -> structured agent actions
  -> response, skill call, memory action, or another step

Think Model

The Think Model receives the user message, conversation context, agent instructions, memory, and available skills. It reasons in plain text without also having to produce the final structured action format.

Use a model that is strong at understanding the task, deciding when a skill is needed, and working through complex or ambiguous requests.

Schema Model

The Schema Model converts the Think Model’s reasoning into actions the agent runtime can execute. For example, it may produce a final response, a skill call, or a memory operation.

This model should be dependable at:

• Following strict instructions.
• Returning valid JSON.
• Matching a provided action schema.
• Preserving exact skill IDs and parameters.

The Schema Model can often be smaller or less expensive than the Think Model, provided it remains reliable at structured extraction.

If no Schema Model is selected, Smartunit uses the Think Model for both stages. This is a useful starting configuration, but it does not reduce the process to one call: Thinker still performs separate reasoning and extraction calls.

Choose Thinker when:

• The primary model performs noticeably better when it can reason in plain text.
• Complex skill selection is unreliable in Direct mode.
• The model mixes explanations with structured actions or produces malformed action output.
• Improved reasoning quality is worth additional latency and token usage.

Choosing Models

A practical setup is:

Role	Selection guidance
Direct Model	Strong reasoning and reliable structured output
Think Model	Best available model for reasoning and tool selection
Schema Model	Fast, reliable model for strict JSON and schema matching

Both Thinker models use the connection configured on the agent. Each model keeps the temperature, maximum-token, and top-p settings from its own agent-model configuration.

For the Schema Model, a lower temperature usually produces more consistent extraction. Set its maximum-token limit high enough to return the complete action object, especially when the agent has many skills or complex skill parameters.

When messages can contain images, use models that support the supplied image format. The current message is used during both Thinker stages.

Provider Compatibility

The configured connection must provide an OpenAI-compatible chat completions API. The model used by Direct and the Schema Model used by Thinker must support JSON object responses.

Some providers describe their API as OpenAI-compatible but reject, ignore, or partially implement structured-output options for particular models. If a model works for ordinary chat but the agent reports malformed or missing actions, check the provider’s structured-output support and try a different model.

Cost, Budgets, And Iterations

One agent reasoning step is not the same as one provider request:

• Direct normally makes one provider request per step.
• Thinker normally makes two provider requests per step.

Usage from every request is recorded and counted toward the configured budget. Thinker therefore usually costs more and takes longer than Direct for the same number of agent steps.

The agent’s Max Iterations setting counts reasoning steps, not individual provider requests. For example, five Thinker steps can result in approximately ten model requests, in addition to any other model activity.

Related Settings

Reasoning mode is separate from these settings:

Setting	What it controls
Context	How much conversation history is sent to the agent
Planning	Whether the agent creates and follows an explicit execution plan
Max Iterations	How many reasoning steps a request may use
Budget	Token or spend limits
Skill Set	Which flow actions the agent may call

Changing the reasoner does not enable planning, add skills, or change memory scope.

Debugging And Privacy

When debug mode is enabled, Smartunit records detailed model request and response data. In Thinker mode this can include the Think Model’s plain-text reasoning as well as the Schema Model’s extraction response.

Treat debug events as sensitive. They may contain user messages, memory, instructions, skill details, and intermediate reasoning. Enable debug mode only in trusted environments and avoid sharing unreviewed screenshots or exports.

Troubleshooting

The agent returns invalid or inconsistent actions

Try Direct with a model that is stronger at structured output. If the model understands the task but struggles to combine reasoning with JSON formatting, try Thinker and select a reliable Schema Model.

Thinker is too slow or expensive

Use Direct, reduce the amount of conversation context, or select a faster Schema Model. Do not use a weak Schema Model solely to reduce cost because extraction errors can prevent otherwise good reasoning from being executed.

The Schema Model field is empty

This is valid. Smartunit reuses the Think Model for extraction, while still making two separate calls.

Thinker did not add more agent steps

Thinker changes what happens inside each reasoning step. It does not raise Max Iterations or automatically enable planning.