Configuration Management
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
- packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json
- packages/nodes-base/AGENTS.md
- AGENTS.md
- packages/testing/playwright/AI-TEST-CHEAT-SHEET.md
- packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/notification.ts
The n8n AI Agent is an assistant specialized in creating and editing n8n workflows based on natural language prompts. It follows a structured, multi-phase process to build efficient and robust workflows, leveraging a library of best practices and a defined set of tools for interacting with the n8n canvas. The agent's core principle is to reflect on tool results to plan optimal next steps, ensuring all nodes are properly configured and connected.
The agent's behavior is primarily defined by a comprehensive system prompt that outlines its communication style, tool execution strategy, and a mandatory sequence for workflow creation. This ensures consistency, reliability, and adherence to established development patterns within the n8n ecosystem.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:70-74
Workflow Creation Sequence
The AI Agent follows a mandatory, phased sequence to construct workflows. This structured approach ensures that all necessary information is gathered before any modifications are made to the canvas, leading to more reliable results. Several phases are designed for parallel execution to improve efficiency.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:90-92
The diagram below illustrates the high-level workflow creation sequence.
This diagram shows the sequential and parallel phases the AI Agent follows to build a workflow from a user prompt.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:94-153
Phases of Workflow Creation
| Phase | Name | Description | Execution |
|---|---|---|---|
| 1 | Categorization | Categorizes the user prompt and searches for relevant best practices documentation. | Mandatory |
| 2 | Examples | (Optional) Searches for existing workflow examples using relevant search terms. | Parallel |
| 3 | Discovery | Searches for all required node types simultaneously. | Parallel |
| 4 | Analysis | Retrieves detailed information for all discovered nodes to understand their inputs and outputs. | Parallel |
| 5 | Creation | Adds all required nodes to the canvas individually and in parallel. | Parallel |
| 6 | - Connection | Connects the nodes based on the analyzed input/output structures. | Parallel |
| 7 | Configuration | Configures parameters for all nodes, especially those controlling behavior (e.g., mode, operation). This is a mandatory step. | Parallel, Mandatory |
| 8 | Validation | Runs validate_workflow to check for structural issues and resolves any violations. | Mandatory |
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:94-153
Prompt Categorization and Best Practices
The first step in the agent's process is to categorize the user's prompt into one or more predefined WorkflowTechniques. This categorization is crucial as it determines which best-practices documents the agent will consult to build the workflow.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:97-101
Example Prompt Techniques
The system uses a set of test prompts to validate its categorization logic.
| Prompt | Expected Techniques |
|---|---|
| "create an ai chat bot" | chatbot |
| "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 |
| "Build a 'Reply Triage' workflow that triggers on inbound emails and routes them using AI" | triage |
| "Migrate JSON data from one schema to another." | data_transformation |
Sources: packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json
Best Practices Documents
Based on the categorized technique, the agent loads corresponding BestPracticesDocuments. These documents provide critical guidance on workflow design, recommended nodes, and common pitfalls to avoid. The agent is mandated to enforce these best practices, even if the user did not explicitly request them.
For example, for a Triage workflow, the agent would load the TriageBestPractices document.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:163-172, packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts:4
Recommended Nodes for Triage Workflows
| Node Category | Recommended Nodes | Purpose |
|---|---|---|
| Trigger | Webhook, Gmail Trigger, Schedule Trigger | Capture incoming items for triage. |
| Classification | IF, Switch, OpenAI, AI Agent | Perform rule-based or AI-powered classification. |
| Data Processing | Set, Function, HTTP Request | Normalize fields, implement custom logic, or fetch context. |
| Integration | Slack, HubSpot, JIRA, Database Nodes | Send notifications or create/update records in other systems. |
| Workflow Control | Execute Workflow, Error Trigger, Merge | Handle modular logic, catch failures, and consolidate branches. |
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/triage.ts:49-123
Critical Agent Rules and Patterns
The agent's system prompt defines several non-negotiable rules and patterns to ensure the creation of high-quality, functional workflows.
Node Selection and Defaults
- Prefer AI Agent Node: When building AI workflows, the
AI Agentnode (n8n-nodes-langchain.agent) is preferred over provider-specific LLM nodes (likeOpenAI) for tasks like summarization, analysis, and classification. - Never Rely on Defaults: The agent is explicitly warned to NEVER rely on default parameter values, as they are a common source of runtime failures. It must explicitly configure all parameters that control node behavior.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:155-161, 252-270
RAG Workflow Pattern
For Retrieval-Augmented Generation (RAG) workflows, the agent must follow a specific connection pattern to ensure the Vector Store node receives all necessary inputs.
The diagram below shows the correct connection pattern for a RAG workflow.
This diagram illustrates that the Vector Store receives data via its main input, and capabilities for document processing and embedding generation from specialized AI sub-nodes.
A common mistake to avoid is connecting the Document Loader to the main data flow. The Document Loader is an AI sub-node that provides a capability to the Vector Store, not a data processor in the main sequence.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:223-250
System Message Configuration
For all AI nodes (e.g., AI Agent, LLM Chain), the agent MUST separate static instructions from dynamic data.
- System Message: Contains the AI's role, task description, behavioral instructions, and expected output format.
- User Message/Text: Contains dynamic data from the workflow, such as expressions (
{{ $json.field }}) and user input.
This separation ensures consistent AI behavior while allowing for dynamic context in each execution.
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:303-329
$fromAI Expressions for Tool Nodes
Nodes that act as "Tools" for an AI Agent (e.g., gmailTool, googleCalendarTool) support a special $fromAI expression. This allows the AI to dynamically fill in parameters like email recipients or calendar event times at runtime based on the conversational context.
| Syntax | ={{ $fromAI('key', 'description', 'type', defaultValue) }} |
|---|---|
| key | A unique identifier for the parameter (e.g., 'to', 'subject'). |
| description | (Optional) A description to help the AI understand what to provide. |
| type | (Optional) The expected data type: string, number, boolean, json. Defaults to string. |
| defaultValue | (Optional) A fallback value. |
Example Usage in a Gmail Tool:
{
"sendTo": "={{ $fromAI('to') }}",
"subject": "={{ $fromAI('subject') }}",
"message": "={{ $fromAI('message_html') }}"
}
This pattern is only to be used in nodes whose type ends with "Tool".
Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:400-447
Testing AI-Driven Features
Testing for AI-driven features follows the standard n8n Playwright testing architecture, which separates concerns into four layers: Tests, Composables, Page Objects, and a BasePage. This structure allows for readable, high-level test scenarios that use business workflows defined in "Composers".
A common pattern for testing features that involve both backend and frontend interactions is to combine API calls with UI assertions.
// Example of a combined API + UI test
test('should use API-created credential in UI', async ({ n8n, api }) => {
const projectId = await n8n.start.fromNewProjectBlankCanvas();
// Create via API
await api.credentialApi.createCredential({
name: 'test-cred',
type: 'notionApi',
data: { apiKey: '12345' },
projectId
});
// Verify in UI
await n8n.canvas.addNode('Notion');
await expect(n8n.ndv.getCredentialSelect()).toHaveValue('test-cred');
});
This approach allows for efficient setup of test prerequisites via the API before validating the UI behavior.
Sources: packages/testing/playwright/AI-TEST-CHEAT-SHEET.md:57-75, 84-89
Summary
The n8n AI Agent is a sophisticated system designed to automate workflow creation with a high degree of reliability. It operates on a strict, phased sequence, prioritizing information gathering and validation before making changes. Its reliance on a comprehensive library of best practices, coupled with mandatory rules for configuration and connection patterns, ensures that the generated workflows are not only functional but also maintainable and robust. Developers extending the agent's capabilities should adhere to these established patterns, particularly by creating new best-practices documents and defining clear rules within the agent's core prompt.