/mrge-io/eval-n8n

Wiki directory

Browse AI-generated documentation for any repository.

AI Workflow Builder

Relevant source files

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

The AI Workflow Builder is a feature that enables users to create and modify n8n workflows using natural language prompts. It leverages an AI agent that interprets user requests and utilizes a specialized set of tools to programmatically construct or edit a workflow's JSON definition. This system is designed to simplify the workflow creation process, especially for complex or unfamiliar tasks, by translating high-level descriptions into functional n8n workflows.

The primary user interface for this feature on an empty canvas is the CanvasNodeAIPrompt.vue component, which provides a prompt input, suggestions, and an option to build manually.

Sources: packages/frontend/editor-ui/src/components/canvas/elements/nodes/render-types/CanvasNodeAIPrompt.vue, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts

Architecture

The AI Workflow Builder operates through a client-server architecture where the frontend captures user prompts and the backend orchestrates the AI agent to generate the workflow.

The following diagram illustrates the high-level data flow from user input to workflow generation.

Generating architecture diagram...

Sources: packages/frontend/editor-ui/src/components/canvas/elements/nodes/render-types/CanvasNodeAIPrompt.vue, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts

Frontend Interaction

The user journey begins on the n8n canvas. The CanvasNodeAIPrompt.vue component is displayed on an empty canvas, providing the main interface for the AI builder.

Key UI elements and their functions:

Prompt Input: A text area for users to describe the workflow they want to build.
Suggestion Pills: A set of predefined prompts for common use cases, like "Invoice processing pipeline" or "Daily AI news digest". Clicking a pill populates the prompt input.
Manual Add Button: An alternative for users who prefer to add a trigger node manually, which opens the standard node creator.

When a user submits a prompt, the component sends a request to the backend, which then initiates the AI building process.

Sources: packages/frontend/editor-ui/src/components/canvas/elements/nodes/render-types/CanvasNodeAIPrompt.vue:70-80, packages/frontend/editor-ui/src/constants/workflowSuggestions.ts:5-40

AI Agent Core

The core of the system is an AI agent guided by a detailed system prompt. This prompt defines the agent's principles, strategies, and constraints, ensuring it generates efficient and correct n8n workflows.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts

Core Principles & Rules

The agent's behavior is governed by a strict set of rules defined in main-agent.prompt.ts.

Principle	Description
Core Principle	After receiving tool results, the agent must reflect on their quality and plan the next steps to ensure all nodes are properly configured and connected.
Communication Style	Responses must be concise. The agent must NOT provide commentary between tool calls and should only respond after all tools are complete.
Parallel Execution	All tools support parallel execution. The agent is instructed to perform tasks like searching, adding, and configuring nodes in parallel for efficiency.
Node Defaults Warning	The agent is critically warned NEVER to rely on default parameter values, as they are a common source of runtime failures. It must explicitly configure all behavior-controlling parameters.
Workflow Configuration Node	A `n8n-nodes-base.set` node, named "Workflow Configuration", must be placed after the trigger to centralize workflow-wide settings.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:4-21, 95-110, 112-133

Workflow Creation Sequence

The agent follows a strict, multi-phase sequence to build workflows. This ensures a logical and error-resistant construction process.

This flowchart shows the mandated sequence for workflow creation.

Generating architecture diagram...

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:28-50

Special Workflow Patterns

The agent is instructed on specific patterns for common, complex workflows.

RAG Workflow Pattern

For Retrieval-Augmented Generation (RAG) workflows, a specific connection pattern is enforced to ensure the Vector Store node receives data, document processing capabilities, and embedding capabilities correctly.

This diagram shows the connection logic for a RAG workflow.

Generating architecture diagram...

The agent is explicitly warned not to connect the Document Loader to the main data flow, as it is an AI sub-node, not a data processor in the main flow.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:79-108

`$fromAI` Expressions

A critical feature for "Tool" nodes (e.g., gmailTool, googleCalendarTool) is the $fromAI expression. This allows the AI agent to dynamically fill parameters at runtime based on the conversation context.

Syntax: ={{ $fromAI('key', 'description', 'type', defaultValue) }}

Example Usage in a Gmail Tool node:

{
  "sendTo": "={{ $fromAI('to') }}",
  "subject": "={{ $fromAI('subject') }}",
  "message": "={{ $fromAI('message_html') }}"
}

The agent is instructed to use these expressions ONLY in nodes whose type ends with "Tool". For regular nodes, it must use static values or standard n8n expressions.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:187-246

Example AI-Generated Workflow

The system can generate complex workflows from a single prompt. The file ai-workflow-v2.ts contains a pre-defined workflow for a "Daily AI Summary" which demonstrates the kind of output the AI builder can produce. It includes triggers, AI nodes, tool nodes, and sticky notes for documentation.

{
	"name": "AI Agent workflow",
	"meta": { "templateId": "ready-to-run-ai-workflow-v2" },
	"nodes": [
		{
			"parameters": { "url": "https://www.theverge.com/rss/index.xml" },
			"type": "n8n-nodes-base.rssFeedReadTool",
			"name": "Get Tech News"
		},
		{
			"parameters": { "rule": { "interval": [{ "triggerAtHour": 7 }]}},
			"type": "n8n-nodes-base.scheduleTrigger",
			"name": "Run every day at 7AM"
		},
		{
			"parameters": {
				"model": { "__rl": true, "mode": "list", "value": "gpt-4.1-mini" }
			},
			"type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
			"name": "OpenAI Model"
		},
		{
			"parameters": {
				"promptType": "define",
				"text": "=Summarize world news and tech news from the last 24 hours. ..."
			},
			"type": "@n8n/n8n-nodes-langchain.agent",
			"name": "AI Summary Agent"
		},
		{
			"parameters": { "subject": "Your news daily summary", "message": "={{ $json.output }}" },
			"type": "n8n-nodes-base.gmail",
			"name": "Send summary by email"
		}
	],
	"connections": {
        "Get Tech News": { "ai_tool": [[{ "node": "AI Summary Agent", "type": "ai_tool" }]]},
        "Run every day at 7AM": { "main": [[{ "node": "AI Summary Agent", "type": "main" }]]},
        "OpenAI Model": { "ai_languageModel": [[{ "node": "AI Summary Agent", "type": "ai_languageModel" }]]},
        "AI Summary Agent": { "main": [[{ "node": "Output", "type": "main" }]]}
    }
}

This is a simplified representation of the workflow.
Sources: packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v2.ts

Evaluation

The AI Workflow Builder includes a comprehensive evaluation framework to test its ability to generate correct workflows from natural language prompts. The framework supports both local CLI-based evaluation and integration with LangSmith.

Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md

Evaluation Metrics

Workflows are scored across seven weighted categories, with specialized evaluator chains for each metric running in parallel for performance.

Metric	Weight	Description
Functionality	25%	Checks if the workflow achieves the requested goal and uses the correct nodes.
Connections	15%	Analyzes if nodes are connected logically and data flow paths are optimal.
Expressions	15%	Validates n8n expression syntax and data path references.
Node Configuration	15%	Checks if node parameters are set correctly and required fields are populated.
Efficiency	10%	Evaluates for redundancy, path optimization, and minimal node count.
Data Flow	10%	Analyzes data transformations and validation logic.
Maintainability	5%	Assesses node naming, workflow organization, and structural quality.

Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md:104-140

Running Evaluations

The evaluation suite can be run from the command line.

CLI Evaluation

# Run all default test cases
pnpm eval

# Run a specific test case
pnpm eval --test-case google-sheets-processing

Langsmith Evaluation

# Set required environment variables
export LANGSMITH_API_KEY=your_api_key

# Run evaluation
pnpm eval:langsmith

A nodes.json file containing all n8n node type definitions is required in the evaluations/ directory to run the tests, as the agent needs this information to generate valid workflows.

Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md:158-185

Testing with Playwright

End-to-end tests for AI features are written using Playwright. The testing cheat sheet provides patterns for setting up and testing AI-driven scenarios.

Example AI Test Pattern:

test('should handle workflow execution error', async ({ n8n }) => {
  await n8n.start.fromImportedWorkflow('failing-workflow.json');
  await n8n.workflowComposer.executeWorkflowAndWaitForNotification('Problem in node');
  await expect(n8n.canvas.getErrorIcon()).toBeVisible();
});

Sources: packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:70-75

AI Workflow Builder

Relevant source files

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

The primary user interface for this feature on an empty canvas is the CanvasNodeAIPrompt.vue component, which provides a prompt input, suggestions, and an option to build manually.

Sources: packages/frontend/editor-ui/src/components/canvas/elements/nodes/render-types/CanvasNodeAIPrompt.vue, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts

Architecture

The AI Workflow Builder operates through a client-server architecture where the frontend captures user prompts and the backend orchestrates the AI agent to generate the workflow.

The following diagram illustrates the high-level data flow from user input to workflow generation.

Generating architecture diagram...

Sources: packages/frontend/editor-ui/src/components/canvas/elements/nodes/render-types/CanvasNodeAIPrompt.vue, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts

Frontend Interaction

The user journey begins on the n8n canvas. The CanvasNodeAIPrompt.vue component is displayed on an empty canvas, providing the main interface for the AI builder.

Key UI elements and their functions:

Prompt Input: A text area for users to describe the workflow they want to build.
Suggestion Pills: A set of predefined prompts for common use cases, like "Invoice processing pipeline" or "Daily AI news digest". Clicking a pill populates the prompt input.
Manual Add Button: An alternative for users who prefer to add a trigger node manually, which opens the standard node creator.

When a user submits a prompt, the component sends a request to the backend, which then initiates the AI building process.

Sources: packages/frontend/editor-ui/src/components/canvas/elements/nodes/render-types/CanvasNodeAIPrompt.vue:70-80, packages/frontend/editor-ui/src/constants/workflowSuggestions.ts:5-40

AI Agent Core

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts

Core Principles & Rules

The agent's behavior is governed by a strict set of rules defined in main-agent.prompt.ts.

Principle	Description
Core Principle	After receiving tool results, the agent must reflect on their quality and plan the next steps to ensure all nodes are properly configured and connected.
Communication Style	Responses must be concise. The agent must NOT provide commentary between tool calls and should only respond after all tools are complete.
Parallel Execution	All tools support parallel execution. The agent is instructed to perform tasks like searching, adding, and configuring nodes in parallel for efficiency.
Node Defaults Warning	The agent is critically warned NEVER to rely on default parameter values, as they are a common source of runtime failures. It must explicitly configure all behavior-controlling parameters.
Workflow Configuration Node	A `n8n-nodes-base.set` node, named "Workflow Configuration", must be placed after the trigger to centralize workflow-wide settings.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:4-21, 95-110, 112-133

Workflow Creation Sequence

The agent follows a strict, multi-phase sequence to build workflows. This ensures a logical and error-resistant construction process.

This flowchart shows the mandated sequence for workflow creation.

Generating architecture diagram...

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:28-50

Special Workflow Patterns

The agent is instructed on specific patterns for common, complex workflows.

RAG Workflow Pattern

This diagram shows the connection logic for a RAG workflow.

Generating architecture diagram...

The agent is explicitly warned not to connect the Document Loader to the main data flow, as it is an AI sub-node, not a data processor in the main flow.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:79-108

`$fromAI` Expressions

Syntax: ={{ $fromAI('key', 'description', 'type', defaultValue) }}

Example Usage in a Gmail Tool node:

{
  "sendTo": "={{ $fromAI('to') }}",
  "subject": "={{ $fromAI('subject') }}",
  "message": "={{ $fromAI('message_html') }}"
}

The agent is instructed to use these expressions ONLY in nodes whose type ends with "Tool". For regular nodes, it must use static values or standard n8n expressions.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:187-246

Example AI-Generated Workflow

{
	"name": "AI Agent workflow",
	"meta": { "templateId": "ready-to-run-ai-workflow-v2" },
	"nodes": [
		{
			"parameters": { "url": "https://www.theverge.com/rss/index.xml" },
			"type": "n8n-nodes-base.rssFeedReadTool",
			"name": "Get Tech News"
		},
		{
			"parameters": { "rule": { "interval": [{ "triggerAtHour": 7 }]}},
			"type": "n8n-nodes-base.scheduleTrigger",
			"name": "Run every day at 7AM"
		},
		{
			"parameters": {
				"model": { "__rl": true, "mode": "list", "value": "gpt-4.1-mini" }
			},
			"type": "@n8n/n8n-nodes-langchain.lmChatOpenAi",
			"name": "OpenAI Model"
		},
		{
			"parameters": {
				"promptType": "define",
				"text": "=Summarize world news and tech news from the last 24 hours. ..."
			},
			"type": "@n8n/n8n-nodes-langchain.agent",
			"name": "AI Summary Agent"
		},
		{
			"parameters": { "subject": "Your news daily summary", "message": "={{ $json.output }}" },
			"type": "n8n-nodes-base.gmail",
			"name": "Send summary by email"
		}
	],
	"connections": {
        "Get Tech News": { "ai_tool": [[{ "node": "AI Summary Agent", "type": "ai_tool" }]]},
        "Run every day at 7AM": { "main": [[{ "node": "AI Summary Agent", "type": "main" }]]},
        "OpenAI Model": { "ai_languageModel": [[{ "node": "AI Summary Agent", "type": "ai_languageModel" }]]},
        "AI Summary Agent": { "main": [[{ "node": "Output", "type": "main" }]]}
    }
}

This is a simplified representation of the workflow.
Sources: packages/frontend/editor-ui/src/experiments/readyToRunWorkflowsV2/workflows/ai-workflow-v2.ts

Evaluation

Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md

Evaluation Metrics

Workflows are scored across seven weighted categories, with specialized evaluator chains for each metric running in parallel for performance.

Metric	Weight	Description
Functionality	25%	Checks if the workflow achieves the requested goal and uses the correct nodes.
Connections	15%	Analyzes if nodes are connected logically and data flow paths are optimal.
Expressions	15%	Validates n8n expression syntax and data path references.
Node Configuration	15%	Checks if node parameters are set correctly and required fields are populated.
Efficiency	10%	Evaluates for redundancy, path optimization, and minimal node count.
Data Flow	10%	Analyzes data transformations and validation logic.
Maintainability	5%	Assesses node naming, workflow organization, and structural quality.

Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md:104-140

Running Evaluations

The evaluation suite can be run from the command line.

CLI Evaluation

# Run all default test cases
pnpm eval

# Run a specific test case
pnpm eval --test-case google-sheets-processing

Langsmith Evaluation

# Set required environment variables
export LANGSMITH_API_KEY=your_api_key

# Run evaluation
pnpm eval:langsmith

A nodes.json file containing all n8n node type definitions is required in the evaluations/ directory to run the tests, as the agent needs this information to generate valid workflows.

Sources: packages/@n8n/ai-workflow-builder.ee/evaluations/README.md:158-185

Testing with Playwright

End-to-end tests for AI features are written using Playwright. The testing cheat sheet provides patterns for setting up and testing AI-driven scenarios.

Example AI Test Pattern:

test('should handle workflow execution error', async ({ n8n }) => {
  await n8n.start.fromImportedWorkflow('failing-workflow.json');
  await n8n.workflowComposer.executeWorkflowAndWaitForNotification('Problem in node');
  await expect(n8n.canvas.getErrorIcon()).toBeVisible();
});

Sources: packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:70-75

AI Workflow Builder

Architecture

Frontend Interaction

AI Agent Core

Core Principles & Rules

Workflow Creation Sequence

Special Workflow Patterns

RAG Workflow Pattern

$fromAI Expressions

Example AI-Generated Workflow

Evaluation

Evaluation Metrics

Running Evaluations

Testing with Playwright

AI Workflow Builder

Architecture

Frontend Interaction

AI Agent Core

Core Principles & Rules

Workflow Creation Sequence

Special Workflow Patterns

RAG Workflow Pattern

$fromAI Expressions

Example AI-Generated Workflow

Evaluation

Evaluation Metrics

Running Evaluations

Testing with Playwright

`$fromAI` Expressions

`$fromAI` Expressions