Griptape Nodes Scripting
"Retained Mode" is a Python scripting interface to interact with Griptape Nodes. These methods allow users to create, modify, and manage nodes, parameters, connections, and flows through a simplified Python API.
Note: The actual import command for RetainedMode is:
from griptape_nodes.retained_mode import RetainedMode as cmdHowever, for convenience, in the script editor of the GUI, this import is already done for you automatically, so you can freely use
cmd.directly.
Flow Operations
create_flow
Creates a new flow within the Griptape system.
cmd.create_flow(flow_name=None, parent_flow_name=None)
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | ⚪ |
| parent_flow_name | string | ⚪ |
Return Value
ResultPayload object with flow creation status
Description
Creates a new flow with the specified name. If parent_flow_name is provided, the new flow will be created as a child of the specified parent flow.
delete_flow
cmd.delete_flow(flow_name)
Deletes an existing flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with flow deletion status
Description
Removes the specified flow from the system.
get_flows
cmd.get_flows(parent_flow_name=None)
Lists all flows within a parent flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| parent_flow_name | string | ⚪ |
Return Value
ResultPayload object containing a list of flows
Description
Returns all flows within the specified parent flow. If no parent_flow_name is provided, returns all top-level flows.
get_nodes_in_flow
cmd.get_nodes_in_flow(flow_name)
Lists all nodes within a flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object containing a list of node names
Description
Returns all nodes within the specified flow.
run_flow
cmd.run_flow(flow_name)
Executes a flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with flow execution status
Description
Starts the execution of the specified flow.
reset_flow
cmd.reset_flow(flow_name)
Resets a flow to its initial state.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with flow reset status
Description
Unresolves all nodes in the flow, returning it to its initial state.
get_flow_state
cmd.get_flow_state(flow_name)
Returns the current state of a flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object containing flow state information
Description
Gets the current execution state of the specified flow.
cancel_flow
cmd.cancel_flow(flow_name)
Cancels the execution of a flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with flow cancellation status
Description
Stops the execution of the specified flow.
single_step
cmd.single_step(flow_name)
Executes a single node step in a flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with step execution status
Description
Executes a single node in the specified flow.
single_execution_step
cmd.single_execution_step(flow_name)
Executes a single execution step in a flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with execution step status
Description
Executes a single execution step in the specified flow.
continue_flow
cmd.continue_flow(flow_name)
Continues the execution of a paused flow.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| flow_name | string | 🟢 |
Return Value
ResultPayload object with flow continuation status
Description
Continues the execution of a flow that was previously paused.
Node Operations
create_node
cmd.create_node(node_type, specific_library_name=None, node_name=None, parent_flow_name=None, metadata=None)
Creates a new node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_type | string | 🟢 |
| specific_library_name | string | ⚪ |
| node_name | string | ⚪ |
| parent_flow_name | string | ⚪ |
| metadata | dict | ⚪ |
Return Value
Node name or ResultPayload object with node creation status
Description
Creates a new node of the specified type. Optional parameters allow specifying the library, node name, parent flow, and metadata.
delete_node
cmd.delete_node(node_name)
Deletes an existing node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
Return Value
ResultPayload object with node deletion status
Description
Removes the specified node from the system.
run_node
cmd.run_node(node_name)
Executes a single node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
Return Value
ResultPayload object with node execution status
Description
Resolves and executes the specified node.
get_resolution_state_for_node
cmd.get_resolution_state_for_node(node_name)
Returns the resolution state of a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
Return Value
ResultPayload object containing node resolution state
Description
Gets the current resolution state of the specified node.
get_metadata_for_node
cmd.get_metadata_for_node(node_name)
Returns the metadata for a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
Return Value
ResultPayload object containing node metadata
Description
Gets the metadata associated with the specified node.
set_metadata_for_node
cmd.set_metadata_for_node(node_name, metadata)
Sets the metadata for a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
| metadata | dict | 🟢 |
Return Value
ResultPayload object with metadata update status
Description
Sets the metadata for the specified node.
exists
cmd.exists(node)
Checks if a node exists.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node | string | 🟢 |
Return Value
Boolean indicating whether the node exists
Description
Returns True if the specified node exists, False otherwise.
ls
cmd.ls(**kwargs)
Lists objects in the system.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| **kwargs | dict | ⚪ |
Return Value
List of object names matching the filter criteria
Description
Lists objects in the system, optionally filtered by the provided criteria.
Parameter Operations
list_params
cmd.list_params(node)
Lists all parameters on a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node | string | 🟢 |
Return Value
List of parameter names
Description
Returns a list of all parameters on the specified node.
add_param
cmd.add_param(node_name, parameter_name, default_value, tooltip, type=None, input_types=None, output_type=None, edit=False, tooltip_as_input=None, tooltip_as_property=None, tooltip_as_output=None, ui_options=None, mode_allowed_input=True, mode_allowed_property=True, mode_allowed_output=True, **kwargs)
Adds a parameter to a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
| parameter_name | string | 🟢 |
| default_value | any | 🟢 |
| tooltip | string or list | 🟢 |
| type | string | ⚪ |
| input_types | list of strings | ⚪ |
| output_type | string | ⚪ |
| edit | boolean | ⚪ |
| tooltip_as_input | string or list | ⚪ |
| tooltip_as_property | string or list | ⚪ |
| tooltip_as_output | string or list | ⚪ |
| ui_options | ParameterUIOptions | ⚪ |
| mode_allowed_input | boolean | ⚪ |
| mode_allowed_property | boolean | ⚪ |
| mode_allowed_output | boolean | ⚪ |
Return Value
ResultPayload object with parameter addition status
Description
Adds a parameter to the specified node with the given configuration. If edit=True, modifies an existing parameter instead.
del_param
cmd.del_param(node_name, parameter_name)
Removes a parameter from a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
| parameter_name | string | 🟢 |
Return Value
ResultPayload object with parameter removal status
Description
Removes the specified parameter from the node.
param_info
cmd.param_info(node, param) or cmd.param_info("node.param")
Gets information about a parameter.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node | string | 🟢 |
| param | string | 🟢 |
Return Value
ResultPayload object containing parameter details
Description
Returns detailed information about the specified parameter. Accepts either separate node and param arguments or a single "node.param" string.
get_value
cmd.get_value(node, param) or cmd.get_value("node.param")
Gets the value of a parameter.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node | string | 🟢 |
| param | string | 🟢 |
Return Value
The value of the parameter or a failure result
Description
Returns the current value of the specified parameter. Supports indexed access for container types (e.g., "node.param[0]").
set_value
cmd.set_value(node, param, value) or cmd.set_value("node.param", value)
Sets the value of a parameter.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node | string | 🟢 |
| param | string | 🟢 |
| value | any | 🟢 |
Return Value
ResultPayload object with value update status
Description
Sets the value of the specified parameter. Supports indexed access for container types (e.g., "node.param[0]").
Connection Operations
connect
cmd.connect(source, destination)
Creates a connection between two parameters.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| source | string | 🟢 |
| destination | string | 🟢 |
Return Value
ResultPayload object with connection creation status
Description
Creates a connection from the source parameter to the destination parameter. Both arguments should be in the format "node.param".
exec_chain
cmd.exec_chain(*node_names)
Creates execution connections between a sequence of nodes.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| *node_names | string(s) | 🟢 |
Return Value
Dictionary with results of each connection attempt
Description
Creates exec_out -> exec_in connections between a sequence of nodes, effectively chaining them for execution in sequence.
delete_connection
cmd.delete_connection(source_node_name, source_param_name, target_node_name, target_param_name)
Deletes a connection between parameters.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| source_node_name | string | 🟢 |
| source_param_name | string | 🟢 |
| target_node_name | string | 🟢 |
| target_param_name | string | 🟢 |
Return Value
ResultPayload object with connection deletion status
Description
Removes the connection between the specified source and target parameters.
get_connections_for_node
cmd.get_connections_for_node(node_name)
Lists all connections for a node.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| node_name | string | 🟢 |
Return Value
ResultPayload object containing connection information
Description
Returns all connections involving the specified node, both incoming and outgoing.
Library Operations
get_available_libraries
cmd.get_available_libraries()
Lists all available node libraries.
Arguments
None
Return Value
ResultPayload object containing a list of library names
Description
Returns all registered node libraries in the system.
get_node_types_in_library
cmd.get_node_types_in_library(library_name)
Lists all node types in a library.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| library_name | string | 🟢 |
Return Value
ResultPayload object containing a list of node type names
Description
Returns all node types available in the specified library.
get_node_metadata_from_library
cmd.get_node_metadata_from_library(library_name, node_type_name)
Gets metadata for a node type.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| library_name | string | 🟢 |
| node_type_name | string | 🟢 |
Return Value
ResultPayload object containing node type metadata
Description
Returns the metadata for the specified node type in the given library.
Config Operations
get_config_value
cmd.get_config_value(category_and_key)
Gets a configuration value.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| category_and_key | string | 🟢 |
Return Value
ResultPayload object containing the configuration value
Description
Returns the value for the specified configuration key.
set_config_value
cmd.set_config_value(category_and_key, value)
Sets a configuration value.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| category_and_key | string | 🟢 |
| value | any | 🟢 |
Return Value
ResultPayload object with configuration update status
Description
Sets the value for the specified configuration key.
get_config_category
cmd.get_config_category(category=None)
Gets all configuration values in a category.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| category | string | ⚪ |
Return Value
ResultPayload object containing category configuration values
Description
Returns all configuration values in the specified category. If no category is provided, returns all configuration values.
set_config_category
cmd.set_config_category(category=None, contents={})
Sets configuration values for a category.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| category | string | ⚪ |
| contents | dict | ⚪ |
Return Value
ResultPayload object with category configuration update status
Description
Sets all configuration values for the specified category with the provided contents.
Utility Operations
run_arbitrary_python
cmd.run_arbitrary_python(python_str)
Executes arbitrary Python code.
Arguments
| Name | Argument Type | Required |
|---|---|---|
| python_str | string | 🟢 |
Return Value
ResultPayload object with execution status and results
Description
Executes the provided Python code string in the Griptape environment.
Examples
Creating a Flow and Nodes
# Create a new flow
flow = cmd.create_flow(flow_name="MyFlow")
# Create two nodes in the flow
node1 = cmd.create_node(node_type="CreateText", node_name="MyText", parent_flow_name="MyFlow")
node2 = cmd.create_node(node_type="RunAgent", node_name="MyAgent", parent_flow_name="MyFlow")
Setting Parameter Values and Creating Connections
# Set a parameter value
cmd.set_value("MyText.text", "This is a sample text to summarize.")
# Connect two nodes
cmd.connect("MyText.text", "MyAgent.prompt")
Running a Flow
# Run the flow
cmd.run_flow("MyFlow")
# Get the result
summary = cmd.get_value("MyAgent.output")
print(summary) # <whatever that summary would be!>
Working with Parameters
# Add a new parameter to a node
cmd.add_param(
node_name="MyAgent",
parameter_name="sunglasses",
default_value=100,
tooltip="The coolness of sunglasses",
type=["int"]
)
# Set the value of the new parameter
cmd.set_value("MyAgent.sunglasses", 50)
# Change the parameter
cmd.add_param(
node_name="MyAgent",
parameter_name="sunglasses",
tooltip="The coolness of sunglasses if halved",
edit=1
)
Listing and Querying
# List all nodes in a flow
nodes = cmd.get_nodes_in_flow("MyFlow")
print(nodes) # ["MyText","MyAgent"]
# List all parameters on a node
params = cmd.list_params("MyAgent")
print(params) # ["agent", "prompt_driver", "tools", "rulesets", "prompt", "prompt_context", "output"]
# Check if a node exists
if cmd.exists("MyText"):
print("MyText node exists") # True