Griptape Nodes リテインモードスクリプティング (Retained Mode Scripting)

「リテインモード (Retained Mode)」は、Griptape Nodes と対話するための Python スクリプトインターフェースを提供します。これにより、シンプルな Python API を通じて、ノード、パラメータ、接続、フローの作成、変更、管理をプログラムから行うことができます。

注意: RetainedMode の実際のインポートコマンドは以下の通りです：
from griptape_nodes.retained_mode import RetainedMode as cmd
ただし、利便性のため、GUI のスクリプトエディタ内ではこのインポートがあらかじめ自動的に行われているため、直接 cmd. を自由に使用できます。

スクリプトの操作方法 (Working with Scripts)

スクリプトを開発および実行する主な方法は 2 つあります：

スクリプトエディタの利用 (Using the Script Editor) - Griptape Nodes のスクリプトエディタ内で直接スクリプトを記述し、即座に実行してフローを変更・制御します。
外部スクリプトのインポート (Importing External Scripts) - 再利用可能なスクリプトモジュールを外部ファイルとして保持し、スクリプトエディタ内で Python の標準インポート機能を使って読み込み、そこから機能を実行します。

スクリプトエディタは、すべてのスクリプト操作の主要なエントリーポイントです。

スクリプトは反復的な作業の自動化に非常に役立ちます：プロパティや接続を維持したままのノードの複製、ノードの値のエクスポートと別フローへのインポート、事前定義されたノードと接続を持つ完全なフローのプログラムによる構築、ループ処理による多数のノードに対する一括操作など。また、Retained Mode を他の Python ライブラリ（pandas、numpy、requests など）と組み合わせることで、スクリプトの処理能力をさらに拡張できます。

以降の内容は API リファレンスです：フロー管理、ノード操作、パラメータ管理、接続、フロー実行について解説します。

フロー操作 (Flow Operations)

create_flow

Griptape システム内に新しいフローを作成します。

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

引数

名前	引数の型	必須
flow_name	string	⚪
parent_flow_name	string	⚪

戻り値

フローの作成ステータスを含む ResultPayload オブジェクト

説明

指定した名前で新しいフローを作成します。parent_flow_name が指定された場合、新しいフローは指定された親フローの子フローとして作成されます。

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 オブジェクト

説明

指定した親フロー内のすべてのフローを返します。parent_flow_name が指定されていない場合は、すべてのトップレベルフローを返します。

get_nodes_in_flow

cmd.get_nodes_in_flow(flow_name, node_types=None)

フロー内のすべてのノードを一覧表示します。Python クラス名によるフィルタリングも可能です。

引数

名前	引数の型	必須
flow_name	string	🟢
node_types	list[string] \| None	🔴

戻り値

ノード名のリストを含む ResultPayload オブジェクト

説明

指定したフロー内のすべてのノードを返します。node_types を指定した場合、Python クラス名がいずれかのエントリに一致するノードのみが返されます（例: ["StartFlow", "Agent"]）。すべてのノードを取得する場合は、node_types を省略するか None を渡してください。

run_flow

cmd.run_flow(flow_name)

フローを実行します。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

フローの実行ステータスを含む ResultPayload オブジェクト

説明

指定したフローの実行を開始します。

reset_flow

cmd.reset_flow(flow_name)

フローを初期状態にリセットします。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

フローのリセットステータスを含む ResultPayload オブジェクト

説明

フロー内のすべてのノードの解決状態を解除（Unresolve）し、初期状態に戻します。

get_flow_state

cmd.get_flow_state(flow_name)

フローの現在の状態を返します。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

フローの状態情報を含む ResultPayload オブジェクト

説明

指定したフローの現在の実行状態を取得します。

cancel_flow

cmd.cancel_flow(flow_name)

フローの実行をキャンセル（中断）します。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

フローのキャンセルステータスを含む ResultPayload オブジェクト

説明

指定したフローの実行を停止します。

single_step

cmd.single_step(flow_name)

フロー内の単一ノードステップを実行します。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

ステップ実行ステータスを含む ResultPayload オブジェクト

説明

指定したフロー内の単一ノードを実行します。

single_execution_step

cmd.single_execution_step(flow_name)

フロー内の単一実行ステップを実行します。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

実行ステップステータスを含む ResultPayload オブジェクト

説明

指定したフロー内の単一の実行ステップを実行します。

continue_flow

cmd.continue_flow(flow_name)

一時停止されたフローの実行を再開します。

引数

名前	引数の型	必須
flow_name	string	🟢

戻り値

フローの再開ステータスを含む ResultPayload オブジェクト

説明

以前に一時停止されたフローの実行を再開します。

ノード操作 (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	🟢
specific_library_name	string	⚪
node_name	string	⚪
parent_flow_name	string	⚪
metadata	dict	⚪

戻り値

ノード名、またはノード作成ステータスを含む ResultPayload オブジェクト

説明

指定した型の新しいノードを作成します。オプションの引数により、ライブラリ、ノード名、親フロー、メタデータを指定できます。

delete_node

cmd.delete_node(node_name)

既存のノードを削除します。

引数

名前	引数の型	必須
node_name	string	🟢

戻り値

ノード削除ステータスを含む ResultPayload オブジェクト

説明

指定したノードをシステムから削除します。

run_node

cmd.run_node(node_name)

単一のノードを実行します。

引数

名前	引数の型	必須
node_name	string	🟢

戻り値

ノード実行ステータスを含む ResultPayload オブジェクト

説明

指定したノードを解決して実行します。

get_resolution_state_for_node

cmd.get_resolution_state_for_node(node_name)

ノードの解決（実行）状態を返します。

引数

名前	引数の型	必須
node_name	string	🟢

戻り値

ノードの解決状態を含む ResultPayload オブジェクト

説明

指定したノードの現在の解決状態を取得します。

get_metadata_for_node

cmd.get_metadata_for_node(node_name)

ノードのメタデータを返します。

引数

名前	引数の型	必須
node_name	string	🟢

戻り値

ノードのメタデータを含む ResultPayload オブジェクト

説明

指定したノードに関連付けられているメタデータを取得します。

set_metadata_for_node

cmd.set_metadata_for_node(node_name, metadata)

ノードのメタデータを設定します。

引数

名前	引数の型	必須
node_name	string	🟢
metadata	dict	🟢

戻り値

メタデータ更新ステータスを含む ResultPayload オブジェクト

説明

指定したノードのメタデータを設定します。

exists

cmd.exists(node)

ノードが存在するかどうかを確認します。

引数

名前	引数の型	必須
node	string	🟢

戻り値

ノードが存在するかどうかを示すブール値（True / False）

説明

指定したノードが存在する場合は True、それ以外は False を返します。

ls

cmd.ls(**kwargs)

システム内のオブジェクトを一覧表示します。

引数

名前	引数の型	必須
**kwargs	dict	⚪

戻り値

フィルタ条件に一致するオブジェクト名のリスト

説明

指定した条件（オプション）でフィルタリングされたシステム内のオブジェクトを一覧表示します。

パラメータ操作 (Parameter Operations)

list_params

cmd.list_params(node)

ノード上のすべてのパラメータを一覧表示します。

引数

名前	引数の型	必須
node	string	🟢

戻り値

パラメータ名のリスト

説明

指定したノード上のすべてのパラメータのリストを返します。

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 of strings	⚪
output_type	string	⚪
edit	boolean	⚪
tooltip_as_input	string または list	⚪
tooltip_as_property	string または list	⚪
tooltip_as_output	string または list	⚪
ui_options	ParameterUIOptions	⚪
mode_allowed_input	boolean	⚪
mode_allowed_property	boolean	⚪
mode_allowed_output	boolean	⚪

戻り値

パラメータ追加ステータスを含む ResultPayload オブジェクト

説明

指定された設定でノードにパラメータを追加します。edit=True の場合、既存のパラメータを変更します。

del_param

cmd.del_param(node_name, parameter_name)

ノードからパラメータを削除します。

引数

名前	引数の型	必須
node_name	string	🟢
parameter_name	string	🟢

戻り値

パラメータ削除ステータスを含む ResultPayload オブジェクト

説明

指定したパラメータをノードから削除します。

param_info

cmd.param_info(node, param) または cmd.param_info("node.param")

パラメータに関する詳細情報を取得します。

引数

名前	引数の型	必須
node	string	🟢
param	string	🟢

戻り値

パラメータの詳細を含む ResultPayload オブジェクト

説明

指定したパラメータの詳細情報を返します。ノードとパラメータを別々に渡す形式、または単一の "node.param" 文字列形式のいずれも受け付けます。

get_value

cmd.get_value(node, param) または cmd.get_value("node.param")

パラメータの値を取得します。

引数

名前	引数の型	必須
node	string	🟢
param	string	🟢

戻り値

パラメータの値、または失敗結果

説明

指定したパラメータの現在の値を返します。コンテナ型に対するインデックスアクセスもサポートされています（例: "node.param[0]"）。

set_value

cmd.set_value(node, param, value) または cmd.set_value("node.param", value)

パラメータの値を設定します。

引数

名前	引数の型	必須
node	string	🟢
param	string	🟢
value	any	🟢

戻り値

値更新ステータスを含む ResultPayload オブジェクト

説明

指定したパラメータの値を設定します。コンテナ型に対するインデックスアクセスもサポートされています（例: "node.param[0]"）。

接続操作 (Connection Operations)

connect

cmd.connect(source, destination)

2 つのパラメータ間にデータ接続を作成します。

引数

名前	引数の型	必須
source	string	🟢
destination	string	🟢

戻り値

接続作成ステータスを含む ResultPayload オブジェクト

説明

送信元（source）パラメータから送信先（destination）パラメータへの接続を作成します。両方の引数は "node.param" の形式で指定します。

exec_chain

cmd.exec_chain(*node_names)

一連のノード間に実行順序（Control Flow）の接続を作成します。

引数

名前	引数の型	必須
*node_names	string(s)	🟢

戻り値

各接続試行の結果を含む辞書（Dictionary）

説明

一連のノード間に exec_out -> exec_in の接続を作成し、順番に実行されるようにチェーン化します。

delete_connection

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

パラメータ間の接続を削除します。

引数

名前	引数の型	必須
source_node_name	string	🟢
source_param_name	string	🟢
target_node_name	string	🟢
target_param_name	string	🟢

戻り値

接続削除ステータスを含む ResultPayload オブジェクト

説明

指定した送信元パラメータと送信先パラメータの間の接続を解除・削除します。

get_connections_for_node

cmd.get_connections_for_node(node_name)

ノードに関連するすべての接続を一覧表示します。

引数

名前	引数の型	必須
node_name	string	🟢

戻り値

接続情報を含む ResultPayload オブジェクト

説明

指定したノードに関連するすべての接続（入力接続および出力接続の両方）を返します。

ライブラリ操作 (Library Operations)

get_available_libraries

cmd.get_available_libraries()

利用可能なすべてのノードライブラリを一覧表示します。

引数

なし

戻り値

ライブラリ名のリストを含む ResultPayload オブジェクト

説明

システムに登録されているすべてのノードライブラリを返します。

get_node_types_in_library

cmd.get_node_types_in_library(library_name)

ライブラリ内のすべてのノードタイプを一覧表示します。

引数

名前	引数の型	必須
library_name	string	🟢

戻り値

ノードタイプ名のリストを含む ResultPayload オブジェクト

説明

指定したライブラリで利用可能なすべてのノードタイプを返します。

get_node_metadata_from_library

cmd.get_node_metadata_from_library(library_name, node_type_name)

ノードタイプのメタデータを取得します。

引数

名前	引数の型	必須
library_name	string	🟢
node_type_name	string	🟢

戻り値

ノードタイプのメタデータを含む ResultPayload オブジェクト

説明

指定したライブラリ内の指定したノードタイプのメタデータを返します。

設定操作 (Config Operations)

get_config_value

cmd.get_config_value(category_and_key)

設定値を取得します。

引数

名前	引数の型	必須
category_and_key	string	🟢

戻り値

設定値を含む ResultPayload オブジェクト

説明

指定した設定キーに対応する値を返します。

set_config_value

cmd.set_config_value(category_and_key, value)

設定値を設定・更新します。

引数

名前	引数の型	必須
category_and_key	string	🟢
value	any	🟢

戻り値

設定更新ステータスを含む ResultPayload オブジェクト

説明

指定した設定キーに値を設定します。

get_config_category

cmd.get_config_category(category=None)

指定したカテゴリ内のすべての設定値を取得します。

引数

名前	引数の型	必須
category	string	⚪

戻り値

カテゴリ内の設定値を含む ResultPayload オブジェクト

説明

指定したカテゴリ内のすべての設定値を返します。カテゴリが指定されていない場合は、すべての設定値を返します。

set_config_category

cmd.set_config_category(category=None, contents={})

指定したカテゴリの設定値を一括設定します。

引数

名前	引数の型	必須
category	string	⚪
contents	dict	⚪

戻り値

カテゴリ設定更新ステータスを含む ResultPayload オブジェクト

説明

指定したカテゴリのすべての設定値を指定された内容で設定します。

ユーティリティ操作 (Utility Operations)

run_arbitrary_python

cmd.run_arbitrary_python(python_str)

任意の Python コードを実行します。

引数

名前	引数の型	必須
python_str	string	🟢

戻り値

実行ステータスと結果を含む ResultPayload オブジェクト

説明

指定された Python コード文字列を Griptape 環境内で実行します。

実装例 (Examples)

フローとノードの作成

# 新しいフローを作成
flow = cmd.create_flow(flow_name="MyFlow")

# フロー内に 2 つのノードを作成
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")

パラメータ値の設定と接続の作成

# パラメータ値を設定
cmd.set_value("MyText.text", "これは要約するためのサンプルテキストです。")

# 2 つのノードを接続
cmd.connect("MyText.text", "MyAgent.prompt")

フローの実行

# フローを実行
cmd.run_flow("MyFlow")

# 結果を取得
summary = cmd.get_value("MyAgent.output")
print(summary)  # 要約結果が出力されます！

パラメータの操作

# ノードに新しいパラメータを追加
cmd.add_param(
    node_name="MyAgent",
    parameter_name="sunglasses",
    default_value=100,
    tooltip="サングラスのクール度",
    type=["int"],
)

# 新しいパラメータの値を設定
cmd.set_value("MyAgent.sunglasses", 50)

# パラメータの定義を変更
cmd.add_param(node_name="MyAgent", parameter_name="sunglasses", tooltip="半減させた場合のサングラスのクール度", edit=1)

一覧表示と存在確認

# フロー内のすべてのノードを一覧表示
nodes = cmd.get_nodes_in_flow("MyFlow")
print(nodes)  # ["MyText", "MyAgent"]

# ノード上のすべてのパラメータを一覧表示
params = cmd.list_params("MyAgent")
print(params)  # ["agent", "prompt_driver", "tools", "rulesets", "prompt", "prompt_context", "output"]

# ノードが存在するか確認
if cmd.exists("MyText"):
    print("MyText ノードが存在します")  # True