AI Workflow Builder & Evaluations

Relevant source files

The following files were used as context for generating this wiki page:

• packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
• packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
• packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
• packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json

The AI Workflow Builder is a specialized system within n8n that automates the generation of executable workflows from natural language prompts. It uses an agentic architecture to analyze user requirements, discover appropriate nodes, and generate JavaScript code using the n8n Workflow SDK.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:31-36, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:107-111

Core Architecture and Agents

The system operates through specialized agents that handle different stages of the workflow creation process. These agents use tools to interact with the n8n ecosystem and ensure technical accuracy.

Discovery Agent

The Discovery Agent identifies the necessary n8n nodes and connection-changing parameters based on the user's request. It categorizes the prompt into specific workflow techniques to retrieve relevant best practices.

• Node Identification: Searches for nodes by keyword and retrieves exact version numbers and properties.
• Technique Categorization: Assigns categories like chatbot, scheduling, or data_extraction to guide node selection.
• Clarifying Questions: Asks the user for missing information when the intent is underspecified.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:33-35, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:182-190

Code Builder Agent

The Code Builder Agent generates complete, executable JavaScript code using the n8n Workflow SDK. It follows a mandatory multi-step process to ensure the generated graph is valid.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:31-36

The diagram shows the mandatory sequential process followed by the Code Builder Agent to transform a request into a validated workflow. Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:365-420

Workflow Techniques

The system utilizes a set of predefined techniques to categorize user prompts and retrieve specific design guidance.

Technique	Description
chatbot	Receiving chat messages and replying (e.g., Telegram, Slack).
scheduling	Running actions at specific times or intervals.
data_extraction	Pulling specific information from structured or unstructured inputs.
content_generation	Creating text, images, audio, or video using AI models.
triage	Classifying data for routing, prioritization, or qualification.
document_processing	Taking action on content within files (PDFs, images, CSVs).
scraping_and_research	Collecting current/live information from external sources.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:313-325, packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json:1-10

Code Generation and SDK Usage

The system generates code specifically for the n8n Workflow SDK. It uses expr() for expressions and placeholder() for missing values that require user input.

SDK Implementation Rules

• Unique Variable Names: Variable names must not conflict with builder function names like node or trigger.
• Node Connections: Uses .to() to chain nodes and .input(n) to target specific inputs on multi-input nodes like Merge.
• Sample Data: Every node must include an output property with sample data to enable downstream expression validation.
• Credentials: Uses newCredential('Type') to reference credentials required by specific nodes.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:466-501

Parallel Execution Pattern

This diagram illustrates how parallel branches are combined using the Merge node's indexed inputs in the SDK. Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:167-184

AI Node Design Patterns

The builder applies specific logic when constructing AI-centric workflows, prioritizing the AI Agent node for reasoning tasks.

• Multi-Agent Systems: Implemented using AI Agent Tool nodes connected to a main AI Agent. Each sub-agent requires its own Chat Model.
• Tool Usage: Tools (e.g., SerpAPI Tool, Calculator Tool) connect to the AI Agent via the ai_tool connection type.
• Structured Output: The Structured Output Parser is preferred for extracting specific fields into JSON instead of using manual Code nodes.
• Memory: Chatbot agents must include a memory sub-node (e.g., Window Buffer Memory) to maintain context.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:50-68, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:192-205

Evaluations and Validation

The system includes a validation phase to ensure generated workflows are technically sound before they are presented to the user.

1. Node Type Definitions: The builder calls get_node_types with exact discriminators (resource/operation) to fetch parameter schemas.
2. Schema Validation: Ensures all mandatory parameters are present and data types match the node requirements.
3. Graph Integrity: Validates that all connections are possible given the node types and versions used.
4. Error Correction: If validate_workflow reports issues, the agent uses batch_str_replace to apply fixes atomically.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:438-460, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:505-515, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:121-131

Best Practices for Data Analysis

Workflows involving data analysis follow a structured Input → Transform → Output pattern.

• Cardinality Control: If a node returns multiple items, downstream nodes run once per item. The system uses executeOnce: true or Merge nodes to manage item multiplication.
• Batching: For large datasets, the Split In Batches node is used to prevent memory exhaustion.
• Native Preference: Native nodes (e.g., Filter, Aggregate, Sort) are always preferred over the Code node for performance and readability.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts:7-25, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:98-110