DecisionNode

nae.DecisionNode

DecisionNode(name: Optional[str] = None, llm: Optional[Any] = None, node_prompt: str = '', choices: List[str] = [], tools: Optional[list] = None, input_field: str = 'messages', reads: Optional[List[str]] = None, cache_ttl: Optional[int] = None, retry: bool = False)

Bases: RouterNode, LLMNode

A node that makes decisions based on LLM output to direct graph flow.

DecisionNode uses a language model to choose between predefined options, determining the next node in the graph based on the choice made.

Tool use is two-phase so tools NEVER share a call with structured output: the base model is bound as a separate _tool_llm (used to gather context via the shared tool-call loop) and _route_llm is the structured-output model that returns the forced choice.

Wire it by indexing a choice — decision["positive"] > handler; a bare decision > x raises.

Examples:

from nae import AgentNode, DecisionNode, AgenticGraph

classify = DecisionNode(
    llm=llm,
    node_prompt="Classify the sentiment of the message.",
    choices=["positive", "negative"],
)
praise = AgentNode(llm=llm, node_prompt="Thank the happy customer.")
apologize = AgentNode(llm=llm, node_prompt="Apologize to the unhappy customer.")

classify["positive"] > praise
classify["negative"] > apologize

graph = AgenticGraph(start_node=classify, end_nodes={praise, apologize})

Initialize a DecisionNode.

Parameters:

Name	Type	Description	Default
name	Optional[str]	Unique identifier for the node	None
llm	Optional[Any]	Language model instance to be used by this node	None
node_prompt	str	System prompt/instructions for the language model	''
choices	List[str]	List of possible decision options	[]
tools	Optional[list]	Optional tools the node may call to gather context BEFORE routing. Same normalization as AgentNode. Tools run in a first phase (a tool-call loop on a tool-bound copy of the model); the gathered messages then feed the structured-output routing call. Tools and structured output never happen in one call.	None
input_field	str	State key to read the message history from.	'messages'
reads	Optional[List[str]]	State keys this node reads (multi-key form; back-compat generalization of input_field). Reads are dispatched by VALUE type just like AgentNode — message lists become history, scalars are interpolated into node_prompt. Use reads OR input_field.	None
cache_ttl	Optional[int]	see Node — node-level result caching.	None
retry	bool	see Node — node-level retry on exception.	False

Raises:

Type	Description
AssertionError	If node_prompt or choices is empty

__call__

__call__(state: dict) -> dict

Process the current state and make a decision.

Parameters:

Name	Type	Description	Default
state	dict	Current conversation state containing message history	required

Returns:

Type	Description
dict	A state delta: {f"decision_{name}": , "log": [...]}

Raises:

Type	Description
ValueError	If LLM is not set, if choice is invalid, or if choice has no connected node