Nodetool Workflow Builder

Build NodeTool workflows

Create or edit a workflow that produces the requested outputs from the specified inputs. Preserve existing nodes and connections outside the requested change.

A graph is one surface among several

NodeTool holds several document kinds, and most of them are not graphs. Build a graph when the user asked for one, when the job has to re-run on new inputs, or when the result must be callable over the API. Otherwise route the request.

A workflow can still be the right answer alongside one of these: a mini app runs workflows, and a timeline clip can be produced by one.

Use the authoring surface the user requested. Prefer available UI tools for a visible canvas, headless workflow tools for saved graphs, and JSON or the TypeScript DSL when a workflow file is requested. Do not claim a missing tool is callable. Use the live schemas and registry as the source of identifiers.

Build and verify

1. Inspect the existing graph for edits. Identify required inputs, outputs, and behavior from the request and existing context.
2. Search required node types with include_properties=true and include_outputs=true. Reuse metadata already retrieved for the same type. Discover model choices through available model-search tools. Do not invent node types, properties, handles, or model identifiers.
3. Add or update nodes, set required properties, and connect compatible handles. Keep existing layout and identifiers when editing. Read Graph authoring reference below for the relevant tool, streaming pattern, or DSL operation before using it.
4. Validate through ui_get_graph or validate_workflow as appropriate. Fix errors and required-input warnings. Read back the saved graph before claiming it was created or changed. Report any remaining limitation.
5. Execute only when the request includes a run. Respect generation budgets and tool permissions. Report the workflow identifier, inputs, validation result, and actual run outcome when executed.

If a node is unavailable, broaden the search and inspect supported alternatives. Proceed with an equivalent composition when it preserves the requested behavior. Otherwise explain the missing capability and ask only for the decision needed to choose an alternative. Continue independent work on the rest of the graph.

Graph authoring reference

Read only the sections needed for the current operation. Live registry metadata and tool schemas are authoritative. Catalog entries and DSL examples are search leads, not proof that a node or argument exists in this installation.

Tool Reference

Set a node's sync_mode through ui_update_node_data (data.sync_mode) — there is no dedicated sync-mode tool.

Node Data Fields

When using ui_add_node or ui_graph, the data object supports:

• properties — node-specific input values (from metadata)
• dynamic_outputs — tool outputs for Agent nodes: {"tool_name": {"type": "str"}}
• dynamic_properties — runtime-configurable properties (usually {})
• sync_mode — "on_any" (default, fire on any input) or "on_all" (wait for all inputs)

Node Catalog

Core Namespaces

Library Namespaces (lib.*)

lib.pdf (rasterize pages to images), lib.sqlite (database path), lib.browser (screenshots), lib.svg (vector graphics), lib.charts (charts)

Note: lib.http, lib.os, lib.datetime, lib.json, lib.math, lib.uuid, nodetool.boolean, nodetool.dictionary, nodetool.list, nodetool.numbers, nodetool.text.Chunk, and all skills.* nodes have been removed. Use the Code node (nodetool.code.Code) and its snippet library instead. Its sandbox provides fetch for web requests, workspace.* for files, and @nodetool-ai/sandbox-dates (date-fns) for date logic. nodetool.control.RepeatCount and nodetool.control.RepeatValue cover repetition.

External Service Namespaces

Data Types

• Primitives: str, int, float, bool, list, dict, any
• Assets: {type: "image|audio|video|document", uri: "..."}
• Models: language_model, image_model, video_model, embedding_model, tts_model

Edges enforce type compatibility. Use any type for flexible connections.

Search Strategy

• Use broad category terms with limit=20 to see all options.
• Multi-word queries are split and scored independently — "dataframe group aggregate" finds multiple related nodes.
• Use input_type / output_type filters: "str", "int", "float", "image", "audio", "list", etc.
• If no results, broaden the query or try the namespace prefix (e.g., "nodetool.text").
• Type conversions: dataframe→array via "to_numpy", list→item via iterator, item→list via collector.

Workflow Patterns

Pattern 1: Simple Pipeline

Shape: Input → Transform(s) → Output Use for: Single-source processing, data conversion, image enhancement. Example: ImageInput → Sharpen → AutoContrast → Output

Pattern 2: Agent-Driven Generation

Shape: Input → Agent → Post-process → Output Use for: Creative generation, multimodal transforms (image→text→audio), semantic understanding. Key nodes: Agent (general LLM), Summarizer (text summarization), ListGenerator (streams items)

Pattern 3: Streaming with Previews

Shape: Inputs → Agent (strategy) → ListGenerator → Processing → Preview nodes at each stage Use for: Complex multi-stage generation where user needs progress visibility. Key concept: Add Preview nodes at intermediate stages for debugging and monitoring.

Pattern 4: RAG (Retrieval-Augmented Generation)

Shape: ChatInput → vector.HybridSearch + FormatText → Agent → Output Use for: Question-answering over documents, factual accuracy from specific sources. Index flow: nodetool.code.Code (workspace.list) → LoadDocumentFile → nodetool.code.Code ("Chunk Text" snippet) → vector.IndexTextChunk Query flow: ChatInput → vector.HybridSearch → FormatText → Agent → Output Note: RAG nodes are the single vector.* namespace (e.g. vector.QueryText, vector.HybridSearch, vector.IndexTextChunk); there is no vector.chroma.*/vector.faiss.*.

Pattern 5: Database Persistence

Shape: Input → FormatText → DataGenerator → Insert → Query → Preview Use for: Persistent storage, apps with memory, agent history. Key nodes: CreateTable, Insert, Query, Update, Delete (lib.sqlite namespace)

Pattern 6: Email & Web Integration

Shape: GmailSearch → EmailFields → Summarizer → Preview Use for: Email processing, RSS monitoring, web content extraction. Key nodes: GmailSearch, EmailFields, FetchRSSFeed, GetRequest

Pattern 7: Realtime Processing

Shape: RealtimeAudioInput → RealtimeAgent → Preview Use for: Voice interfaces, live transcription, interactive audio. Key nodes: RealtimeAudioInput, RealtimeAgent, LiveAgent, RealtimeWhisper LiveAgent runs GPT-Live: full-duplex speech with a Responses backend for lookups and web search. Feed it 24 kHz PCM16 microphone chunks.