flow-nodes

Flow Node Reference

Use manage_flow_nodes to add logic nodes inside tool branches only. Nodes are helpers for tools — they must ALWAYS be created under a tool, never as standalone pre-agent nodes.

CRITICAL: NEVER add nodes before the AI Agent Job node. Pre-agent nodes cause conversation loops and break the agent's ability to orchestrate. ALL logic — including authentication, data collection, greetings, and conditional behavior — must be implemented as agent tools.

Voice exception — Set Session Config: The one node that should run before the AI Agent node is a setSessionConfig (Set Session Config) node, and only in voice flows. It applies per-session speech settings (barge-in, ASR, STT/TTS, input timeouts) and must be the first node. The audit_voice_agent tool checks for this and can create it by prepending before the AI Agent node. Do not add any other pre-agent nodes.

LLM Prompt exception: llmPrompt (llmPromptV2) is a top-level raw LLM node for flows with no AI Agent node. Create it only when the user asks for an LLM Prompt node by name; otherwise use the AI Agent default. Reading or updating existing llmPromptV2 nodes is fine. See the LLM Prompt section.

Quick Start (tool-first workflow)

1. Create a tool — create_tool { aiAgentId, toolType: 'tool', name: 'Process Order', config: { toolId: 'process_order', description: 'Process a customer order' } } → returns toolNodeId
2. Get the flowId — from create_ai_agent response, or list_resources { resourceType: 'flow', projectId }
3. Add a node inside the tool — manage_flow_nodes { operation: 'create', flowId, parentNodeId: '<toolNodeId>', mode: 'appendChild', nodeType: 'code', label: 'Validate Order', config: { code: '...' } }
4. Add more nodes — manage_flow_nodes { operation: 'create', flowId, parentNodeId: '<previousNodeId>', mode: 'append', nodeType: 'say', label: 'Confirm', config: { text: 'Order processed!' } }
5. List all nodes — manage_flow_nodes { operation: 'list', flowId } (id, type, label, parentId, isDisabled when true — no config)
   Read one node with its config before editing — manage_flow_nodes { operation: 'get', flowId, nodeId: '<id>' }
6. Update a node — manage_flow_nodes { operation: 'update', flowId, nodeId: '<id>', config: { text: 'Updated!' } }
7. Delete a node — manage_flow_nodes { operation: 'delete', flowId, nodeId: '<id>' }