Reasoning Agents
Run a separate native reasoning stage before the main Agent or Team response.
Setup
In an activated virtual environment:
uv pip install -U agno openai
export OPENAI_API_KEY="your_openai_api_key"Use reasoning_model to run a separate native reasoning stage before an Agent or Team produces its main response. Use ReasoningTools when you want a tool-capable model to write explicit planning notes during its ordinary tool loop.
How It Works
Agno's reasoning manager checks whether the configured reasoning_model is a supported native reasoning model. It runs that stage and passes its output into response generation. A non-native model such as GPT-4.1 is not a supported separate reasoner; that stage is skipped with a warning.
The Reasoning Framework
The current framework uses native model reasoning. It no longer implements the former generic six-step prompting loop controlled by reasoning=True. Reasoning output, validation quality, and the number of internal steps depend on the model.
How It Differs by Model Type
A native model can be your main model, with its provider-specific reasoning options, or a separate reasoning_model. For a model without native reasoning, add explicit ReasoningTools to its tool list. See Reasoning Models.
Basic Example
from agno.agent import Agent
from agno.models.openai import OpenAIChat, OpenAIResponses
reasoning_agent = Agent(
model=OpenAIChat(id="gpt-4.1"),
reasoning_model=OpenAIResponses(
id="gpt-5.2", reasoning_effort="medium", reasoning_summary="auto"
),
markdown=True,
)
reasoning_agent.print_response(
"Prove that the sum of the first n odd numbers equals n squared.",
stream=True,
show_full_reasoning=True,
)What You'll See
The main response follows the reasoning stage. When available, show_full_reasoning=True displays the provider-exposed reasoning content or summary. It does not reveal hidden reasoning or guarantee verification, confidence scores, or a fixed number of steps.
Reasoning with Tools
The automatically created reasoning agent receives the reasoning model and run context, but does not automatically copy the main agent's tools. For interleaved research and explicit planning, use ReasoningTools alongside your retrieval tools on the main agent. For custom tools in the separate stage, supply a configured reasoning_agent as shown below and use a native model that supports those tools.
Configuration Options
Display Options
With the agent above:
reasoning_agent.print_response(
"What is 25 * 37?",
stream=True,
show_full_reasoning=True,
)Capturing Reasoning Events
Use stream=True, stream_events=True with run() or arun() to inspect emitted events. Content depends on the selected adapter and model. See the Reasoning Reference.
Iteration Control
reasoning=True, reasoning_min_steps, and reasoning_max_steps are removed constructor arguments. Configure the native model's supported reasoning settings instead. For explicit reasoning tools, ordinary tool-call limits govern the tool loop; they do not count hidden model steps.
Custom Reasoning Agent
A custom agent changes the separate stage's instructions and tools. Set reasoning_model too: it triggers and selects the native reasoning path. Supplying only reasoning_agent does not activate a separate stage.
from agno.agent import Agent
from agno.models.openai import OpenAIChat, OpenAIResponses
native_model = OpenAIResponses(
id="gpt-5.2", reasoning_effort="medium", reasoning_summary="auto"
)
custom_reasoner = Agent(
model=native_model,
instructions="Check the algebra and state the assumptions in your answer.",
)
main_agent = Agent(
model=OpenAIChat(id="gpt-4.1"),
reasoning_model=native_model,
reasoning_agent=custom_reasoner,
)
main_agent.print_response("Find all real roots of x squared minus 5x plus 6.")Example Use Cases
Use a separate stage to evaluate a problem before composing an answer, or to apply specialized instructions to the reasoning pass. For live research, provide retrieval tools and inspect the evidence. A reasoning stage alone does not establish that claims are current or correct.
When to Use Reasoning Agents
Choose a separate stage when its additional output helps your response model. Measure the extra calls, latency, and answer quality on your tasks. For a single native model or an ordinary tool loop, start with that simpler configuration.