Multi-Step Reasoning

Multi-Step Reasoning

Your agent doesn't just search once and answer. It can run up to 5 tool iterations per message — searching, analyzing, refining, searching again, and then delivering a final answer. This is what makes complex questions possible.

How It Works

When your agent receives a message that requires research or verification, it enters an agentic loop:

1. First iteration: Agent decides what to search for, runs a web search
2. Analysis: Agent reads the results, decides if it has enough information
3. Second iteration: If needed, agent runs a follow-up search (different query, deeper angle)
4. Continue: Up to 5 total iterations of search + analysis
5. Final answer: Agent synthesizes everything and delivers the response

On the last iteration (5th), tools are removed from the model's context, forcing it to answer with whatever information it has gathered. This prevents infinite loops.

The Power of Workflow Pipelines

Multi-step reasoning becomes truly powerful when your soul defines a structured pipeline for the agent to follow.

Jackie Check's verification pipeline (check.agenturo.app) is the best example:

<knowledge>
## VERIFICATION PIPELINE
1. DECOMPOSE — break the claim into sub-claims
2. SEARCH — search for each sub-claim independently
3. EVALUATE — assess source quality, recency, consensus
4. JUDGE — deliver verdict with evidence
</knowledge>

When a visitor says "Is it true that Finland has the best education system in the world?", the pipeline drives this multi-step process:

• Iteration 1: Decompose ("best" by what metric?) → Search for Finland education rankings
• Iteration 2: Search for counter-evidence (countries that outrank Finland on specific metrics)
• Iteration 3: Evaluate source quality and recency of findings
• Final: Deliver structured verdict with specific evidence

Without the pipeline, the agent would search once, find a few articles about Finland's education, and give a surface-level "Yes, Finland is known for..." response. With the pipeline, it produces a nuanced, evidence-based answer.

Edge Case Mappings Prevent Waste

Not every question needs 5 iterations. Edge case mappings in your soul can short-circuit the loop for simple cases:

<knowledge>
## EDGE CASES
- If asked a simple factual question with an obvious answer
  (e.g., "What is the capital of France?"): answer directly, no search needed
- If the visitor is just greeting or chatting: respond conversationally,
  don't trigger search
- If the question is about something in your soul's knowledge: answer
  from knowledge, search only if visitor challenges the answer
</knowledge>

This prevents your agent from running a 3-iteration web search when someone says "Hey, what do you do?"

What Visitors See

During multi-step reasoning, visitors see:

• A "searching..." indicator when the agent is running a web search
• A research summary when the agent has completed multiple search steps
• The final answer synthesized from all gathered information

The process typically takes 10-30 seconds depending on the number of iterations and search latency.

Designing for Multi-Step

If your agent handles complex questions, design your soul to leverage multi-step reasoning:

For research agents:

## RESEARCH PROCESS
1. Understand the question — identify what specific information is needed
2. Search broadly — cast a wide net for relevant sources
3. Search deeply — follow up on the most promising results
4. Synthesize — combine findings into a clear, sourced answer

For comparison agents:

## COMPARISON PROCESS
1. Search for information about Option A
2. Search for information about Option B
3. Identify the key comparison dimensions
4. Deliver a structured comparison with clear winner per dimension

For analysis agents:

## ANALYSIS PROCESS
1. Understand what the visitor is asking to analyze
2. Search for relevant context and benchmarks
3. Apply the analysis framework
4. Deliver findings with specific evidence

Limitations

• Maximum 5 iterations — this is a hard cap. Design your pipelines to complete within this limit.
• 15-second timeout per search — individual searches that take too long are cancelled
• Token consumption — each iteration consumes tokens. Multi-step reasoning on complex questions can use 2000-5000 tokens per message.
• Tool discipline matters — without it, the agent narrates every step, doubling the output length. See the Output Format article for tool discipline rules.

When Multi-Step Is Overkill

Not every agent needs multi-step reasoning. A personal brand agent answering "What's your tech stack?" should answer from its soul knowledge in one step. A product agent answering "Do you ship to Germany?" should answer directly.

Multi-step reasoning shines when:

• The answer requires current information from multiple sources
• The question involves comparison or analysis
• Verification against counter-evidence is needed
• The visitor asks something not in the soul's knowledge and web search is needed