Skip to content

Developing Nodes

This section provides comprehensive documentation for developers building custom nodes for Griptape Nodes.

For AI Assistants & Coding Agents

All documentation in this section is available as post-processed markdown for AI coding assistants. The site exposes a full machine-readable surface; see For Agents for the index.

Usage: Point your AI assistant to these URLs with instructions like: "Read this node development guide: [URL] and help me build a custom node"

Introduction

Griptape Nodes are modular workflow components that enable users to build complex AI workflows through visual programming. This section covers both fundamental concepts and advanced patterns for creating robust, user-friendly nodes.

If you're new to developing nodes, start with the Getting Started Guide. It provides a beginner-friendly introduction to the node development ecosystem and walks you through building your first node.

Nodes inherit from BaseNode subclasses:

  • DataNode: For data processing tasks
  • ControlNode: For flow control with exec_in/out
  • StartNode: For workflow initialization
  • EndNode: For workflow termination

Core Concepts

Base Classes

  • DataNode: Processes data without execution flow control. Use for nodes that transform or pass through data synchronously — they process immediately when their inputs are satisfied.
  • ControlNode: Manages execution flow with exec_in/exec_out connections. Use for nodes that make external API calls or perform long-running operations — override async def aprocess() for async work, or yield blocking work to a background thread with AsyncResult. If your node calls an API and polls for results, it must be a ControlNode.
  • StartNode: Entry points for workflows
  • EndNode: Terminal points for workflows

Parameters

Define inputs, outputs, and properties via the Parameter class. Parameters support:

  • Type validation
  • UI customization
  • Connection constraints
  • Default values
  • Traits (Options, Slider, Button, ColorPicker)

See Parameters for the full reference.

Process Method

The process() method contains core logic. Set outputs in self.parameter_output_values. For asynchronous work, override async def aprocess() instead — see Execution and Lifecycle.

Node States

  • UNRESOLVED: Initial state
  • RESOLVING: Currently processing
  • RESOLVED: Processing complete

Connections

Managed via lifecycle callbacks for validation and handling. See Execution and Lifecycle.

Events

Use on_griptape_event for reacting to workflow events.

Setting Up

  1. Install griptape-nodes
  2. Use virtual environments for isolation
  3. Structure projects with simple folder hierarchies
  4. Import from griptape_nodes.exe_types.* and 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

The fastest way to a production-ready node library is the official template repository:

Griptape Nodes Library Template (readme)

It provides the necessary boilerplate, testing framework, and documentation patterns. The workflow:

  1. Use the template repository - Create your own repository from the GitHub template
  2. Set up your environment - Clone the repo to your Griptape Nodes workspace directory
  3. Configure your library - Rename directories and update package information in pyproject.toml
  4. Create your nodes - Define node classes (either ControlNode or DataNode) with appropriate parameters
  5. Implement your logic - Code the required process() method and any additional functionality
  6. Configure library metadata - Set up your library.json file with nodes and category information
  7. Register with the engine - Add your library to Griptape Nodes through the settings interface
  8. Test and use - Create flows using your custom nodes in the Griptape Nodes interface

To understand how to design your nodes, explore the patterns used in the standard library: node reference.