griptape-ai/griptape-nodes/griptape-nodes-workflows

Griptape Nodes Workflow Construction Guide

This skill covers the full cold-start cycle (build → wire → run → read) against the engine's MCP server, plus the idioms and gotchas discovered from running real workflows.

Mental Model

• Workflow: Top-level namespace. Only ONE can be active at a time. Reset with ClearAllObjectStateRequest.
• Flow: The canvas inside a workflow. A workflow has exactly one top-level "canvas" flow. Sub-flows are possible but rarely needed for scratch work.
• Node: A unit of work with parameters (inputs, outputs, properties).
• Connection: An edge between two parameters. Two kinds:
• Data flow: A typed parameter on one node → a typed parameter on another. The engine derives execution order from data dependencies, so data connections alone are usually sufficient.
• Control flow: exec_out → exec_in. Only needed when two nodes must run in a specific order but don't share data (e.g. side-effecting steps, branching). Skip these by default.
• Current Context: A stack (workflow → flow → node). Most requests default to "current" when a name is omitted.

What the MCP server actually exposes

Every MCP tool corresponds 1:1 to a RequestPayload class registered in SUPPORTED_REQUEST_EVENTS (src/griptape_nodes/servers/mcp.py). The server name is prefixed onto each tool, so the request CreateNodeRequest is reachable as griptape_nodes_CreateNodeRequest. A few consequences worth remembering up front:

• There are no plural variants of individual requests. CreateNodesRequest,

CreateConnectionsRequest, etc. do not exist. To create N nodes, send N CreateNodeRequest calls — or wrap them in a single EventRequestBatch call (see below).

• `CreateNodeRequest` does not take parameter values. Setting a parameter is

always a separate SetParameterValueRequest after the node exists. There is no parameter_values / inputs shortcut on create.

• `EventRequestBatch` is the only fan-out primitive. It is a synthetic tool

(no matching RequestPayload class) that ships an ordered list of inner requests in one transport frame. Reach for it whenever you already know the shape of a build phase. See "EventRequestBatch: collapse a build phase into one round trip" below.

Survey the Workspace First

Before building anything, find out what is actually loaded in this engine. The set of registered libraries and the node types they expose is the catalog every later step draws from, so spend the round trips up front instead of guessing names that may not exist (or that exist in a different library than you expect).

Find the workspace directory on disk

The MCP surface does not expose GetConfigValueRequest, so resolve the workspace path by reading the user config file directly. On macOS / Linux it lives at:

~/.config/griptape_nodes/griptape_nodes_config.json

The keys you care about are:

• workspace_directory: absolute (or ~-prefixed) workspace root. The sandbox

library lives inside this directory.

• app_events.on_app_initialization_complete.libraries_to_register: list of locally

registered griptape_nodes_library.json paths. Entries can be either a string or an object {"path": "...", "enabled": true}. Reading these tells you where each library's source lives if you need to look at an existing node's Python module before writing a similar sandbox node.

The sandbox subdirectory key (sandbox_library_directory) is optional and defaults to sandbox_library. The absolute sandbox path is therefore <workspace_directory>/<sandbox_library_directory> (e.g. ~/Projects/.../GriptapeNodes/sandbox_library).

Do this once per session and remember the paths; they don't change mid-run.

Survey the registered libraries via MCP

A. griptape_nodes_ListRegisteredLibrariesRequest()
   → list of library names currently loaded (e.g. "Griptape Nodes Library",
     "Sandbox Library"). If a library you expect is missing, no `DescribeNodeType`
     call against its node types will resolve.
 
B. griptape_nodes_EventRequestBatch with one
   ListNodeTypesInLibraryRequest(library="<name>", include_metadata=true) per library
   → every library's node types in one round trip. `node_types` holds the exact strings
     to pass to `CreateNodeRequest.node_type` and `DescribeNodeTypeRequest.node_type`;
     `node_metadata` maps each to its `category`, `display_name`, `description`, and
     `deprecation`. Skip node types with a `deprecation` when another node does the job.
 
C. (optional) griptape_nodes_ListCategoriesInLibraryRequest(library="<name>")
   → category titles and descriptions, in the order the library declares them.

Do this once per session, then reuse the catalog. Skip the survey only when you already know (from a prior call in the same session) which library provides each node type you intend to use.

EventRequestBatch: collapse a build phase into one round trip

EventRequestBatch (MCP tool name: griptape_nodes_EventRequestBatch) wraps an ordered list of inner requests in a single transport frame. Use it whenever the shape of the build phase is already decided — typical pattern is N CreateNodeRequest

• M SetParameterValueRequest + K CreateConnectionRequest + one

AutoLayoutFlowRequest, all in one round trip.

Shape:

{
  "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
}

Behavior:

• Sequential dispatch. The engine awaits inner requests in submission order

(for inner in batch.requests: await _dispatch_event_request(inner)), so a CreateNodeRequest followed by a SetParameterValueRequest on that same node is safe inside one batch.

• Pre-flight validation. Every inner request is constructed against its

RequestPayload class before anything goes on the wire. An unknown request_type, a request that is not a JSON object, or unknown kwargs in the inner payload all reject the entire batch up front with a TypeError / ValueError.

• Per-slot failure isolation. Once the batch is dispatched, a failure in one

slot does not abort siblings. Failed slots come back as {"ok": false, "details": "..."} in the result array; successful slots come back as the same flattened object a single tool call would return. Walk every slot before assuming the batch succeeded.

• No nesting. EventRequestBatch is intentionally absent from

SUPPORTED_REQUEST_EVENTS and the inner request_type enum, so a batch cannot contain another batch.

• Default timeout scales with size. timeout_ms defaults to

30000 × len(requests) clamped at 300000 ms (5 min). Pass an explicit override when the last slot is StartFlowRequest or any other long-running call; otherwise the synchronous run can eat the budget meant for the rest of the batch. bool is rejected explicitly so True cannot silently become 1ms.

Return shape: a JSON array of trimmed slot responses in submission order. Each slot looks identical to the response that single-tool dispatch would have returned for that request_type.

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

Critical idiom: pre-name nodes you reference later in the same batch

Inside one batch you cannot read CreateNodeResultSuccess.node_name from an earlier slot before composing a later one — every entry is fixed when the batch is submitted. So either:

• Pass an explicit node_name on every CreateNodeRequest and reuse those names

verbatim in later SetParameterValueRequest / CreateConnectionRequest entries, or

• Split the build across two batches: one that creates nodes (read the assigned

names back from the result array), then a second that sets parameters and wires them up.

The one-batch + explicit names path is almost always shorter and is what the batched recipe below uses.

Canonical Cold-Start Recipe

For a typical 3-node linear pipeline (TextInput → Agent → DisplayText), once the workspace survey above has confirmed the relevant library exposes those node types:

1. griptape_nodes_EnsureWorkflowAndFlowRequest()
   → returns workflow_name, flow_name, created_workflow, created_flow.
     Idempotent: if both pieces are already in context, reuses them.
 
2. griptape_nodes_DescribeNodeTypeRequest(node_type="TextInput")
3. griptape_nodes_DescribeNodeTypeRequest(node_type="Agent")
4. griptape_nodes_DescribeNodeTypeRequest(node_type="DisplayText")
   → get exact parameter names/types/modes. Look for:
     - data input(s)  (mode_allowed_input  == true)
     - data output(s) (mode_allowed_output == true)
     - control params (type == "parametercontroltype"): exec_in / exec_out
       are usually skippable (see Mental Model)
 
5. griptape_nodes_CreateNodeRequest(node_type="TextInput")
6. griptape_nodes_CreateNodeRequest(node_type="Agent")
7. griptape_nodes_CreateNodeRequest(node_type="DisplayText")
   → each returns a flat `node_name` (e.g. "TextInput_1", "Agent_1"). Read it from
     the response, do not assume a naming convention. The default name comes from
     `metadata.display_name` and may include spaces (e.g. "Text Input_1"). Pass an
     explicit `node_name` if you want a stable handle.
 
8. griptape_nodes_SetParameterValueRequest(
       node_name="TextInput_1", parameter_name="text", value="...")
   → there is no `parameter_values` shortcut on CreateNode; set every non-default
     parameter with its own SetParameterValue call.
 
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")
    → data connections only; the engine orders execution from data dependencies.
 
11. griptape_nodes_AutoLayoutFlowRequest()
    → required after any multi-node build. Without it, every node lands at (0, 0)
      and the canvas shows them stacked on top of each other. Topologically sorts
      the graph and assigns column-and-row positions. Omit `flow_name` to lay out
      the current-context flow.
 
12. griptape_nodes_StartFlowRequest()
    → omit flow_name; the handler uses the current-context flow.
      Returns once the run ends.
 
13. griptape_nodes_GetParameterValueRequest(node_name="DisplayText_1", parameter_name="text")
    → the terminal node's output.

Thirteen MCP calls: 1 ensure + 3 describe + 3 create + 1 set + 2 connect + 1 layout + 1 run + 1 read. Wider graphs scale linearly: every node adds one CreateNode plus its SetParameterValue calls; every edge adds one CreateConnection.

Batched variant (4 round trips)

The build phase (steps 5-11 above) has fixed shape, so it collapses into one EventRequestBatch call. The describe phase still benefits from being a separate batch because its results inform the build payload, and StartFlowRequest is usually kept out of the build batch so its long timeout does not gate the rest: