Graph nodes and validation reference
Choose supported graph nodes and keep version 1 graph definitions within validation limits.
Use this reference to choose a supported node type and check a version 1 Agent graph before previewing it. It covers the graph shape, node-specific data, field limits, and structural errors accepted by the public validator.
Graph structure
Every graph is a directed collection of nodes and edges. A valid definition uses version: 1, contains at least one node, includes both terminal types, and points every edge at existing node IDs.
The diagram shows the required terminal boundary and an optional branch. The schema verifies that START and END exist and that edge endpoints exist; it does not, by itself, prove that every node is reachable or that every path reaches END.
| Property | Type | Requirement |
|---|---|---|
version | literal number | Must be 1. |
nodes | array | Must contain at least one node, including a start and an end. |
edges | array | May be empty at schema level; every source and target must match a node id. |
Node id | string | 1–100 characters. |
Node position.x, position.y | finite number | Both coordinates are required. |
Node data.label | string | Required; 1–120 characters. |
Edge id | string | 1–100 characters. |
Edge source, target | string | 1–100 characters and must reference existing nodes. |
Edge label | string | Optional; at most 120 characters. |
Supported node types
Choose only the following type identifiers. Unsupported identifiers cause schema validation to fail.
| Type | Use | Relevant data |
|---|---|---|
start | Mark the entry terminal. | label |
end | Mark the exit terminal. | label |
agent | Run an agent prompt with optional tools. | prompt, allowedTools |
supervisor | Coordinate or route work with a prompt. | prompt |
tool | Call a named tool action. | toolName, action, inputTemplate |
router | Select a deterministic or AI route. | routerMode, condition, routerPrompt |
approval | Pause for a decision or escalation. | approvalReason, autoApproveCondition, escalateAfterMin |
loop | Repeat bounded work. | maxIterations |
parallel | Map or reduce parallel work. | parallelMode, mapField |
subgraph | Embed another graph and map its data. | subgraph, inputMapping, outputMapping |
mcp_server | Refer to an MCP server connection. | mcpServerId, mcpTransport, mcpEndpoint |
mcp_tool | Call a tool exposed by an MCP server. | mcpToolName, mcpToolServer, mcpToolParams |
skill | Invoke another skill. | skillId, skillInput |
http | Make an HTTP request. | httpMethod, httpUrl, httpHeaders, httpBody, httpResponseType, httpTimeoutMs |
transform | Transform prior data. | transformOp, transformExpr |
delay | Represent a nonnegative delay. | delayMs, delayTemplate |
aggregate | Combine values. | aggregateMode, aggregateExpr |
variable | Read or modify a named value. | varName, varOp, varValue |
output | Shape graph output. | outputTemplate, outputFields |
sticky_note | Add canvas-only notes. | noteContent, noteColor |
frame | Group nodes visually. | frameTitle, frameOpacity, containedNodeIds |
Field limits
The following limits are the ones most likely to affect graph authoring. Lengths are maximum character counts unless stated otherwise.
| Field | Limit or allowed value |
|---|---|
description | 1,000 |
prompt, noteContent | 10,000 |
allowedTools | Up to 50 nonempty strings |
condition, autoApproveCondition, mcpEndpoint | 1,000 |
routerPrompt, transformExpr, aggregateExpr, outputTemplate | 4,000 |
approvalReason | 2,000 |
escalateAfterMin | Integer from 1 through 10,080 |
maxIterations | Integer from 1 through 100 |
routerMode | deterministic or ai |
parallelMode | map or reduce |
mcpTransport | STDIO or SSE |
httpMethod | GET, POST, PUT, PATCH, or DELETE |
httpResponseType | json, text, or blob |
httpUrl | 2,000 |
httpTimeoutMs | Positive integer |
delayMs | Nonnegative integer |
frameOpacity | Number from 0 through 1 |
Validation failures
Use the error text to identify the structural correction:
| Error | Correction |
|---|---|
Graph must contain at least one node | Add a node. |
Graph must contain a START node | Add a node with type: "start". |
Graph must contain an END node | Add a node with type: "end". |
Edges must reference existing node ids | Change every edge endpoint to an existing node ID or remove the stale edge. |
The visual graph is incomplete — add a START node, an END node, and valid connections. | Restore the terminal nodes and connect the visual graph before starting a preview. |
For a practical check of structure and runtime input, preview and debug the graph. To construct a graph from scratch, create an agent graph.