Tree-of-Thoughts (ToT) execution strategy for Jido agents.
This strategy implements branching exploration by generating multiple candidate thoughts at each step, evaluating them, and expanding the most promising branches.
Overview
Tree-of-Thoughts extends Chain-of-Thought by:
- Generating multiple candidate thoughts at each step
- Evaluating each thought's potential
- Exploring promising branches while pruning poor ones
- Supporting different traversal strategies (BFS, DFS, best-first)
This approach is effective for problems requiring search, like:
- Puzzles and games
- Planning and scheduling
- Creative writing
- Complex reasoning tasks
Architecture
This strategy uses a pure state machine (Jido.AI.Reasoning.TreeOfThoughts.Machine) for
all state transitions. The strategy acts as a thin adapter that:
- Converts instructions to machine messages
- Converts machine directives to SDK-specific directive structs
- Manages the machine state within the agent
Configuration
Configure via strategy options when defining your agent:
use Jido.Agent,
name: "my_tot_agent",
strategy: {
Jido.AI.Reasoning.TreeOfThoughts.Strategy,
model: "anthropic:claude-sonnet-4-20250514",
branching_factor: 3,
max_depth: 4,
traversal_strategy: :best_first
}Options
:model(optional) - Model alias or direct model spec, defaults to :fast (resolved via Jido.AI.resolve_model/1):branching_factor,:max_depth,:traversal_strategy(optional) - Core tree search controls:top_k,:min_depth,:max_nodes,:max_duration_ms,:beam_width(optional) - Search budget and shaping controls:early_success_threshold,:convergence_window,:min_score_improvement,:max_parse_retries(optional) - Completion/parser controls:tools,:tool_context,:tool_timeout_ms,:tool_max_retries,:tool_retry_backoff_ms,:max_tool_round_trips(optional) - Tool execution controls:effect_policy,:agent_effect_policy,:strategy_effect_policy(optional) - Effect policy controls:generation_prompt(optional) - Custom prompt for thought generation:evaluation_prompt(optional) - Custom prompt for thought evaluation
Signal Routing
This strategy implements signal_routes/1 which AgentServer uses to
automatically route these signals to strategy commands:
"ai.tot.query"→:tot_start"ai.llm.response"→:tot_llm_result"ai.llm.delta"→:tot_llm_partial
State
State is stored under agent.state.__strategy__ with tree structure.
Summary
Functions
Returns the best scoring node in the tree.
Returns all nodes in the tree.
Returns the solution content (the result).
Returns the solution path (list of node IDs from root to solution).
Returns the action atom for handling streaming LLM partial tokens.
Returns the action atom for handling LLM results.
Returns the action atom for handling request rejection events.
Returns the action atom for starting a ToT exploration.
Returns the action atom for handling tool result events.
Types
@type config() :: %{ model: String.t(), branching_factor: pos_integer(), max_depth: pos_integer(), traversal_strategy: Jido.AI.Reasoning.TreeOfThoughts.Machine.traversal_strategy(), generation_prompt: String.t(), evaluation_prompt: String.t(), top_k: pos_integer(), min_depth: non_neg_integer(), max_nodes: pos_integer(), max_duration_ms: pos_integer() | nil, beam_width: pos_integer() | nil, early_success_threshold: float(), convergence_window: pos_integer(), min_score_improvement: float(), max_parse_retries: non_neg_integer(), tools: [module()], actions_by_name: %{required(String.t()) => module()}, reqllm_tools: [ReqLLM.Tool.t()], tool_context: map(), tool_timeout_ms: pos_integer(), tool_max_retries: non_neg_integer(), tool_retry_backoff_ms: non_neg_integer(), max_tool_round_trips: pos_integer(), effect_policy: map() }
Functions
@spec get_best_node(Jido.Agent.t()) :: Jido.AI.Reasoning.TreeOfThoughts.Machine.thought_node() | nil
Returns the best scoring node in the tree.
@spec get_nodes(Jido.Agent.t()) :: %{ required(String.t()) => Jido.AI.Reasoning.TreeOfThoughts.Machine.thought_node() }
Returns all nodes in the tree.
@spec get_result(Jido.Agent.t()) :: map() | nil
Returns the solution content (the result).
@spec get_solution_path(Jido.Agent.t()) :: [String.t()]
Returns the solution path (list of node IDs from root to solution).
@spec llm_partial_action() :: :tot_llm_partial
Returns the action atom for handling streaming LLM partial tokens.
@spec llm_result_action() :: :tot_llm_result
Returns the action atom for handling LLM results.
@spec request_error_action() :: :tot_request_error
Returns the action atom for handling request rejection events.
@spec start_action() :: :tot_start
Returns the action atom for starting a ToT exploration.
@spec tool_result_action() :: :tot_tool_result
Returns the action atom for handling tool result events.