---
title: "Node flows"
description: "Graph-based call flows: build, validate, simulate, publish and inspect runs."
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.trillet.ai/llms.txt). Append `.md` to any page URL for its markdown version.

{/* Generated by packages/mcp/scripts/gen-tool-reference.mjs from @trillet-ai/mcp v0.10.0. Do not edit by hand. */}

Graph-based call flows: build, validate, simulate, publish and inspect runs. 10 tools.

## `trillet_node_flow_reference`

**Node flow reference**

Return the complete reference for Trillet node flows (graph call flows): node types and their config fields, edge kinds and handle rules, condition syntax, validation errors, and lifecycle gotchas. READ THIS FIRST before creating or editing any node graph.

Flags: `read-only`

### Parameters

None.

## `trillet_list_node_flows`

**List node flows**

List node-graph call flows in the workspace (summaries; graphs excluded).

Flags: `read-only` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | number | no | Default: `1`. |
| `limit` | number | no | Default: `20`. |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result, where it is a bare array):

| Field | Type | Description |
| --- | --- | --- |
| `nodeFlows` | object[] |  |

## `trillet_get_node_flow`

**Get node flow**

Fetch a node flow: the graph (nodes, edges, variables, globals, router), plus the companion pathway (its id is what the call-flow settings tools operate on).

Flags: `read-only` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `graph_id` | string | yes |  |
| `full_graph` | boolean | no | true returns complete nodes/edges configs; false returns a summary Default: `false`. |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result):

| Field | Type | Description |
| --- | --- | --- |
| `graph` | any |  |
| `pathway` | object |  |

## `trillet_create_node_flow`

**Create node flow**

Create a new node-graph call flow. This ALSO auto-creates a companion agent and pathway. Optionally start from a platform template (see trillet_list_node_flow_templates). After creating: update the graph, validate, then PUBLISH (calls fail with NODE_FLOW_NOT_PUBLISHED until published).

Flags: `writes` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `description` | string | no |  |
| `template` | string | no | Template key from the templates list |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result):

| Field | Type | Description |
| --- | --- | --- |
| `created` | object |  |
| `pathwayId` | string |  |

## `trillet_list_node_flow_templates`

**List node flow templates**

List available node-flow starter templates.

Flags: `read-only` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result, where it is a bare array):

| Field | Type | Description |
| --- | --- | --- |
| `templates` | any[] |  |

## `trillet_update_node_graph`

**Update node graph**

Update graph fields: name, description, startNodeId, variables, globals, router, nodes, edges. Arrays replace wholesale, so send complete nodes/edges lists. IMPORTANT: updates are saved WITHOUT validation, and live calls keep running the previously PUBLISHED version. Always trillet_validate_node_graph then trillet_publish_node_graph afterwards. Consult trillet_node_flow_reference for node/edge schemas before building.

Flags: `writes` `destructive` `structured output`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `graph_id` | string | yes |  |
| `update` | object (map) | yes | Any of: name, description, startNodeId, variables, globals, router, nodes, edges |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result):

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `name` | string |  |
| `status` | string |  |
| `startNodeId` | string |  |
| `nodes` | string[] |  |
| `edges` | number |  |
| `variables` | string[] |  |
| `interrupts` | string[] |  |
| `hasDraft` | boolean |  |
| `publishedVersion` | any |  |
| `publishedAt` | string |  |

## `trillet_validate_node_graph`

**Validate node graph**

Validate the saved graph (or a proposed unsaved graph passed inline). Returns problems with severity: 'error' blocks publish, 'warning' does not. Problem codes are documented in trillet_node_flow_reference.

Flags: `read-only`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `graph_id` | string | yes |  |
| `graph` | object (map) | no | Optional full graph object to validate without saving |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_publish_node_graph`

**Publish node graph**

Publish the graph: validates (400 NODE_GRAPH_INVALID with problems if blocking errors), snapshots a version, compiles, deploys any code nodes to Cloudflare, and makes it live for calls. This is the ONLY way edits reach live calls.

Flags: `writes` `destructive` `asks for confirmation` `structured output`

Clients that support MCP elicitation show a confirmation form before this tool runs; declining cancels it with no changes. Other clients rely on their own approval prompt.

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `graph_id` | string | yes |  |
| `note` | string | no | Version note |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

### Structured output

Returned as `structuredContent` (fields are optional; the same data is in the text result):

| Field | Type | Description |
| --- | --- | --- |
| `published` | object |  |
| `warnings` | any[] |  |

## `trillet_simulate_node_graph`

**Simulate node graph**

Run a text simulation of the graph without a live call: pass caller turns and optional initial variable state; returns the traversal trace. Verifies STRUCTURE (edges wire up, conditions evaluate, handles resolve, guards fire) - it does NOT verify routing quality, because the router is mocked and intent edges are not judged by a model. To test real routing/extraction conversationally, use trillet_start_text_call (runs the live runtime).

Flags: `read-only`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `graph_id` | string | yes |  |
| `turns` | string[] | yes | Caller utterances in order |
| `initial_state` | object (map) | no |  |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |

## `trillet_list_node_flow_runs`

**List node flow runs**

List recent runs (call traversals) of a node graph: path taken, disposition, counters. Use for debugging why calls routed the way they did.

Flags: `read-only`

### Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `graph_id` | string | yes |  |
| `run_id` | string | no | Fetch one run with full trace events |
| `workspace_id` | string | no | Run this call in another workspace: its id or its name (see trillet_list_workspaces). Omit to use the default (TRILLET_WORKSPACE_ID, the workspace picked when the connector was approved, or the one set with trillet_switch_workspace). |