name: griptape-nodes-workflows description: エンジンの MCP サーバーを操作して、Griptape Nodes のワークフローを構築、実行、検証します。ノードワークフローの構築、既存フローの実行、パラメータ値の設定、ノード間の接続の配線、ワークフロー実行結果の読み取りをユーザーから求められた場合に使用します。トリガーとなるフレーズ: 「ワークフローを構築して」、「フローにノードを追加して」、「これらのノードを接続して」、「フローを実行して」、「ノード X の出力を確認して」など。

Griptape Nodes ワークフロー構築ガイド (Workflow Construction Guide)

このスキルは、エンジンの MCP サーバーを介したコールドスタートからの完全なサイクル（構築 → 配線 → 実行 → 出力読み取り）と、実際のワークフロー運用から得られた推奨パターンおよび注意点（Gotchas）を網羅しています。

メンタルモデル (Mental Model)

ワークフロー (Workflow): 最上位の名前空間。アクティブにできるのは同時に 1 つのみです。ClearAllObjectStateRequest でリセットできます。
フロー (Flow): ワークフロー内のキャンバス。ワークフローは正確に 1 つの最上位「キャンバス」フローを持ちます。サブフローも作成可能ですが、通常の作業ではほとんど必要ありません。
ノード (Node): パラメータ（入力、出力、プロパティ）を持つ作業単位。
接続 (Connection): 2 つのパラメータ間のエッジ。2 種類存在します：
- データフロー (Data flow): あるノードの型付きパラメータ → 別のノードの型付きパラメータ。エンジンはデータ依存関係から実行順序を自動導出するため、通常はデータ接続のみで十分です。
- コントロールフロー (Control flow): exec_out → exec_in。2 つのノード間でデータを共有しないが、特定の順序で実行する必要がある場合（副作用を伴うステップや条件分岐など）にのみ必要です。デフォルトではスキップしてください。
現在のコンテキスト (Current Context): スタック構造（ワークフロー → フロー → ノード）。名前を省略したリクエストのほとんどは、自動的に「現在のアクティブなコンテキスト」を対象とします。

MCP サーバーが実際に公開しているもの (What the MCP server actually exposes)

すべての MCP ツールは、SUPPORTED_REQUEST_EVENTS（src/griptape_nodes/servers/mcp.py）に登録されている RequestPayload クラスと 1:1 で対応しています。各ツール名にはサーバー名のプレフィックスが付与されているため、例えば CreateNodeRequest リクエストは griptape_nodes_CreateNodeRequest として呼び出せます。事前に把握しておくべき重要なポイント：

個々のリクエストに複数形（Plural）のバリエーションはありません。 CreateNodesRequest や CreateConnectionsRequest などは存在しません。N 個のノードを作成する場合は、CreateNodeRequest を N 回送信するか、後述の単一の EventRequestBatch 呼び出しにラップして送信します。
CreateNodeRequest はパラメータ値を受け取りません。 パラメータの設定は、ノード作成後に常に独立した SetParameterValueRequest として行います。作成時に parameter_values や inputs を一括指定するショートカットはありません。
EventRequestBatch が唯一の並列/一括送信プリミティブです。 これは対応する RequestPayload クラスを持たない合成ツールであり、順序付けられた内部リクエストのリストを 1 つのトランスポートフレームで送信します。構築フェーズの形状が既に決まっている場合は、常にこれを活用してください。後述の「EventRequestBatch: 構築フェーズを 1 回の往復に集約」を参照してください。

最初にワークスペースを調査する (Survey the Workspace First)

何かを構築する前に、このエンジンに実際に何が読み込まれているかを確認してください。登録されているライブラリとそれらが公開しているノードタイプの集合が、後続のすべてのステップで参照できるカタログとなるため、存在しない（または想定と異なるライブラリに属する）名前を推測して無駄な往復を重ねる前に、初期調査に往復を使ってください。

ディスク上のワークスペースディレクトリを特定する

MCP インターフェースには GetConfigValueRequest が公開されていないため、ユーザー設定ファイルを直接読み取ってワークスペースのパスを解決します。macOS / Linux では以下の場所にあります：

~/.config/griptape_nodes/griptape_nodes_config.json

確認すべき主要キー：

workspace_directory: 絶対（または ~ プレフィックス付き）のワークスペースルート。サンドボックスライブラリはこのディレクトリ内に配置されます。
app_events.on_app_initialization_complete.libraries_to_register: ローカルに登録されている griptape_nodes_library.json のパスのリスト。エントリは文字列、または {"path": "...", "enabled": true} オブジェクトです。これらを確認することで、サンドボックスノードを新規作成する前に既存ノードの Python モジュールを参照したい場合に、各ライブラリのソースコードがどこにあるかを把握できます。

サンドボックスのサブディレクトリキー（sandbox_library_directory）はオプションであり、デフォルトは sandbox_library です。したがって、サンドボックスの絶対パスは <workspace_directory>/<sandbox_library_directory>（例: ~/Projects/.../GriptapeNodes/sandbox_library）となります。

これはセッションごとに 1 回だけ行い、パスを記憶してください。実行の途中でパスが変化することはありません。

MCP を介して登録済みライブラリを調査する

A. griptape_nodes_ListRegisteredLibrariesRequest()
   → 現在読み込まれているライブラリ名のリスト（例: "Griptape Nodes Library",
     "Sandbox Library"）。期待するライブラリが存在しない場合、その配下のノードタイプに対する
     `DescribeNodeType` の呼び出しは解決できません。

B. griptape_nodes_ListNodeTypesInLibraryRequest(library="<name>")
   → 利用予定のライブラリごとに 1 回呼び出します。返されるノードタイプ名は、
     `CreateNodeRequest.node_type` や `DescribeNodeTypeRequest.node_type` に
     渡す正確な文字列です。

C. (オプション) griptape_nodes_ListCategoriesInLibraryRequest(library="<name>")
   → 巨大なライブラリの一部（例: 画像ノードのみ）に関心があり、次のステップのスコープを
     絞り込みたい場合に有用です。

セッションごとに一度これを行い、カタログを再利用してください。同じセッション内の事前の呼び出しによって、使用予定の各ノードタイプをどのライブラリが提供しているかが既に分かっている場合にのみ、この調査をスキップできます。

EventRequestBatch: 構築フェーズを 1 回の往復に集約

EventRequestBatch（MCP ツール名: griptape_nodes_EventRequestBatch）は、順序付けられた内部リクエストのリストを 1 つのトランスポートフレームにまとめます。構築フェーズの構成がすでに決まっている場合は常にこれを使用します — 一般的なパターンは、N 個の CreateNodeRequest + M 個の SetParameterValueRequest + K 個の CreateConnectionRequest + 1 個の AutoLayoutFlowRequest を、すべて 1 回の往復で実行することです。

リクエストの構造：

{
  "requests": [
    {"request_type": "CreateNodeRequest",
     "request": {"node_type": "TextInput", "node_name": "TextInput_1"}},
    {"request_type": "SetParameterValueRequest",
     "request": {"node_name": "TextInput_1", "parameter_name": "text", "value": "..."}}
  ],
  "timeout_ms": 60000
}

動作仕様：

順次ディスパッチ (Sequential dispatch): エンジンは送信順に内部リクエストを待機・実行します（for inner in batch.requests: await _dispatch_event_request(inner)）。そのため、同じバッチ内で CreateNodeRequest に続けてそのノードに対する SetParameterValueRequest を送信しても安全です。
事前検証 (Pre-flight validation): すべての内部リクエストは、ネットワークに送信される前にそれぞれの RequestPayload クラスに照らして検証されます。未知の request_type、JSON オブジェクトでない request、内部ペイロードの未知の kwargs がある場合、バッチ全体が TypeError / ValueError で事前に拒否されます。
スロット単位の障害分離 (Per-slot failure isolation): バッチのディスパッチが開始された後は、1 つのスロットで失敗が発生しても他のスロットの実行は中断されません。失敗したスロットは結果配列内に {"ok": false, "details": "..."} として返され、成功したスロットは単一ツール呼び出しと同じ平坦化されたオブジェクトとして返されます。バッチ全体が成功したと見なす前に、すべてのスロットの結果を確認してください。
ネスト不可: EventRequestBatch は意図的に SUPPORTED_REQUEST_EVENTS および内部 request_type の列挙型から除外されているため、バッチの中に別のバッチを含めることはできません。
サイズに応じたデフォルトタイムアウト: timeout_ms のデフォルトは 30000 × len(requests)（最大 300,000 ms = 5 分にクランプ）です。最後のスロットが StartFlowRequest(wait_for_completion=True) やその他の長時間実行呼び出しである場合は、明示的なタイムアウトを指定してください。そうしないと、同期実行がバッチの残りの予算を使い果たしてしまう可能性があります。なお、bool は明示的に拒否されるため、誤って True を渡して 1ms に扱われることはありません。

戻り値の構造: 送信順に並んだトリミング済みスロットレスポンスの JSON 配列。各スロットは、その request_type に対する単一ツールのディスパッチが返したであろうレスポンスと同一です。

[
  {"ok": true, "node_name": "TextInput_1", "...": "..."},
  {"ok": true, "finalized_value": "...", "...": "..."}
]

重要な推奨パターン: 同じバッチ内で後から参照するノードにあらかじめ名前を付ける

1 つのバッチ内では、後半のスロットを作成する前に前半のスロットの CreateNodeResultSuccess.node_name を読み取ることはできません — バッチ送信時にすべてのエントリが固定されているためです。したがって、以下のいずれかのアプローチを取ります：

すべての CreateNodeRequest に明示的な node_name を渡し、後続の SetParameterValueRequest / CreateConnectionRequest エントリでそれらの名前をそのまま再利用する。
構築を 2 つのバッチに分割する: 1 つ目でノードを作成し（結果配列から割り当てられた名前を読み取る）、2 つ目でパラメータを設定して配線する。

前者の「1 つのバッチ + 明示的なノード名」のパスの方がほぼ常に手数が少なく、後述のバッチ化レシピでもこの方法を採用しています。

標準コールドスタートレシピ (Canonical Cold-Start Recipe)

典型的な 3 ノードの線形パイプライン（TextInput → Agent → DisplayText）を構築する手順（前述のワークスペース調査によって関連ライブラリがこれらのノードタイプを提供していることが確認された後の手順）：

1. griptape_nodes_EnsureWorkflowAndFlowRequest()
   → workflow_name, flow_name, created_workflow, created_flow を返します。
     冪等（Idempotent）です: 両方がすでにコンテキストにあればそれらを再利用します。

2. griptape_nodes_DescribeNodeTypeRequest(node_type="TextInput")
3. griptape_nodes_DescribeNodeTypeRequest(node_type="Agent")
4. griptape_nodes_DescribeNodeTypeRequest(node_type="DisplayText")
   → 正確なパラメータ名、型、モードを取得します。注目すべき点:
     - データ入力 (mode_allowed_input == true)
     - データ出力 (mode_allowed_output == true)
     - コントロールパラメータ (type == "parametercontroltype"): 通常 exec_in / exec_out
       はスキップ可能です（メンタルモデル参照）

5. griptape_nodes_CreateNodeRequest(node_type="TextInput")
6. griptape_nodes_CreateNodeRequest(node_type="Agent")
7. griptape_nodes_CreateNodeRequest(node_type="DisplayText")
   → それぞれ平坦な `node_name`（例: "TextInput_1", "Agent_1"）を返します。レスポンスから
     確実に読み取り、命名規則を勝手に仮定しないでください。デフォルト名は `metadata.display_name`
     から生成され、空白を含む場合があります（例: "Text Input_1"）。安定した名前が必要な場合は、
     明示的に `node_name` を渡してください。

8. griptape_nodes_SetParameterValueRequest(
       node_name="TextInput_1", parameter_name="text", value="...")
   → CreateNode にはパラメータの一括設定ショートカットはありません。デフォルト以外の
     すべてのパラメータは個別の SetParameterValue で設定します。

9. griptape_nodes_CreateConnectionRequest(
       source_node_name="TextInput_1", source_parameter_name="text",
       target_node_name="Agent_1", target_parameter_name="prompt")
10. griptape_nodes_CreateConnectionRequest(
       source_node_name="Agent_1", source_parameter_name="output",
       target_node_name="DisplayText_1", target_parameter_name="text")
    → データ接続のみを行います。エンジンはデータ依存関係から実行順序を決定します。

11. griptape_nodes_AutoLayoutFlowRequest()
    → 複数ノードの構築後は必須です。これを行わないと、すべてのノードが座標 (0, 0) に
      配置され、キャンバス上で重なってしまいます。グラフをトポロジカルソートし、列と行の
      位置を割り当てます。現在のコンテキストフローを整列させる場合は `flow_name` を省略します。

12. griptape_nodes_StartFlowRequest(wait_for_completion=True, completion_timeout_ms=60000)
    → flow_name は省略します（ハンドラーが現在のコンテキストフローを使用します）。
      wait_for_completion はフローが解決またはタイムアウトするまでブロックします。

13. griptape_nodes_GetParameterValueRequest(node_name="DisplayText_1", parameter_name="text")
    → 終端ノードの出力を読み取ります。

計 13 回の MCP 呼び出し: ensure 1 回 + describe 3 回 + create 3 回 + set 1 回 + connect 2 回 + layout 1 回 + run 1 回 + read 1 回。より大きなグラフでも線形にスケールします：ノードごとに CreateNode 1 回と SetParameterValue 呼び出し、エッジごとに CreateConnection 1 回が加算されます。

バッチ化バリエーション（4 回の往復）

構築フェーズ（上記ステップ 5 〜 11）は形状が固定されているため、1 回の EventRequestBatch 呼び出しに集約できます。調査フェーズは結果を確認して構築ペイロードに反映させる必要があるため独立したバッチにするのが適切であり、StartFlowRequest は長いタイムアウトが他の処理を阻害しないよう構築バッチの外に置くのが通常です：

1. EnsureWorkflowAndFlowRequest (1 回)
2. EventRequestBatch([ (1 回、順次実行)
     DescribeNodeTypeRequest("TextInput"),
     DescribeNodeTypeRequest("Agent"),
     DescribeNodeTypeRequest("DisplayText"),
   ])
3. EventRequestBatch([ (1 回、順次実行)
     CreateNodeRequest(node_type="TextInput", node_name="TextInput_1"),
     CreateNodeRequest(node_type="Agent", node_name="Agent_1"),
     CreateNodeRequest(node_type="DisplayText", node_name="DisplayText_1"),
     SetParameterValueRequest(node_name="TextInput_1", parameter_name="text", value="..."),
     CreateConnectionRequest(source_node_name="TextInput_1", source_parameter_name="text",
                             target_node_name="Agent_1", target_parameter_name="prompt"),
     CreateConnectionRequest(source_node_name="Agent_1", source_parameter_name="output",
                             target_node_name="DisplayText_1", target_parameter_name="text"),
     AutoLayoutFlowRequest(),
   ])
4. StartFlowRequest(wait_for_completion=True, completion_timeout_ms=60000)
   + GetParameterValueRequest("DisplayText_1", "text") (2 回)

13 回の往復が 4 回に短縮されます。各バッチ実行後は結果配列を走査し、次のステップに進む前にすべてのスロットが ok: true を返していることを確認してください。スロット単位の失敗はバッチの残りの実行を中断させないため、スロット 4 のスペルミスを見逃すと、スロット 5 と 6 が無効な状態に対して実行されてしまいます。

主要な実践原則 (Key Idioms)

ノードタイプを選択する前にワークスペースを調査する。 ~/.config/griptape_nodes/griptape_nodes_config.json の JSON 設定を読み取ってサンドボックスディレクトリと登録済みライブラリの場所を把握し、DescribeNodeType を呼び出す前に利用予定のライブラリに対して ListRegisteredLibrariesRequest と ListNodeTypesInLibraryRequest を実行してください。このカタログにより、このエンジンに実際にどのノードタイプが存在し、各ノードがどのライブラリに属しているかが分かります。これは、同じ名前のノードが複数のライブラリに存在する場合に DescribeNodeTypeRequest.library や CreateNodeRequest.specific_library_name に渡すべき必須の情報です。
配線する前に定義を検出する。 パラメータ名を推測する前に、使用する各ノードタイプに対して必ず DescribeNodeType を呼び出してください。初期に 3 〜 5 回の呼び出しが必要になりますが、誤ったパラメータ名の推測やタイポによる多数のトラブルシュート往復を防ぐことができます。
形状が決まったら EventRequestBatch でバッチ化する。 検出フェーズ以降の処理は通常、形状が固定されています（N 個の作成 + M 個の設定 + K 個の接続 + レイアウト）。それらを 1 回の EventRequestBatch にまとめ、同じバッチ内で後から参照するすべてのノードにあらかじめ名前を付けてください。結果配列のすべてのスロットを検査してください。スロットごとの失敗は他の処理を停止させません。同期実行時間をカバーするように timeout_ms を引き上げない限り、StartFlowRequest は構築バッチに含めないでください。
コントロールフローではなくデータフローを配線する。 エンジンはデータ依存関係から実行順序を導出するため、exec_out → exec_in の接続は通常不要です。ノード間でデータをやり取りしないが特定の順序で実行する必要がある場合にのみ追加してください。
複数ノードを構築した後は必ず AutoLayout を実行する。 これを行わないと、ノードはすべて (0, 0) に配置されて重なってしまいます。AutoLayoutFlowRequest は 1 回の往復で実行できる冪等な操作です。構築フェーズの締めくくりとして必ず実行してください。
StartFlowRequest では wait_for_completion=True を使用する。 LLM、画像生成、長時間の I/O を伴うワークフローでは、completion_timeout_ms を十分長め（60,000 ms 以上）に設定してください。そうしないと、フローが開始された瞬間に呼び出しが復帰してしまい、自前で GetNodeResolutionStateRequest をポーリングする必要が生じます。
単一フローの構築直後は StartFlowRequest の flow_name を省略する。 ハンドラーはデフォルトで現在のコンテキストフローを使用します。
レスポンスを読み取り、名前を勝手に仮定しない。 CreateNodeResultSuccess.node_name が、以降のすべての呼び出しにおける正幹の識別子となります。SetParameterValueRequest、CreateConnectionRequest、GetParameterValueRequest にその文字列をそのまま渡してください。

レスポンスの構造 (Response Shape)

すべての MCP ツールはトリミングされたオブジェクトを返します（エンジンのエンベロープはサーバー側の _trim_response でアンラップされます）：

{
  "ok": true,
  "details": "<人間が読めるサマリー。省略される場合あり>",
  "altered_workflow_state": true|false,
  "...": "...ペイロードの各フィールド..."
}

ok はエンジンが *ResultSuccess ペイロードを生成したかどうかを反映します。残りのフィールドは内部の結果クラスから平坦化されて展開されます。例えば CreateNodeResultSuccess.node_name は response["node_name"] としてアクセスでき、EnsureWorkflowAndFlowResultSuccess はトップレベルに workflow_name、flow_name、created_workflow、created_flow を公開し、AutoLayoutFlowResultSuccess は flow_name と positioned_nodes を公開します。失敗時は、エンジンの result_details メッセージが添付された MCP ツールエラーとして表面化します。

EventRequestBatch は単一オブジェクトではなく JSON 配列を返します。各スロットは上記の単一呼び出しの形式を反映しているため、バッチ化された構築フェーズは [{"ok": true, "node_name": "TextInput_1", ...}, {"ok": true, ...}, ...] のようになります。失敗したスロットはその位置に {"ok": false, "details": "..."} として返され、配列の残りのスロットはそのまま実行されます。

注意点と落とし穴 (Gotchas)

DescribeNodeType が不完全な場合がある

DescribeNodeType はノードクラスをインスタンス化することで情報を検出します。__init__ で I/O（ネットワーク、認証、ディスク）を実行するノードタイプの場合、インスタンス化に失敗することがあります。その場合でもリクエスト自体は成功しますが、以下が返されます：

完全なライブラリレベルの metadata（カテゴリ、説明、display_name など）
parameters: []（空 — パラメータが宣言される前にインスタンス化が失敗したため）
原因を示す details 内の WARNING レベルのエントリ

ノードの役割自体は分かりますが、MCP 単体からはパラメータスキーマを確認できません。別のノードタイプへのフォールバックを検討するか、適切な認証情報が設定された環境で describe を実行してください。

CreateNode が暗黙的に ErrorProxyNode を生成することがある

ノードのインスタンス化に失敗し、create_error_proxy_on_failure=True（デフォルト）である場合、エンジンは ErrorProxyNode を代わりに配置して成功を報告します。後続のステップで原因不明のエラーが発生した場合は、レスポンスの node_type（プロキシクラス名になっているか）や details 文字列を確認してください。厳格な失敗判定が必要な場合は、リクエストで create_error_proxy_on_failure=False を設定してください。

デフォルトのノード名には空白が含まれる

エンジンはノードの名前を metadata.display_name に基づいて命名するため、多くの場合、空白を含む人間が読みやすい形式になります（例: "Text Input_1"、"Display Text_1"）。これはすべての API で動作しますが、タイポしやすくなります。リクエストごとに明示的な node_name を渡すか、CreateNodeResultSuccess から返された node_name を常に読み取ってそのまま再利用してください。

接続リクエストのフィールド名は短縮されていない

CreateConnectionRequest では、source_node_name、source_parameter_name、target_node_name、target_parameter_name という完全なフィールド名を使用します。短いエイリアス（source、source_param など）は存在しません。ここでのスペルミスは、分かりやすい「未知のフィールド」エラーではなく、Pydantic からの不透明なバリデーションエラーとして表面化します。

コンテキスト内で同時にアクティブにできるワークフローは 1 つのみ

すでにワークフローがコンテキストに存在する場合、SetWorkflowContextRequest は拒否されます。切り替えるには、事前に ClearAllObjectStateRequest(i_know_what_im_doing=True) を実行します — これによりすべて（ノード、フロー、接続、ワークフロー）が消去されます。現時点ではこれより緩やかなリセット手段はありません。

実行中のエージェントを途中で中断することはできない

現時点では、実行中のフローを一時停止またはキャンセルする機能はありません。completion_timeout_ms を使用して待機時間の上限を設定してください。タイムアウトが発生した場合、StartFlowRequest は失敗を返しますが、フロー自体は完了するかエラーになるまでエンジン内で動作し続けます。その間、後続の StartFlowRequest は「Flow is already running」として失敗します。

ツール早見表 (Tool Cheat Sheet)

目的	ツール
コールド状態からワークフローとフローをブートストラップ	`EnsureWorkflowAndFlowRequest`
1 回の往復で N 個のリクエストを一括送信	`EventRequestBatch`（合成ツール。後続スロットで参照するノードにあらかじめ名前を付ける）
ライブラリ / ノードタイプの検出	`ListRegisteredLibrariesRequest`, `ListNodeTypesInLibraryRequest`, `ListCategoriesInLibraryRequest`
ノードタイプのパラメータ検証	`DescribeNodeTypeRequest`
ノードの作成	`CreateNodeRequest`
単一エッジの配線	`CreateConnectionRequest`
複数ノード構築後のキャンバス自動整列	`AutoLayoutFlowRequest`
単一ノードを明示的な座標に移動	`SetNodeMetadataRequest`（`metadata.position` を設定）
パラメータ値の設定	`SetParameterValueRequest`
パラメータ値の読み取り	`GetParameterValueRequest`
稼働中ノードのパラメータスキーマ/詳細の検査	`GetParameterDetailsRequest`, `ListParametersOnNodeRequest`
同期実行	`StartFlowRequest(wait_for_completion=True, completion_timeout_ms=...)`
特定ノードからの実行開始	`StartFlowFromNodeRequest`
コントロールフローを発火させずに単一ノードを解決	`ResolveNodeRequest`
単一ノードを直接実行	`ExecuteNodeRequest`
ノードまたはフローの名前変更	`RenameObjectRequest(allow_next_closest_name_available=True)`
ノードのロックまたはロック解除	`SetLockNodeStateRequest`
ノードのパラメータをデフォルト値にリセット	`ResetNodeToDefaultsRequest`
状態の検査	`ListNodesInFlowRequest`, `ListConnectionsForNodeRequest`, `GetNodeResolutionStateRequest`, `GetNodeMetadataRequest`, `GetConnectionsForParameterRequest`
Python クラスによるノード検索（例: StartFlow, Agent）	`ListNodesInFlowRequest(node_types=["StartFlow", "Agent"])` — クラス名が一致するノードのみ返却。全ノード取得時は省略
ディスク上の Python ソースからサンドボックスノードタイプを登録	`RegisterSandboxNodeFromSourceRequest`（下記カスタムノード参照）
すべてのリセット	`ClearAllObjectStateRequest(i_know_what_im_doing=True)`

カスタムノード (Custom nodes)

RegisterSandboxNodeFromSourceRequest を介して新しいノードタイプを作成する場合は、コードを記述する前に、カスタムノード開発の概要、パラメータリファレンス、および実行とライフサイクルガイドを確認してください。これらのページには、サンドボックスクラスが準拠すべきエンジン側の規約が記載されています：

BaseNode のサブクラス化と process / aprocess の契約
Parameter の宣言、モード（mode_allowed_input / ..._property / ..._output）、トレイト
ParameterString / ParameterImage などのヘルパー（手動の Parameter 構築より推奨）
ParameterGroup / ParameterList コンテナ
接続ルールとノードの状態遷移

RegisterSandboxNodeFromSourceRequest は、サンドボックスライブラリディレクトリ内のディスク上に既に存在する Python ソースを登録するだけであり、ファイル自体の書き込みは行いません。エージェントはリクエストを発行する前に、自身のファイルシステムツール（例: write）を使用して <workspace_directory>/<sandbox_library_directory> 配下に .py ファイルを配置する責任があります。インポートされたソースは分離なしでエンジンプロセス内で実行されるため、登録エラーを繰り返すよりも事前に規約に合わせて記述する方が効率的です。単純なワークフロー操作タスク（構築 → 配線 → 実行 → 読み取り）のみであればこれらのガイドは過剰ですので、本スキルの内容のみに従ってください。

実装例: ワンショット俳句パイプライン

目標: 1 行のプロンプトで Agent を実行し、出力を読み取る。

EnsureWorkflowAndFlowRequest()
DescribeNodeTypeRequest(node_type="TextInput") → テキスト出力パラメータは text
DescribeNodeTypeRequest(node_type="Agent") → 入力 prompt、出力 output
DescribeNodeTypeRequest(node_type="DisplayText") → 入力 text
CreateNodeRequest(node_type="TextInput") → 割り当てられた node_name を読み取る
CreateNodeRequest(node_type="Agent") → 割り当てられた node_name を読み取る
CreateNodeRequest(node_type="DisplayText") → 割り当てられた node_name を読み取る
SetParameterValueRequest(node_name="TextInput_1", parameter_name="text", value="雲についての俳句を詠んでください。")
CreateConnectionRequest(TextInput_1.text → Agent_1.prompt)
CreateConnectionRequest(Agent_1.output → DisplayText_1.text)
AutoLayoutFlowRequest() → 3 つのノードを列方向に自動整列
StartFlowRequest(wait_for_completion=True, completion_timeout_ms=60000)
GetParameterValueRequest(node_name="DisplayText_1", parameter_name="text")

合計: 空のエンジンから結果の出力取得まで計 13 回の MCP 呼び出し。

同じパイプラインのバッチ実行版（4 回の往復）

EnsureWorkflowAndFlowRequest()
EventRequestBatch([DescribeNodeTypeRequest × 3])
EventRequestBatch([CreateNodeRequest × 3 (明示的な node_name 付き), SetParameterValueRequest, CreateConnectionRequest × 2, AutoLayoutFlowRequest])
StartFlowRequest(wait_for_completion=True, completion_timeout_ms=60000) に続けて GetParameterValueRequest("DisplayText_1", "text")

ステップ 3 の構築バッチが機能するのは、すべての CreateNodeRequest に明示的な node_name が指定されているためです。後続の SetParameterValueRequest および CreateConnectionRequest スロットは、ノード作成ごとの個別のレスポンスを待つことなく、それらの名前を直接参照できます。

さらに詳しい情報 (Further reading)

本スキルのスコープ（構築 → 配線 → 実行 → 読み取り）を超える内容については、まず /for_agents/ を参照してください。これはエンジンの機械可読ドキュメントへの公式エントリーポイントです — /llms.txt（厳選インデックス）、/llms-full.txt（1 回のフェッチで取得できる全コーパス）、ページごとの .md ファイルの使い分けを解説し、エージェントがエンジンの実際の API を正確に理解するための最重要ページを一覧化しています。