Chapter 19 · Reasoning and Thinking Models

Learning objectives: Understand two ways Agno lets the model "think one step further" — built-in reasoning flow and native thinking models; learn to use reasoning_model to integrate DeepSeek-R1 class models, and judge which tasks are worth the reasoning overhead.

19.1 Why You Need Reasoning

Standard chat models are "output as you think": for multi-step math, complex planning, or logic-trap tasks, they容易走偏 (easily go astray) at the first step. The essence of reasoning is to let the model generate intermediate thinking steps (draft, decomposition, self-check) before producing the final answer — effectively turning the "thought process" into generated content as well.

Agno provides two paths:

1. Agent's built-in reasoning flow: reasoning=True, letting the Agent reason step by step (Cop's underlying implementation uses prompts and multi-turn calls; reasoning_min_steps/reasoning_max_steps control the step count);
2. Native thinking models: directly use models like DeepSeek-R1 / deepseek-reasoner that have built-in chain-of-thought, or use the reasoning_model parameter to designate a specialized model for reasoning.

19.2 Direct Thinking Model Swap

The simplest approach: swap the model id to a thinking model — zero Agent code changes:

# reasoning_direct.py
import os
from agno.agent import Agent
from agno.models.openai import OpenAIChat

reasoning_agent = Agent(
    model=OpenAIChat(
        id="deepseek-reasoner",              # DeepSeek's thinking model
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    markdown=True,
)

reasoning_agent.print_response("A 3x3 magic square has every row, column, and diagonal summing to 15. Provide one valid filling and verify it.")

At runtime you'll see an output section with the "thinking process" (chain of thought) first, followed by the final answer. Note: thinking models typically do not support (and it is not recommended to) use sampling parameters like temperature; they are also unsuitable for low-latency scenarios.

19.3 Dual-Model with reasoning_model

The reasoning_model parameter lets you designate an independent model solely for reasoning, while the main model handles the final expression — the typical combo is "cheap model does the chores, reasoning model tackles the hard problems," or vice versa "reasoning model produces the plan, cheap model writes the report":

from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    # Main model: responsible for the final response
    model=OpenAIChat(
        id="deepseek-chat",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    # Reasoning model: uses it to step through hard problems first (also accepts "provider:model_id" string)
    reasoning_model=OpenAIChat(
        id="deepseek-reasoner",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    reasoning_min_steps=1,
    reasoning_max_steps=10,   # Upper bound on reasoning steps; controls cost
    markdown=True,
)

agent.print_response("Three letters are randomly placed into three envelopes. What is the probability that all three are in the wrong envelope? Give a complete derivation.")

You can also just set reasoning=True to enable the Agent's built-in stepwise reasoning flow (the reasoning_agent parameter can even accept a custom Agent to act as the "reasoner"), but be aware this significantly increases call rounds:

stepwise_agent = Agent(
    model=OpenAIChat(
        id="deepseek-chat",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    reasoning=True,          # Enable built-in stepwise reasoning flow
    reasoning_max_steps=6,   # Limit steps to control cost and latency
    markdown=True,
)

19.4 Reasoning Overhead and Suitable Scenarios

Reasoning is not a free lunch — every "extra think" means more tokens and longer latency:

Task type	Reasoning recommended?	Reason
Math / logic / constraint solving	✅ Strongly recommended	Chain-of-thought significantly improves accuracy
Multi-step planning, complex decision-making	✅ Recommended	Decomposition and self-check reduce omissions
Casual chat, translation, format conversion	❌ Not recommended	Purely adds latency and cost
Simple RAG Q&A	❌ Generally unnecessary	Retrieval quality is the bottleneck

Common pitfalls

• Passing reasoning=True on top of a thinking model doubles reasoning ("reasoning on top of reasoning"), doubling cost and increasing timeout risk;
• Setting reasoning_max_steps too high may hang a single run() for a long time — always pair with a timeout in production;
• Thinking model outputs contain chain-of-thought content; when doing structured parsing, extract only the final-answer field.

19.5 Synergy with Tools and RAG

Reasoning and retrieval are complementary capabilities: reasoning solves "how to think," RAG solves "what do you know." A typical combo puts the thinking model in the driver's seat of Agentic RAG — reason out "what information do I need," then retrieve, then synthesize:

agent = Agent(
    model=OpenAIChat(
        id="deepseek-reasoner",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    knowledge=knowledge,          # Knowledge base built in Chapter 17
    search_knowledge=True,
    instructions=["First analyze what information the problem requires, then search the knowledge base, and finally answer with evidence."],
    markdown=True,
)

Chapter Summary

• Reasoning = let the model generate intermediate thinking steps before answering; can significantly improve accuracy on logic-heavy tasks;
• Direct approach: swap the model id to a thinking model like deepseek-reasoner; zero code changes;
• reasoning_model designates a dedicated reasoning model for an Agent (accepts a Model object or "provider:model_id" string); reasoning_min_steps/reasoning_max_steps control step count;
• Reasoning has real cost: judge whether it's worth it by task type; don't abuse it on simple tasks;
• Reasoning and RAG/tools are orthogonal — combine freely.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Which parameter lets an Agent use a "dedicated reasoning model" in Agno?

2. Which of the following task types is least suitable for enabling reasoning?

3. What do reasoning_min_steps and reasoning_max_steps control?

4. Regarding thinking model practices, which statement is false?

🛠️ Hands-On Exercises

1. Prepare 5 logic puzzles; answer each with deepseek-chat and deepseek-reasoner separately; record the accuracy difference.
2. Configure a dual-model Agent with reasoning_model; set reasoning_max_steps to 2 and 10 respectively; compare answer quality and latency.
3. Swap the thinking model into the Chapter 17 RAG Agent and observe whether its retrieval keyword choices become more reasonable.

Now that the model knows how to "think," it also needs a full toolkit of "methodologies": Chapter 20: Skills covers that; and "when to pause and ask a human" will be explored in Chapter 21: Human-in-the-Loop and Guardrails.