Reasoning Framework

The reasoning framework provides structured thinking strategies for complex tasks. An orchestrator classifies tasks and selects the appropriate strategy automatically.

Architecture

graph TD
    T[Task Input] --> O[Orchestrator]
    O --> CL[_classify_task]
    CL --> |math, analytical| CoT[Chain-of-Thought]
    CL --> |planning| ToT[Tree-of-Thought]
    CL --> |research| ReAct[ReAct]
    CL --> |creative, code| Ref[Reflection]

    CoT --> P[Provider]
    ToT --> P
    ReAct --> P
    Ref --> P
    ReAct --> TE[Tool Executor]

    P --> R[ReasoningResult]

    CoT -.-> |fallback| FB[Fallback Strategy]
    ToT -.-> |fallback| FB
    ReAct -.-> |fallback| FB
    Ref -.-> |fallback| FB

Strategies

Strategy	Class	Use Case	How It Works
Chain-of-Thought	`ChainOfThought`	Math, analytical, simple	Step-by-step reasoning with explicit intermediate steps
Tree-of-Thought	`TreeOfThought`	Planning, design	Explores multiple solution branches (BFS/DFS/beam search)
ReAct	`ReActAgent`	Research, tool-heavy tasks	Interleaves reasoning with tool actions (Reason-Act-Observe loop)
Reflection	`ReflectiveReasoner`	Creative, code	Generates, self-critiques, and revises through multiple rounds

Task Classification

The orchestrator classifies tasks by keyword matching in _classify_task():

Task Type	Keywords	Default Strategy
`math`	calculate, compute, solve, equation, formula	CoT
`code`	code, program, function, implement, debug	Reflection
`research`	search, find information, look up, research	ReAct
`planning`	plan, design, strategy, organize, roadmap	ToT
`creative`	write, create, compose, draft, story, poem	Reflection
`analytical`	analyze, compare, evaluate, assess, review	CoT
`simple`	what is, who is, when did, define, list	CoT
`unknown`	(no match)	CoT (fallback)

Strategy Configs

Chain-of-Thought (`CoTConfig`)

Field	Default	Description
`model`	`"llama3.2"`	Model to use
`mode`	`"zero_shot"`	`"zero_shot"` or `"few_shot"`
`examples`	`[]`	Few-shot examples (if `few_shot` mode)
`max_steps`	`10`	Maximum reasoning steps

Tree-of-Thought (`ToTConfig`)

Field	Default	Description
`model`	`"llama3.2"`	Model to use
`branching_factor`	`3`	Branches per node
`max_depth`	`3`	Maximum tree depth
`search_strategy`	`"bfs"`	`"bfs"`, `"dfs"`, or `"beam"`
`beam_width`	`2`	Beam width (if beam search)

ReAct (`ReActConfig`)

Field	Default	Description
`model`	`"llama3.2"`	Model to use
`tools`	`[]`	Available `Tool` objects
`max_iterations`	`10`	Max reason-act-observe cycles

Reflection (`ReflectionConfig`)

Field	Default	Description
`model`	`"llama3.2"`	Model to use
`max_revisions`	`3`	Maximum self-revision rounds
`critique_model`	`null`	Optional separate model for critique

Result Structure

ReasoningResult contains:

Field	Type	Description
`answer`	string	Final response
`strategy`	string	Strategy used
`status`	ReasoningStatus	`"complete"` or `"failed"`
`steps`	list[ThoughtStep]	Full reasoning trace
`total_steps`	int	Step count
`branches_explored`	int	ToT branches explored
`actions_taken`	int	ReAct actions executed
`revisions`	int	Reflection revision count
`total_tokens`	int	Token usage
`total_time_ms`	float	Elapsed time

Orchestrator Config

from agentx_ai.reasoning.orchestrator import ReasoningOrchestrator, OrchestratorConfig

config = OrchestratorConfig(
    default_model="llama3.2",
    fallback_strategy="cot",    # Fallback if primary fails
    enable_fallback=True,
)

orchestrator = ReasoningOrchestrator(config)
result = await orchestrator.reason("Plan a week-long trip to Japan")
# result.strategy == "tot" (auto-classified as planning)

The strategy map can be overridden in OrchestratorConfig.strategy_map to change which strategy handles each task type.

Integration

The Agent uses reasoning through Agent.run():

Agent receives a task
TaskPlanner decomposes into subtasks
For each subtask, ReasoningOrchestrator.reason() is called
Results are aggregated into the final AgentResult

In chat mode (Agent.chat(simple_mode=True)), reasoning is bypassed — the agent uses direct provider completion instead.

Agent Core — How reasoning fits into the agent pipeline
API: Agent Run — Endpoint with reasoning_strategy parameter
API Models: ReasoningResult — Result schema