コンテンツにスキップ

ノード開発 (Developing Nodes)

このセクションでは、Griptape Nodes 向けのカスタムノードを開発するための包括的なドキュメントを提供します。

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"

はじめに (Introduction)

Griptape Nodes は、ビジュアルプログラミングを通じて複雑な AI ワークフローを直感的に構築できるようにするモジュール式コンポーネントです。本セクションでは、堅牢で使いやすいノードを作成するための基本概念から高度な設計パターンまでを詳しく解説します。

ノード開発が初めての方は、まず スタートガイド (Getting Started Guide) から始めることをお勧めします。ノード開発エコシステムの概要と、最初のノードを作成する手順をわかりやすく紹介しています。

すべてのノードは BaseNode のサブクラスを継承します：

  • DataNode: データ処理タスク向け
  • ControlNode: exec_in/out によるフロー制御向け
  • StartNode: ワークフローの初期化用
  • EndNode: ワークフローの終了用

コア概念 (Core Concepts)

基本クラス (Base Classes)

  • DataNode: 実行フロー制御（exec）を伴わない純粋なデータ処理を行います。データの変換や同期的な受け渡しを行うノードに使用します — 入力パラメータが満たされた瞬間に即座に処理が実行されます。
  • ControlNode: exec_in / exec_out 接続によって実行フローを明示的に制御します。外部 API 呼び出しや長時間の処理を行うノードに使用します — 非同期処理の場合は async def aprocess() をオーバーライドし、ブロッキング処理の場合は AsyncResult を使ってバックグラウンドスレッドに委託します。API を呼び出して結果をポーリングするようなノードは、必ず ControlNode として実装してください。
  • StartNode: ワークフローのエントリポイント。
  • EndNode: ワークフローの終端ポイント。

パラメータ (Parameters)

Parameter クラスを通じて入力、出力、およびプロパティを定義します。パラメータは以下をサポートしています：

  • 型検証 (Type validation)
  • UI カスタマイズ
  • 接続制約 (Connection constraints)
  • デフォルト値
  • トレイト (Options, Slider, Button, ColorPicker)

完全なリファレンスについては パラメータ (Parameters) を参照してください。

プロセスメソッド (Process Method)

process() メソッドにノードの中核ロジックを実装します。出力値は self.parameter_output_values に格納します。非同期処理を行う場合は、代わりに async def aprocess() をオーバーライドします（詳細は 実行とライフサイクル (Execution and Lifecycle) を参照）。

ノードの状態 (Node States)

  • UNRESOLVED: 初期状態
  • RESOLVING: 処理実行中
  • RESOLVED: 処理完了

接続 (Connections)

接続の検証と処理はライフサイクルコールバックを通じて管理されます（実行とライフサイクル を参照）。

イベント (Events)

ワークフローイベントへの反応には on_griptape_event を使用します。

開発環境のセットアップ (Setting Up)

  1. griptape-nodes をインストールします。
  2. 依存関係の分離のために Python 仮想環境を使用します。
  3. シンプルなフォルダ階層でプロジェクトを構成します。
  4. griptape_nodes.exe_types.* および griptape_nodes_library.utils.* から必要なモジュールをインポートします。

ノードの作成 (Creating a Node)

基本的なノード構造 (Basic Node Structure)

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


class MyNode(DataNode):
    def __init__(self, **kwargs) -> None:
        super().__init__(**kwargs)
        self.category = "Category"
        self.description = "Description"

        self.add_parameter(Parameter(name="input", input_types=["str"], type="str", tooltip="Input parameter"))

        self.add_parameter(Parameter(name="output", output_type="str", tooltip="Output parameter"))

    def process(self) -> None:
        val = self.get_parameter_value("input").upper()
        self.parameter_output_values["output"] = val

ドキュメント構成 (Documentation Structure)

テンプレートリポジトリから始める (Start from the Template Repository)

本番環境に対応したノードライブラリを作成する最も迅速な方法は、公式のテンプレートリポジトリを利用することです：

Griptape Nodes Library Template (readme)

必要なボイラープレート、テストフレームワーク、ドキュメントのパターンがあらかじめ整っています。開発の流れ：

  1. テンプレートからリポジトリを作成 - GitHub テンプレートから自身のリポジトリを生成します。
  2. 環境のセットアップ - Griptape Nodes のワークスペースディレクトリにリポジトリをクローンします。
  3. ライブラリの設定 - ディレクトリ名を変更し、pyproject.toml のパッケージ情報を更新します。
  4. ノードの作成 - 適切なパラメータを持つノードクラス（ControlNode または DataNode）を定義します。
  5. ロジックの実装 - 必要な process() メソッドおよび追加機能をコーディングします。
  6. ライブラリメタデータの設定 - ノードとカテゴリ情報を記載した library.json ファイルを作成します。
  7. エンジンへの登録 - 設定インターフェースを通じて Griptape Nodes にライブラリを追加します。
  8. テストと利用 - Griptape Nodes の UI 上でカスタムノードを配置してフローを作成・テストします。

ノードの設計方法を深く理解するには、標準ライブラリで採用されている設計パターン（ノードリファレンス）も参考にしてください。