f07b68fb3e
* fix: honor can_be_disabled and declared defaults when loading agent action enabled flags (#174) * fix: surface refused agent action toggles, enforce enabled/can_be_disabled at the model, correct changelog claims (#174) * fix: correct ToggleAgentAction docs wording and error message, restore test class placement (#174)
11 KiB
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. |