コンテンツにスキップ

ノード開発のスタートガイド (Getting Started with Node Development)

AI アシスタントおよびコーディングエージェント向け (For AI Assistants & Coding Agents)

本ガイドは、AI コーディングアシスタントが直接読み込める後処理済み Markdown として公開されています。マシン可読なインデックスについては エージェント向け案内 (For Agents) を参照してください。

利用方法: 以下のプロンプト例のように AI アシスタントへ URL を指示してください： "Read this node development guide: [URL] and help me build a custom node"

このページは、Griptape Nodes エコシステムを初めて利用する開発者 が、確信を持ってカスタムノードを作成できるようにするための実践的ガイドです。

本セクションのより詳細で網羅的な技術ドキュメントへ進む前の、わかりやすい「入り口」となっています（全体のドキュメントマップは 概要 (Overview) を参照してください）。

コードを書く前のメンタルモデル (What you’ll build mentally before you write code)

全体像として：

  • ノード (Node) は、パラメータ（入力/出力/プロパティ）と process() メソッドを定義する Python クラスです。
  • ワークフロー (Flow) は、パラメータによって相互接続されたノードのグラフです。
  • パラメータは以下の両方の役割を果たします：
    • UI 要素（ユーザーが画面上で確認・編集・配線するもの）
    • 型チェックされた接続点（何と何を配線できるかを制御するもの）

適切なベースノード型の選択

  • DataNode: ノードが純粋にデータを処理し、実行フローの分岐を必要としない場合に使用します。
  • ControlNode: ノードが明示的な実行フロー（control in/out）を制御する必要がある場合に使用します。
  • SuccessFailureNode: 成功と失敗で別々の実行制御出力を提供したい場合に使用します。
  • 反復ループノード: エンジンのループプリミティブは BaseIterativeStartNode / BaseIterativeEndNode 上に構築されています。

迷った場合は、まず DataNode から始めて、必要になった時点で ControlNode やループノードへとステップアップしてください。

Griptape Node を初めて作成する場合、最も手早い手順は以下の通りです：

  • ライブラリテンプレートリポジトリ から開始する（概要 を参照）
  • まずは単一の DataNode（制御フローなし）を作成する
  • 一般的なデータ型には組み込みの Parameter* ヘルパー構造を使用する
  • validate_before_node_run() で入力を検証する
  • シークレットは GriptapeNodes.SecretsManager() ではなく GetSecretValueRequest で取得する

最初のノード（最小限のコード例） (Your first node)

以下は、文字列を受け取り、大文字に変換して出力する最小構成のノード例です。

from griptape_nodes.exe_types.core_types import Parameter, ParameterMode
from griptape_nodes.exe_types.node_types import DataNode


class UppercaseText(DataNode):
    def __init__(self, **kwargs) -> None:
        # 親コンストラクタを必ず呼び出します。これにより、エンジンが
        # ノードの内部状態を初期化し、ノードコンテキストを登録します。
        super().__init__(**kwargs)

        # add_parameter(...) でパラメータを登録します。
        # パラメータは以下を定義します：
        # - ユーザーが設定できる値 (PROPERTY モード)
        # - 他のノードから接続できる入力 (INPUT モード)
        # - 他のノードへ接続できる出力 (OUTPUT モード)
        self.add_parameter(
            Parameter(
                name="text",
                # パラメータの "type" はエンジンにおける主要なデータ型です。
                # UI のデフォルト表示や接続時の型チェックに影響します。
                type="str",
                # input_types は、このパラメータに接続できる入力型を制御します。
                # 柔軟な配線を許可するために複数の型を指定することも可能です。
                input_types=["str"],
                # default_value は、何も接続されておらずユーザーも
                # UI 上で値を指定していない場合に使用されます。
                default_value="Hello Griptape Nodes",
                allowed_modes={ParameterMode.INPUT, ParameterMode.PROPERTY},
                tooltip="入力テキスト",
            )
        )

        self.add_parameter(
            Parameter(
                name="uppercased",
                type="str",
                output_type="str",
                allowed_modes={ParameterMode.OUTPUT},
                tooltip="大文字変換された出力テキスト",
            )
        )

    def process(self) -> None:
        # process() はフロー内でノードが実行された際に呼び出されます。
        # get_parameter_value(...) で入力を取得し、parameter_output_values に出力を書き込みます。
        text = self.get_parameter_value("text") or ""
        self.parameter_output_values["uppercased"] = text.upper()

動作を確認しながら進める (Test as you go)

  • ノードを追加・編集した後は、シンプルなフローを作成して以下を確認してください：
    • パラメータ UI が正しく表示されているか（入力、プロパティ、出力）
    • 出力値が UI 上で正常に更新されるか
    • バリデーションエラーが具体的で分かりやすいメッセージになっているか

パラメータの実践モデル (Parameters: the practical model)

すべてのパラメータは、以下の 3 つの「モード」で使用できます：

  • Input: 他のノードからの接続を受け入れる
  • Output: 他のノードへの接続を提供する
  • Property: ノード UI 上でユーザーが設定できる値

一般的なケースには Parameter* ヘルパーを使用

コアエンジンは、griptape_nodes.exe_types.param_types.* 配下に以下のような便利なヘルパー構造を提供しています：

  • ParameterString, ParameterInt, ParameterFloat, ParameterBool
  • ParameterJson, ParameterDict, ParameterRange
  • ParameterImage, ParameterAudio, ParameterVideo, Parameter3D
  • ParameterButton

これらのヘルパーは以下の理由で非常に有用です：

  • 意図した type / output_type および一般的な ui_options があらかじめ設定されている
  • 安全に値を型変換する accept_any=True をサポートしていることが多い
  • ランタイム更新のためにいくつかの UI オプションを Python プロパティとして公開している

詳細は パラメータヘルパー構造 を参照してください。

コンテナ: ParameterList と ParameterDictionary

  • ParameterList: ノード UI 上で「同種の要素のリスト」を扱いたい場合に使用します。
    • 取得: get_parameter_list_value() はネストされたイテラブルを平坦化（flatten）します。
    • 注意: 現在の実装では falsy な要素（0 や False など）が除外されます。これらを保持したい場合は get_parameter_value() を使用して手動で平坦化してください。
  • ParameterDictionary: UI 上でキー/値のペアのエントリを扱いたい場合に使用します。

トレイト: UI 動作とバリデーション

トレイト（Traits）をパラメータにアタッチすることで、特殊な UI 表示や振る舞いを追加できます。

よく使用されるトレイト：

  • Options(...): ドロップダウン選択（シリアライズ安定性のため選択肢は ui_options に保存）
  • Slider(min_val, max_val): スライダー UI + 範囲検証
  • FileSystemPicker(...): ファイル/ディレクトリ選択ダイアログ UI（フィルタおよびワークスペース制約付き）

数値スライダーパラメータの実装例：

from griptape_nodes.exe_types.core_types import Parameter, ParameterMode
from griptape_nodes.traits.slider import Slider

self.add_parameter(
    Parameter(
        name="temperature",
        type="float",
        default_value=0.7,
        tooltip="サンプリング温度（高いほどランダムになります）",
        # 純粋な PROPERTY にすることも、配線を許可するために INPUT+PROPERTY にすることも可能
        allowed_modes={ParameterMode.INPUT, ParameterMode.PROPERTY},
        # traits 引数を介してインラインでアタッチ
        traits={Slider(min_val=0.0, max_val=2.0)},
    )
)

バリデーション、エラー処理、ユーザー体験 (Validation, error handling, and user experience)

初心者向けの適切な指針：

  • パラメータ検証には validate_before_node_run() を使用する
  • 早期に失敗させ、ユーザーが対処できるメッセージ（何を接続すべきか、何を設定すべきか）を提示する
  • ノードが失敗してもワークフロー全体の実行を継続させたい場合は、SuccessFailureNode を使用して失敗ルートを明示的に配線する

よくある落とし穴 (Common gotchas)

  • get_parameter_list_value() で falsy な値が欠落する: リストに 0 や False が含まれる可能性がある場合は、get_parameter_value() を使用して手動で処理してください。
  • ui_options の競合: hide=... 引数と ui_options={"hide": ...} の両方を指定した場合、ui_options の値が優先されます。
  • シークレット: API キーをハードコードしないでください。必ず GriptapeNodes.handle_request(GetSecretValueRequest(key=...)) を使用してください。

シークレットと設定 (Secrets and configuration)

ノードで API キーやパスワードなどのシークレットが必要な場合：

  • ライブラリ設定ファイル（griptape_nodes_library.json）でシークレットを登録します
  • GriptapeNodes.handle_request(GetSecretValueRequest(key="NAME")) 経由で読み込みます。ノードがワーカー内で実行されている間は直接のマネージャーアクセスは拒否され、シークレットを管理するメインエンジンによって安全に値が返されます。

次のステップ (Next steps)