Agent Nodes

Generic agent interaction available for every agent: fetch an agent instance, call agent functions (optionally conditionally), and read or count agent state variables.

9 nodes.

Node	Registry path
Call Agent Function	`agents/CallAgentFunction`
Call Agent Function (Conditional)	`agents/CallAgentFunctionConditional`
Counter Agent State	`agents/CounterAgentState`
Dynamic Instruction	`agents/DynamicInstruction`
Get Agent	`agents/GetAgent`
Get Agent State	`agents/GetAgentState`
Set Agent State	`agents/SetAgentState`
Toggle Agent Action	`agents/ToggleAgentAction`
Unset Agent State	`agents/UnsetAgentState`

Call Agent Function

agents/CallAgentFunction

Call a function on an agent and return its result.

The agent can be given as an agent instance or by name. The function is looked up on the agent by name and called with the given arguments as keyword arguments (coroutine functions are awaited).

Inputs

Input	Type	Description
`agent`	`str,agent`	The agent (instance or name) to call the function on
`function_name`	`str`	The name of the function to call on the agent
`arguments`	`dict`	Dict of keyword arguments to pass to the function

Outputs

Output	Type	Description
`result`	`any`	The return value of the function call

Properties

Property	Type	Default	Description
`agent`	`str`	`""`	The agent to call the function on. Choices are generated at runtime.
`function_name`	`str`	`""`	The name of the function to call on the agent
`arguments`	`dict`	`{}`	The arguments to pass to the function

Call Agent Function (Conditional)

agents/CallAgentFunctionConditional

Call a function on an agent and return its result.

Provides a required state input causing the node to only run when a state is provided

Inputs

Input	Type	Description
`state`	`any`	The graph state
`agent`	`str,agent`	The agent (instance or name) to call the function on
`function_name`	`str`	The name of the function to call on the agent
`arguments`	`dict`	Dict of keyword arguments to pass to the function

Outputs

Output	Type	Description
`state`	`any`	The state input, passed through
`result`	`any`	The return value of the function call

Properties

Property	Type	Default	Description
`agent`	`str`	`""`	The agent to call the function on. Choices are generated at runtime.
`function_name`	`str`	`""`	The name of the function to call on the agent
`arguments`	`dict`	`{}`	The arguments to pass to the function

Counter Agent State

agents/CounterAgentState

Increment a numeric variable in an agent's state and return the new value.

Provides a required state input causing the node to only run when a state is provided

Inputs

Input	Type	Description
`state`	`any`	The graph state
`name`	`str`	(optional) The name of the counter variable
`reset`	`bool`	If true, the value will be reset to 0 (optional)
`reset_cap`	`number`	If set, the counter resets to 0 once it reaches this value (optional)
`agent`	`str,agent`	The agent (instance or name) whose state holds the counter

Outputs

Output	Type	Description
`state`	`any`	The state input, passed through
`name`	`str`	The name that was used
`value`	`any`	The new value
`scope`	`str`	The scope that was used
`reset_cap`	`number`	The reset cap that was used
`reset`	`bool`	Whether the counter was reset
`new_cycle`	`bool`	True if the counter was at 0 before this run

Properties

Property	Type	Default	Description
`name`	`str`	`unset`	The name of the variable to manipulate
`scope`	`str`	`"local"`	Which scope to manipulate. Choices: `scene`, `context`.
`increment`	`int`	`1`	increment
`reset`	`bool`	`False`	reset
`reset_cap`	`int`	`0`	reset_cap
`agent`	`str`	`unset`	The agent to manipulate the state on. Choices are generated at runtime.

Dynamic Instruction

agents/DynamicInstruction

Create a dynamic instruction object to use for instruction injection in event handlers.

A header is required at runtime (raises an error if missing). List content is joined with newlines.

Inputs

Input	Type	Description
`header`	`str`	(optional) The header (title) of the dynamic instruction
`content`	`str,list`	(optional) The content of the dynamic instruction (string or list of strings)

Outputs

Output	Type	Description
`dynamic_instruction`	`dynamic_instruction`	The dynamic instruction object

Properties

Property	Type	Default	Description
`header`	`str`	`unset`	The header of the dynamic instruction
`content`	`text`	`unset`	The content of the dynamic instruction

Get Agent

agents/GetAgent

Get an agent instance by name.

Does nothing if no agent name is set; raises an error if the agent cannot be found.

Outputs

Output	Type	Description
`agent`	`agent`	The agent instance

Properties

Property	Type	Default	Description
`agent_name`	`str`	`""`	The name of the agent to get. Choices are generated at runtime.

Get Agent State

agents/GetAgentState

Get a variable from an agent's state.

The scene scope reads agent state stored with the scene, the context scope reads the agent's context state.

Inputs

Input	Type	Description
`name`	`str`	(optional) the name of the variable to get
`default`	`any`	value to return if the variable is not set (optional)
`agent`	`str,agent`	the agent (instance or name) to read the state from

Outputs

Output	Type	Description
`name`	`str`	the name that was retrieved
`value`	`any`	the value that was retrieved
`scope`	`str`	the scope that was retrieved

Properties

Property	Type	Default	Description
`name`	`str`	`unset`	The name of the variable to manipulate
`scope`	`str`	`"local"`	Which scope to manipulate. Choices: `scene`, `context`.
`agent`	`str`	`unset`	The agent to manipulate the state on. Choices are generated at runtime.

Set Agent State

agents/SetAgentState

Set a variable in an agent's state.

The scene scope writes agent state stored with the scene, the context scope writes to the agent's context state.

Provides a required state input causing the node to only run when a state is provided

Inputs

Input	Type	Description
`state`	`any`	The graph state
`name`	`str`	(optional) the name of the variable to set
`value`	`any`	the value to set
`agent`	`str,agent`	the agent (instance or name) to set the state on

Outputs

Output	Type	Description
`state`	`any`	The state input, passed through
`name`	`str`	the name that was set
`value`	`any`	the value that was set
`scope`	`str`	the scope that was used

Properties

Property	Type	Default	Description
`name`	`str`	`unset`	The name of the variable to manipulate
`scope`	`str`	`"local"`	Which scope to manipulate. Choices: `scene`, `context`.
`agent`	`str`	`unset`	The agent to manipulate the state on. Choices are generated at runtime.

Toggle Agent Action

agents/ToggleAgentAction

Allows disabling or enabling an agent action that can be disabled

Raises an error if the agent or the action cannot be found, or if the action is one that cannot be disabled — those are always enabled and are not togglable from a graph.

Inputs

Input	Type	Description
`state`	`any`	The graph state
`agent`	`str,agent`	(optional) The agent (instance or name) to toggle the action on
`action_name`	`str`	(optional) The name of the action to toggle
`enabled`	`bool`	(optional) Whether to enable or disable the action

Outputs

Output	Type	Description
`state`	`any`	The state input, passed through
`agent`	`agent`	The resolved agent instance
`action_name`	`str`	The action name, passed through
`enabled`	`bool`	The action's effective enabled state after the write — when a scene override is active it takes the write, so this reflects the override rather than the agent's global setting

Properties

Property	Type	Default	Description
`agent`	`str`	`""`	The agent to toggle the action on. Choices are generated at runtime.
`action_name`	`str`	`""`	The name of the action to toggle
`enabled`	`bool`	`True`	Whether to enable or disable the action

Unset Agent State

agents/UnsetAgentState

Unset a variable in an agent's state.

The scene scope removes agent state stored with the scene, the context scope removes from the agent's context state.

Provides a required state input causing the node to only run when a state is provided

Inputs

Input	Type	Description
`state`	`any`	The graph state
`name`	`str`	(optional) the name of the variable to unset
`agent`	`str,agent`	the agent (instance or name) to unset the state on

Outputs

Output	Type	Description
`state`	`any`	The state input, passed through
`name`	`str`	the name that was unset
`value`	`any`	the value that was unset
`scope`	`str`	the scope that was used

Properties

Property	Type	Default	Description
`name`	`str`	`unset`	The name of the variable to manipulate
`scope`	`str`	`"local"`	Which scope to manipulate. Choices: `scene`, `context`.
`agent`	`str`	`unset`	The agent to manipulate the state on. Choices are generated at runtime.