Reasoning Reference

This reference covers the core data structures and events used across all reasoning approaches in Agno (Reasoning Models, Reasoning Tools, and Reasoning Agents).

ReasoningStep

ReasoningStep represents a structured reasoning step carried by tools or events. Native model reasoning can also arrive as text deltas; it is not always converted to this structure.

Attributes

Attribute	Type	Default	Description
`title`	`Optional[str]`	`None`	A concise title for this reasoning step
`reasoning`	`Optional[str]`	`None`	The detailed thought process or reasoning for this step
`action`	`Optional[str]`	`None`	The action to be taken based on this reasoning
`result`	`Optional[str]`	`None`	The outcome or result of executing the action
`next_action`	`Optional[NextAction]`	`None`	What to do next (continue, validate, final_answer, reset)
`confidence`	`Optional[float]`	`None`	Confidence level for this step (0.0 to 1.0)

NextAction Enum

The NextAction enum defines possible next steps in the reasoning process:

Value	Description
`CONTINUE`	Continue with more reasoning steps
`VALIDATE`	Validate the current solution before finalizing
`FINAL_ANSWER`	Ready to provide the final answer
`RESET`	Reset and restart the reasoning process (error detected)

ReasoningSteps

ReasoningSteps is a container for structured reasoning steps in outputs and events. It does not configure an iterative reasoning loop.

Attributes

Attribute	Type	Default	Description
`reasoning_steps`	`List[ReasoningStep]`	Required	List of reasoning steps taken

ReasoningTools

The ReasoningTools toolkit provides explicit tools for structured thinking.

Constructor Parameters

Parameter	Type	Default	Description
`enable_think`	`bool`	`True`	Enable the `think()` tool
`enable_analyze`	`bool`	`True`	Enable the `analyze()` tool
`all`	`bool`	`False`	Legacy parameter to enable both tools
`instructions`	`Optional[str]`	`None`	Custom instructions for using the tools
`add_instructions`	`bool`	`False`	Add default instructions to agent
`add_few_shot`	`bool`	`False`	Add few-shot examples to instructions
`few_shot_examples`	`Optional[str]`	`None`	Custom few-shot examples

Methods

think()

Use as a scratchpad to reason about problems step-by-step.

Parameters:

Parameter	Type	Default	Description
`run_context`	`RunContext`	Required	Run context (automatically injected)
`title`	`str`	Required	Concise title for this thinking step
`thought`	`str`	Required	Detailed reasoning for this step
`action`	`Optional[str]`	`None`	What you'll do based on this thought
`confidence`	`float`	`0.8`	Confidence level (0.0 to 1.0)

Returns: str - Formatted list of all reasoning steps taken so far

analyze()

Analyze results from previous actions and determine next steps.

Parameters:

Parameter	Type	Default	Description
`run_context`	`RunContext`	Required	Run context (automatically injected)
`title`	`str`	Required	Concise title for this analysis
`result`	`str`	Required	Outcome of the previous action
`analysis`	`str`	Required	Your evaluation of the results
`next_action`	`str`	`"continue"`	What to do next: "continue", "validate", or "final_answer"
`confidence`	`float`	`0.8`	Confidence level (0.0 to 1.0)

Returns: str - Formatted list of all reasoning steps taken so far

Reasoning Events

Events emitted during reasoning processes when using Reasoning Agents or Reasoning Models.

Event Types

Event Type	Description
`ReasoningStarted`	Indicates the start of the reasoning process
`ReasoningStep`	Contains a single reasoning step
`ReasoningContentDelta`	Streams a chunk of reasoning content
`ReasoningCompleted`	Signals completion of the reasoning process

ReasoningStartedEvent

Emitted when reasoning begins.

Attributes:

Attribute	Type	Default	Description
`event`	`str`	`"ReasoningStarted"`	Event type
`run_id`	`Optional[str]`	`None`	ID of the current run
`parent_run_id`	`Optional[str]`	`None`	ID of the parent run, when nested
`agent_id`	`str`	`""`	ID of the reasoning agent
`agent_name`	`str`	`""`	Name of the reasoning agent
`session_id`	`Optional[str]`	`None`	ID of the session
`workflow_id`	`Optional[str]`	`None`	ID of the workflow, when run inside a workflow
`workflow_run_id`	`Optional[str]`	`None`	ID of the workflow run
`step_id`	`Optional[str]`	`None`	ID of the workflow step
`step_name`	`Optional[str]`	`None`	Name of the workflow step
`step_index`	`Optional[int]`	`None`	Index of the workflow step
`nested_depth`	`int`	`0`	Nesting depth: 0 for top-level, incremented per nested workflow
`tools`	`Optional[List[ToolExecution]]`	`None`	Tool executions associated with the event
`created_at`	`int`	Current timestamp	Unix timestamp of event creation

ReasoningStepEvent

Emitted for each reasoning step during the process.

Attributes:

Attribute	Type	Default	Description
`event`	`str`	`"ReasoningStep"`	Event type
`content`	`Optional[Any]`	`None`	Content of the reasoning step
`content_type`	`str`	`"str"`	Type of the content
`reasoning_content`	`str`	`""`	Detailed reasoning content for this step
`run_id`	`Optional[str]`	`None`	ID of the current run
`parent_run_id`	`Optional[str]`	`None`	ID of the parent run, when nested
`agent_id`	`str`	`""`	ID of the reasoning agent
`agent_name`	`str`	`""`	Name of the reasoning agent
`session_id`	`Optional[str]`	`None`	ID of the session
`workflow_id`	`Optional[str]`	`None`	ID of the workflow, when run inside a workflow
`workflow_run_id`	`Optional[str]`	`None`	ID of the workflow run
`step_id`	`Optional[str]`	`None`	ID of the workflow step
`step_name`	`Optional[str]`	`None`	Name of the workflow step
`step_index`	`Optional[int]`	`None`	Index of the workflow step
`nested_depth`	`int`	`0`	Nesting depth: 0 for top-level, incremented per nested workflow
`tools`	`Optional[List[ToolExecution]]`	`None`	Tool executions associated with the event
`created_at`	`int`	Current timestamp	Unix timestamp of event creation

Emitted for each chunk of reasoning content as it streams. Inherits the identity, timing, and workflow context fields of BaseAgentRunEvent, like ReasoningStartedEvent. It inherits the backward-compatible content field but does not define content_type; reasoning deltas are in reasoning_content. Its own fields are:

Attribute	Type	Default	Description
`event`	`str`	`"ReasoningContentDelta"`	Event type
`reasoning_content`	`str`	`""`	The chunk of reasoning content

ReasoningCompletedEvent

Emitted when reasoning finishes.

Attributes:

Attribute	Type	Default	Description
`event`	`str`	`"ReasoningCompleted"`	Event type
`content`	`Optional[Any]`	`None`	Final reasoning content
`content_type`	`str`	`"str"`	Type of the content
`run_id`	`Optional[str]`	`None`	ID of the current run
`parent_run_id`	`Optional[str]`	`None`	ID of the parent run, when nested
`agent_id`	`str`	`""`	ID of the reasoning agent
`agent_name`	`str`	`""`	Name of the reasoning agent
`session_id`	`Optional[str]`	`None`	ID of the session
`workflow_id`	`Optional[str]`	`None`	ID of the workflow, when run inside a workflow
`workflow_run_id`	`Optional[str]`	`None`	ID of the workflow run
`step_id`	`Optional[str]`	`None`	ID of the workflow step
`step_name`	`Optional[str]`	`None`	Name of the workflow step
`step_index`	`Optional[int]`	`None`	Index of the workflow step
`nested_depth`	`int`	`0`	Nesting depth: 0 for top-level, incremented per nested workflow
`tools`	`Optional[List[ToolExecution]]`	`None`	Tool executions associated with the event
`created_at`	`int`	Current timestamp	Unix timestamp of event creation

Agent Configuration for Reasoning

Separate reasoning stage

Set reasoning_model to run a native reasoning stage before the main model produces the answer. You can provide reasoning_agent to customize that stage; the stage is activated by reasoning_model.

Parameter	Constructor type	Default	Description
`reasoning_model`	`Optional[Union[Model, str]]`	`None`	Native reasoning model used for the separate stage.
`reasoning_agent`	`Optional[Agent]`	`None`	Optional custom agent used by the reasoning stage.

The current Agent constructor does not accept reasoning, reasoning_min_steps, or reasoning_max_steps. For reasoning in the primary model's own response, configure that model's provider-specific reasoning settings instead. See the reasoning guide for complete setup and examples.

Display Parameters

Parameters for showing reasoning during execution. show_full_reasoning is passed to print_response(); stream_events is set on the Agent or passed to run().

Parameter	Type	Default	Description
`show_full_reasoning`	`bool`	`False`	Display complete reasoning process in output
`stream_events`	`Optional[bool]`	`None`	Stream intermediate events, including reasoning steps, in real-time

Reasoning Reference

ReasoningStep

Attributes

NextAction Enum

ReasoningSteps

Attributes

ReasoningTools

Constructor Parameters

Methods

think()

analyze()

Reasoning Events

Event Types

ReasoningStartedEvent

ReasoningStepEvent

ReasoningContentDeltaEvent

ReasoningCompletedEvent

Agent Configuration for Reasoning

Separate reasoning stage

Display Parameters

See Also

On this page