Griptape Nodes 保留模式脚本编程 (Retained Mode Scripting)

“保留模式 (Retained Mode)”为与 Griptape Nodes 进行程序化底层交互提供了一套强大的 Python 脚本控制接口。它允许开发者通过简洁明了的 Python API，全自动创建、修改并管理工作流 (Flow)、算子节点 (Node)、输入输出属性参数 (Parameters) 以及连线拓扑 (Connections)。

开发提示： RetainedMode 的底层标准导入语句为：
from griptape_nodes.retained_mode import RetainedMode as cmd
为提升交互式脚本编写体验，在图形界面的 Script Editor (脚本编辑器) 中，该导入语句已由系统全自动执行挂载，因此你可以直接自由调用 cmd. 命名空间下的所有函数。

脚本编写与执行方式 (Working with Scripts)

主要有两种开发与执行脚本的途径：

直接使用内置脚本编辑器 (Script Editor)：在 Griptape Nodes 的脚本编辑器中即时编写 Python 代码并立即点击运行，直接程序化动态重构或驱动当前的画布工作流；
导入外部模块化脚本 (External Scripts)：将可复用的脚本逻辑封装保存在外部独立的 .py 文件中，在图形脚本编辑器中通过标准的 Python import 机制导入并调用其封装的功能。

内置的脚本编辑器是执行所有自动化脚本操作的核心主要入口。

脚本编程极其适用于自动化批处理繁琐任务：完整复制节点及其所有属性与连线网络、跨工作流导出与批量导入节点参数、以代码形式程序化搭建包含预设拓扑的完整大型工作流，或在循环结构中对数十个节点执行批量参数覆写。你还可以将 Retained Mode 与其他 Python 科学计算库（如 pandas、numpy、requests 等）深度混编，无限拓宽自动化脚本的工业级能力边界。

以下为 Retained Mode 的完整 API 核心技术参考手册：涵盖工作流流控、节点生命周期、参数管控、拓扑连线以及工作流执行等全维度操作。

工作流全局操作 (Flow Operations)

create_flow

在 Griptape 运行时中创建一个全新的工作流。

cmd.create_flow(flow_name=None, parent_flow_name=None)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	⚪ 选填	新建工作流的具名标识；留空则系统自动分配唯一名称
`parent_flow_name`	`string`	⚪ 选填	父级工作流名称；若传入，新建工作流将作为子流嵌套创建

返回值

包含工作流创建执行状态的 ResultPayload 结果对象。

delete_flow

彻底销毁并删除一个既有的工作流。

cmd.delete_flow(flow_name)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	目标删除的工作流名称

返回值

包含工作流删除状态的 ResultPayload 结果对象。

get_flows

列出指定父流下的所有子工作流；未指定则返回所有顶层工作流。

cmd.get_flows(parent_flow_name=None)

参数规范

参数名称	数据类型	是否必填	说明
`parent_flow_name`	`string`	⚪ 选填	父级工作流名称；留空则检索所有顶层顶级工作流

返回值

包含工作流名称列表的 ResultPayload 结果对象。

get_nodes_in_flow

检索并枚举指定工作流中的所有算子节点，可选支持按 Python 类名进行类型过滤。

cmd.get_nodes_in_flow(flow_name, node_types=None)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	目标检索的工作流名称
`node_types`	`list[string]` \| `None`	🔴 选填	允许过滤的算子 Python 类名列表（例如 `["StartFlow", "Agent"]`）；传 `None` 或省略则返回全部节点

返回值

包含匹配节点名称列表的 ResultPayload 结果对象。

run_flow

启动并执行指定的工作流。

cmd.run_flow(flow_name)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	目标执行的工作流名称

返回值

包含工作流启动执行状态的 ResultPayload 结果对象。

reset_flow

重置工作流至出厂未计算初始状态。

cmd.reset_flow(flow_name)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	目标重置的工作流名称

返回值

包含工作流重置状态的 ResultPayload 对象。会将流内所有节点标记为未解析 (Unresolved)。

get_flow_state

获取指定工作流的当前运行时状态。

cmd.get_flow_state(flow_name)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	目标查询的工作流名称

返回值

包含工作流运行时执行状态（就绪、运行中、暂停、完成、报错）的 ResultPayload 对象。

cancel_flow

强制中止并取消正在运行中的工作流。

cmd.cancel_flow(flow_name)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	准备取消的工作流名称

single_step

在工作流中向前单步步进执行单个节点。

cmd.single_step(flow_name)

参数规范

参数名称	数据类型	是否必填	说明
`flow_name`	`string`	🟢 必填	目标工作流名称

single_execution_step

在工作流中执行单一控制流执行步长。

cmd.single_execution_step(flow_name)

continue_flow

恢复已处于暂停 (Paused) 状态的工作流继续执行。

cmd.continue_flow(flow_name)

节点生命周期操作 (Node Operations)

create_node

在指定工作流中实例化并创建一个全新的算子节点。

cmd.create_node(node_type, specific_library_name=None, node_name=None, parent_flow_name=None, metadata=None)

参数规范

参数名称	数据类型	是否必填	说明
`node_type`	`string`	🟢 必填	算子类型名称（例如 `RunAgent`、`CreateText`）
`specific_library_name`	`string`	⚪ 选填	显式指定所属算子库名称，解决同名算子命名冲突
`node_name`	`string`	⚪ 选填	赋予该节点的专属具名标识；留空则系统自动分配唯一名称
`parent_flow_name`	`string`	⚪ 选填	承载该节点的所属父工作流名称
`metadata`	`dict`	⚪ 选填	附加给节点的初始元数据字典（坐标位置、UI 颜色等）

返回值

返回新创建节点的实际名称，或包含创建状态的 ResultPayload 对象。

delete_node

从当前拓扑中删除指定节点。

cmd.delete_node(node_name)

run_node

单独解析并单体触发执行特定的某一个节点。

cmd.run_node(node_name)

get_resolution_state_for_node

查询特定节点的解析与计算状态（如 RESOLVED、UNRESOLVED、RUNNING 等）。

cmd.get_resolution_state_for_node(node_name)

get_metadata_for_node

读取指定节点关联的所有元数据字典信息。

cmd.get_metadata_for_node(node_name)

set_metadata_for_node

为指定节点覆写设置自定义元数据字典。

cmd.set_metadata_for_node(node_name, metadata)

exists

检测指定的节点在当前引擎环境中是否存在。

cmd.exists(node)

返回值

布尔值 True（存在）或 False（不存在）。

ls

列出系统当前内存中的所有对象，支持条件过滤。

cmd.ls(**kwargs)

属性参数操作 (Parameter Operations)

list_params

列出指定节点表面暴露的所有输入、输出及内部属性参数名称。

cmd.list_params(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,
)

参数规范

参数名称	数据类型	是否必填	说明
`node_name`	`string`	🟢 必填	目标宿主节点名称
`parameter_name`	`string`	🟢 必填	新增参数的唯一标识键名
`default_value`	`any`	🟢 必填	参数出厂默认初始值
`tooltip`	`string` \| `list`	🟢 必填	在前端悬停渲染的提示说明文本
`type`	`string`	⚪ 选填	强类型数据类型定义
`input_types`	`list[string]`	⚪ 选填	作为输入端口时允许接收的上游类型列表
`output_type`	`string`	⚪ 选填	作为输出端口时对外广播的数据类型
`edit`	`boolean`	⚪ 选填	若设为 `True`，则用于就地修改已有参数的定义而非新增
`ui_options`	`ParameterUIOptions`	⚪ 选填	前端专属控件外观配置（滑动条极值、多行文本等）

del_param

从指定节点上移除并注销某个参数。

cmd.del_param(node_name, parameter_name)

param_info

获取某个参数的完整数据类型、连线限制与元数据定义。

cmd.param_info(node, param)  # 或 cmd.param_info("node.param")

get_value

读取参数的当前运行时数值，支持容器索引语法。

cmd.get_value(node, param)  # 或 cmd.get_value("node.param")

提示：针对列表或字典容器类型，支持传递索引语法，例如 cmd.get_value("MyNode.my_list[0]")。

set_value

覆写指定参数的数值，同样支持下标索引写入。

cmd.set_value(node, param, value)  # 或 cmd.set_value("node.param", value)

拓扑连线操作 (Connection Operations)

connect

在两个参数端口之间建立物理数据连线。

cmd.connect(source, destination)

语法规则

源端口与目标端口均采用 "node.param" 具名字符串格式，例如：

cmd.connect("MyTextNode.text", "MyAgentNode.prompt")

exec_chain

对一系列算子节点按序建立控制流链（exec_out -> exec_in）。

cmd.exec_chain(*node_names)

典型用法

一行代码快速串联多个节点的执行次序：

cmd.exec_chain("StartNode", "ProcessNodeA", "ProcessNodeB", "EndNode")

delete_connection

断开并删除两个参数端口之间既有的连线。

cmd.delete_connection(source_node_name, source_param_name, target_node_name, target_param_name)

get_connections_for_node

枚举指定节点涉及的所有物理连线拓扑（包含输入连线与输出连线）。

cmd.get_connections_for_node(node_name)

算子库与全局配置 (Library & Config Operations)

get_available_libraries

返回系统中当前已加载注册的所有算子库名称列表。

cmd.get_available_libraries()

get_node_types_in_library

列出特定算子库中包含的所有算子类型类名列表。

cmd.get_node_types_in_library(library_name)

get_config_value / set_config_value

读取或动态覆写引擎全局配置项：

cmd.get_config_value("category.key")
cmd.set_config_value("category.key", new_value)

原生 Python 执行逃生舱 (run_arbitrary_python)

在 Griptape 宿主环境中执行任意原生 Python 代码字符串：

cmd.run_arbitrary_python("import os; print(os.getcwd())")

综合实战代码范例 (Examples)

1. 自动化全流程构建与节点组装

# 1. 创建全新的工作流
flow = cmd.create_flow(flow_name="AutoSummarizeFlow")

# 2. 在工作流中程序化实例化两个算子节点
node1 = cmd.create_node(node_type="CreateText", node_name="SourceText", parent_flow_name="AutoSummarizeFlow")
node2 = cmd.create_node(node_type="RunAgent", node_name="SummarizerAgent", parent_flow_name="AutoSummarizeFlow")

# 3. 为源文本节点填入素材内容
cmd.set_value("SourceText.text", "Griptape Nodes Retained Mode 允许开发者通过 Python API 全自动编排大型复杂拓扑。")

# 4. 将源节点的文本输出端连入智能体的 Prompt 提示词端口
cmd.connect("SourceText.text", "SummarizerAgent.prompt")

# 5. 触发执行整条工作流
cmd.run_flow("AutoSummarizeFlow")

# 6. 读取并打印下游智能体生成的最终摘要
summary_result = cmd.get_value("SummarizerAgent.output")
print(f"生成的最终摘要成片为：\n{summary_result}")

2. 动态拓扑巡检与条件探测

# 列出工作流中的所有活跃节点
nodes = cmd.get_nodes_in_flow("AutoSummarizeFlow")
print(f"当前流内节点清单: {nodes}")

# 探测特定节点是否存在并查看其暴露的端口
if cmd.exists("SummarizerAgent"):
    params = cmd.list_params("SummarizerAgent")
    print(f"智能体暴露的所有参数端口: {params}")