Node reference

A graph is built from nodes (units of work) wired together by edges (data flow). Each node takes the output of its predecessors as input, runs, and produces a value that downstream nodes read. This page documents every node type: what it does, the fields you configure, what it emits, and when to use it.

flowchart LR
    In([Input]) --> LLM[LLM]
    LLM --> Cond{Condition}
    Cond -->|true| Tool[Tool]
    Cond -->|false| Out([Output])
    Tool --> Out

Tip

Drag a node from the Studio catalog onto the canvas, connect it, then open the Node config panel to set its fields. Most fields accept {{variable}} references that expand from the context store — {{input}} is the run’s input, and a predecessor’s output is available by its node label. See Edge types for how connections behave.

Flow & I/O

Input

The graph’s entry point. Stores the run’s input in the context store as {{input}}.

• Handles: output only. A graph needs exactly one Input node.
• Use: the starting value every other node can reference.

Output

The graph’s terminal node. Whatever reaches it becomes the run’s final output.

• Handles: input only.
• Use: mark the value you want returned to the chat / experiment / API caller.

Condition

Evaluates its input and routes execution down the matching labeled branch.

• Modes:
  • Regex — match the input (or input_template) against a pattern; emits "true" / "false".
  • JSONPath — read a value at path and compare it against an expected value.
  • LLM judge — ask model to evaluate using your prompt; routes on its answer.
• Handles: one output per branch (e.g. true/false), color-coded. Non-matching branches are transitively skipped.
• Use: branching logic — send “positive” vs “negative”, “needs tool” vs “answer directly”, etc.

Loop

Iterates over a JSON array, re-running a set of body nodes once per item.

• Config: max_iterations (safety cap), until_condition (regex that breaks early), body_node_ids (nodes run each iteration), end_node_ids, flatten (flatten per-iteration results into one array), sample (cap iterations to the first N items).
• Context vars inside the body: {{loop_item}}, {{loop_index}}, {{loop_total}}.
• Body nodes are grouped by topological level, so independent ones run in parallel each iteration.
• Use: “for each row / question / document, do X”.

Human

Pauses the run and prompts the user, then resumes from the saved checkpoint.

• Config: prompt_text shown to the user.
• The frontend shows the prompt with resume / skip controls; state is checkpointed so the run continues exactly where it stopped. See control commands.
• Use: human-in-the-loop approval or input mid-graph.

LLM & tools

LLM

Calls a language model with a prompt template and streams the response.

• Config: model, prompt_template, system_prompt (optional), temperature, max_tokens, output_schema (optional).
• Expands {{var}} in the prompt and system prompt; if the template has no variables, the predecessor’s output is appended automatically. Emits a prompt-preview event, then streams tokens live. If output_schema is set, it uses the provider’s native structured-output API.
• Use: the core generation node — answer, summarize, transform, classify with free-form text.

Structured Output

Gets a schema-valid JSON value, cheaply when possible.

• Config: model, prompt_template, output_schema (required), max_retries.
• Validate-then-fix: first it tries to extract a JSON value matching output_schema straight from the upstream text — without calling the model. Only if that fails does it call model with prompt_template as fix-up instructions, retrying up to max_retries. The template can reference {{input}}, {{schema}}, and {{validation_error}}.
• Handles: exposes a fail handle for error routing.
• Use: when a downstream node needs reliable JSON (e.g. before Eval or a Tool).

Tool

Invokes a named tool or skill from your Library with parameters.

• Config: tool_name, params (JSON; supports {{variable}} expansion).
• Handles: exposes a fail handle.
• Use: call a bundled tool, custom skill, or MCP tool from inside a graph.

Caution

Native in-graph tool dispatch is being rewired onto the new runtime (after the OpenFang removal), so a bare Tool node may currently error until that lands. Agents reach tools reliably through the Agent node and the consult flow today.

VectorDB Query

Semantic search over a vector collection.

• Config: collection, query_template, top_k, threshold.
• Embeds the query (via your embedding model), runs a cosine-similarity search in pgvector, filters by threshold, and returns a JSON array of { title, content, similarity }.
• Use: retrieval-augmented context — fetch the most relevant documents for a question.

Multi-agent coordination

Agent (SubAgent)

Loads an agent definition and runs it as a self-contained loop with its own tools, memory, and skill grants.

• Config: agent_definition_id, input/output field mappers, optional memory_override and comms_override (per-slot — they can only tighten the agent’s own policy).
• Internal type sub_agent; the legacy sub_graph is an alias normalized to this.
• Use: embed a full autonomous agent as one step of a larger graph.

Agent (reference node)

A pure reference to an agent definition — it produces nothing on its own. It exists to be visible on the canvas and to be pointed at by a coordinator via a Membership edge.

• Config: agent_definition_id only.
• Use: declare a member of a Panel or Orchestrator.

Panel

A round-table debate among a roster of agents (members come from Membership edges).

• Config: model (moderator), max_rounds (default 3), moderator_prompt.
• Members share one transcript and speak in turn; the moderator decides when to stop and synthesizes the conclusion. See Panels & Orchestrators.
• Use: deliberation where perspectives should build on each other (e.g. a diagnostic panel).

Orchestrator

Hierarchical delegation: a planner decomposes the task and routes sub-tasks to member agents.

• Config: model (planner), max_delegations (default 10), planning_prompt, adaptive (re-plan from results). Members come from Membership edges.
• Members never see each other; only the planner has the full picture.
• Use: task decomposition across isolated specialists.

Comms (AgentComm)

A direct multi-turn conversation with a single target agent — lighter than a full SubAgent.

• Config: target_agent_id, message_template, conversation_turns (0 = single turn), timeout_secs.
• Use: ask one specific agent something and (optionally) go a few turns back and forth.

Data & transformation

Merge

Combines the outputs of several predecessors into one value.

• Strategies: concatenate (default) → [{ source, content }, …]; json_object → { label: value, … }; first → the first predecessor’s value; zip → zips lists by index, spreading object fields to the top level.
• Use: join parallel branches back together before a final step.

DataFrame

Runs SQL over your predecessors’ data using an in-memory columnar engine (Polars).

• Config: sql_query (predecessors are available as tables named by their labels), output_mode (dataframe handle, materialized json, or preview), preview_rows.
• Use: filter, join, aggregate, and reshape tabular data inside a graph.

Flatten

Reshapes nested arrays/objects into row arrays.

• Modes: array → flatten nested arrays up to depth; explode → expand explode_field (a list) into one row per element; combine_lists → merge several input arrays into one; object_entries → turn object keys into [{ source, content }, …].
• Use: prepare data for a Loop or DataFrame.

Accumulator

Persists and combines values across runs within the same chat (or in-memory in Studio).

• Config: key (storage slot), mode — append (collect into a list), union (merge sets / objects), counter (count).
• Use: running totals, growing lists, or counters that survive across chat turns.

History

Loads the conversation history of the current chat, optionally summarizing older messages.

• Config: max_messages, format (chat or json), roles (which roles to include), summarize + summary_model (condense older turns with an LLM).
• Use: feed prior conversation into a prompt for context-aware replies.

File Read

Loads data from storage, parsing it into structured records.

• Config: path_template ({{var}}-expanded), format (raw, csv, json, lines, xml, trec, folder), delimiter, has_headers, batch (return all records as an array), plus record_tag / title_tag / content_tags for XML/TREC parsing.
• Use: bring external files or datasets into a graph.

File Write

Persists a predecessor’s output to storage.

• Config: path_template, format, delimiter, append (add instead of overwrite), headers (CSV column order).
• Use: export results — CSV rows, raw text, or appended logs.

Evaluation & UI

Eval

Computes evaluation metrics by comparing a prediction against a reference.

• Config: metrics (one or more), prediction_var / reference_var (and optional prediction_column / reference_column for tabular data), top_k, nan_policy (skip_nan, fill_zero, fill_mean).
• Metric families:
  • Text: ROUGE-1, ROUGE-2, ROUGE-L, BLEU, exact match.
  • Semantic: cosine similarity (embedding-based).
  • Retrieval: precision@k, recall@k, NDCG, MRR.
  • Classification: F1, precision, recall, accuracy.
  • Correlation: Pearson, Spearman, Kendall.
  • Regression: MAE, RMSE, R².
• The computed scores surface on the trial — this is the node that makes a graph measurable in Experiments.
• Use: score model output against ground truth in a sweep.

Dashboard

A pass-through that tags its data for display in the chat dashboard panel.

• Config: tab_name, view_type (table, chart, echarts, json, text), vega_spec / echarts_spec for charts.
• The widget state persists across chat turns. See binding a graph to a chat.
• Use: surface tables and charts interactively when a graph powers a chat.

Note

The Studio catalog is generated from the live node schema, so newly added node types appear automatically. The canonical definitions live in backend/src/graph/schema.rs (NodeConfig) and backend/src/graph/nodes/.