AI-Powered Workflow Builder (EE)
Relevant source files
The following files were used as context for generating this wiki page:
- AGENTS.md
- CONTRIBUTING.md
- packages/@n8n/ai-workflow-builder.ee/evaluations/chains/test-case-generator.ts
- packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-transformation.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/document-processing.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/enrichment.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/knowledge-base.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/utils/test/markdown-workflow.utils.test.ts
- packages/frontend/editor-ui/src/app/constants/workflowSuggestions.ts
- packages/frontend/editor-ui/src/features/workflows/readyToRun/workflows/aiWorkflow.ts
- packages/nodes-base/nodes/Set/Set.node.json
- packages/testing/playwright/AI-TEST-CHEAT-SHEET.md
- packages/testing/playwright/CONTRIBUTING.md
- packages/testing/playwright/tests/ui/29-templates.spec.ts
- packages/testing/playwright/tests/ui/55-workflow-builder.spec.ts
The AI-Powered Workflow Builder is an enterprise feature that enables users to generate n8n workflows from natural language prompts. It utilizes a sophisticated AI agent that interprets user requests, selects appropriate nodes, and constructs a complete, connected, and configured workflow. This system is designed to accelerate development, enforce best practices, and lower the barrier to entry for creating complex automations.
The builder is accessible from an empty workflow canvas via a "Build with AI" button, which opens a chat-based interface. Users can type a prompt or select from a list of predefined suggestions to initiate the build process.
Sources: packages/testing/playwright/tests/ui/55-workflow-builder.spec.ts:40-43, packages/frontend/editor-ui/src/app/constants/workflowSuggestions.ts, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:101-104
Core Architecture
The AI Builder is orchestrated by a main AI agent that follows a structured, multi-phase process to translate a prompt into a functional workflow. A core principle of its design is the heavy use of parallel execution for tool calls (e.g., adding nodes, configuring parameters) to ensure efficiency.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:105-112
Phased Execution Model
The agent follows a strict sequence of phases to ensure robust and reliable workflow creation. Each phase has a distinct purpose, from understanding the initial request to validating the final result.
This diagram illustrates the sequential and parallel phases of the workflow creation process.
The phases are defined as follows:
| Phase | Description | Mandatory | Execution |
|---|---|---|---|
| Categorization | Categorizes the prompt and searches for best practices documentation based on identified techniques. | Yes | Sequential |
| Examples | Searches for existing workflow examples using relevant search terms. | No | Parallel |
| Discovery | Searches for all required node types simultaneously. | No | Parallel |
| Analysis | Retrieves detailed information (inputs/outputs) for all discovered nodes. | No | Parallel |
| Creation | Adds all required nodes to the canvas, executing add_nodes calls in parallel. | No | Parallel |
| Connection | Connects the nodes based on the analyzed input/output structure. | No | Parallel |
| Configuration | Configures parameters for all nodes using update_node_parameters. | Yes | Parallel |
| Validation | Runs validate_workflow to check for structural issues and resolves any violations. | Yes | Sequential |
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:25-99
Best Practices Enforcement
A critical function of the AI Builder is to enforce n8n's established best practices. During the Categorization phase, the agent identifies the workflow techniques required by the prompt and retrieves corresponding best practice documents. These documents contain critical requirements, recommended nodes, and common pitfalls. The agent is mandated to follow these guidelines, even if the user's prompt does not explicitly mention them. This ensures that the generated workflows are robust, efficient, and less prone to common errors.
For example, when building a data_analysis workflow, the agent will consult data-analysis.ts and may automatically include a Split In Batches node for large datasets, as this is a documented best practice to prevent memory issues.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:140-151, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts:16-18, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts:18-20
Workflow Creation Lifecycle
The interaction between the user and the AI builder follows a clear sequence of events, from the initial prompt to the final, ready-to-use workflow on the canvas.
This diagram shows the user interaction and the internal agent process for building a workflow.
1. Starting a Build Session
A user initiates a build session by clicking the Build with AI button on an empty workflow canvas. This action opens the AI Assistant sidebar, which presents a chat input and a list of workflow suggestions.
Sources: packages/testing/playwright/tests/ui/55-workflow-builder.spec.ts:40-43
2. Workflow Suggestions
To help users get started, the UI displays a set of predefined WorkflowSuggestion pills. These provide ready-made prompts for common use cases. Clicking a pill populates the chat input with the full prompt, which the user can then submit.
| Summary | ID |
|---|---|
| Multi-agent research workflow | multi-agent-research |
| Summarize emails with AI | email-summary |
| Daily AI news digest | ai-news-digest |
| Daily weather report | daily-weather-report |
| Invoice processing pipeline | invoice-pipeline |
| RAG knowledge assistant | rag-assistant |
| Lead qualification and call scheduling | lead-qualification |
| YouTube video chapters | youtube-auto-chapters |
Sources: packages/frontend/editor-ui/src/app/constants/workflowSuggestions.ts:5-87, packages/testing/playwright/tests/ui/55-workflow-builder.spec.ts:47-49
3. Prompt Categorization and Techniques
Once a prompt is submitted, the agent's first step is to categorize it into one or more WorkflowTechniques. This classification determines which best practice documents to consult.
The system is trained on a variety of prompts to identify the correct techniques.
| Example Prompt | Expected Techniques |
|---|---|
| "Get top 10 volatile stocks...analyze them...send a text message" | scraping_and_research, data_analysis, notification |
| "I need a workflow that takes a google doc and identifies the bolded Headings and copies those into a google sheet" | document_processing, data_extraction |
| "Access the sources: ERP, internal web, and PDF contract repository. Normalize the content of each contract (use OCR if necessary). Classify each contract by type..." | document_processing, data_extraction, data_transformation, triage |
| "Build a 'Reply Triage' workflow that triggers on inbound emails and routes them using AI" | triage |
| "i want to automate a mechanism that receives different news from telegram channels and checks if the news are about lebanon, if yes translate the news to arabic and send them to a telegram channel of my own" | data_transformation, notification, monitoring, triage |
Sources: packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json
4. Node Configuration
The Configuration Phase is a mandatory and critical step. The agent is explicitly instructed to NEVER rely on default parameter values, as they are a common source of runtime failures. It uses the update_node_parameters tool to configure every node that processes data.
AI Node Configuration (System vs. User Messages)
For AI nodes (like AI Agent), the agent MUST separate static instructions from dynamic data:
- System Message: Contains the AI's role, capabilities, and behavioral instructions.
- User Message/Text: Contains dynamic data from the workflow, such as expressions like
{{ $json.field }}.
This separation ensures consistent AI behavior while allowing for dynamic context.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:311-399
Tool Node Configuration ($fromAI Expressions)
For "Tool" nodes (e.g., gmailTool, googleCalendarTool), the agent uses a special {{ $fromAI('key') }} expression. This allows the parent AI agent to dynamically fill in parameters like email recipients, subjects, or date ranges at runtime based on the conversation's context.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:442-480
Workflow Configuration Node
The agent is instructed to always include a Workflow Configuration node (n8n-nodes-base.set) at the start of every workflow, immediately after the trigger. This node acts as a centralized place for workflow-wide settings (like URLs or thresholds), which other nodes can then reference using expressions. This practice makes workflows more maintainable.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:265-308, packages/nodes-base/nodes/Set/Set.node.json
Testing and Evaluation
The AI Workflow Builder is tested using a combination of end-to-end UI tests with Playwright and evaluation frameworks.
- UI Testing: Playwright tests simulate user interactions, such as clicking the "Build with AI" button, selecting a prompt, and verifying that nodes are generated on the canvas. These tests use a proxy server to mock API calls to AI providers like Anthropic.
Sources: packages/testing/playwright/tests/ui/55-workflow-builder.spec.ts, packages/testing/playwright/CONTRIBUTING.md:29-35 - Test Case Generation: An automated
test-case-generatorchain is used to create a diverse set of evaluation prompts, covering simple, medium, and complex scenarios across various domains.
Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/chains/test-case-generator.ts:32-62 - Reference Workflows: Some test cases are associated with a reference workflow (a ground-truth JSON file) to evaluate the accuracy of the generated workflow.
Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/chains/test-case-generator.ts:10-13, 103-106
Appendix: Workflow Visualization
The system includes utilities to represent workflows in text format, such as Mermaid diagrams. The mermaidStringify function can convert a workflow's JSON definition into a flowchart TD diagram, including node types, names, and connections. This is useful for debugging, documentation, and providing context to the AI.
Below is an example of a Mermaid diagram generated from a workflow, showing main data connections (-->) and AI-specific connections like -.ai_tool.->.