Instance AI Assistant
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/instance-ai/src/instance-ai.service.ts
- packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
- packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts
- packages/@n8n/instance-ai/src/knowledge-base/tests/materialize-knowledge-base.test.ts
- AGENTS.md
The Instance AI Assistant (referred to in code as "Instance AI") is a specialized backend service and user interface component within n8n designed to assist users in building, managing, and optimizing workflows through artificial intelligence. It acts as an orchestrator that leverages Large Language Models (LLMs) to provide automated workflow generation, node discovery, and best-practice guidance.
Sources: AGENTS.md:126, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:36-39
System Architecture
The Instance AI system is structured as a multi-stage pipeline that transitions from user intent to executable workflow code. It utilizes a "Discovery Agent" to identify necessary components and a "Code Builder Agent" to generate the final JavaScript SDK-based workflow definitions.
Workflow Generation Pipeline
The system follows a mandatory process to ensure technical accuracy and valid node configurations:
- Analysis: Extracting requirements and identifying technique categories (e.g., chatbot, notification, scraping).
- Discovery: Using tools to search for existing n8n nodes and retrieve their specific versioning and parameter details.
- Design: Mapping connections, handling item cardinality (loops/merges), and planning the workflow graph.
- Validation: Running the generated code through a validation engine to check for syntax or logical errors.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:339-440, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:46-51
Architecture Overview
The following diagram illustrates the high-level data flow from a user request to a validated workflow.
The diagram shows the iterative nature of the code generation process, where validation feedback loops back into the builder agent.
Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:425-440
Knowledge Base and Best Practices
A critical component of the Instance AI Assistant is the Knowledge Base, which stores prebaked documentation and templates to guide the AI's decision-making process.
Content Materialization
The system "materializes" a bundle of markdown files and JSON indexes into a sandbox workspace. This includes:
- Best Practices: Guides for specific techniques like scheduling, data analysis, and RAG (Retrieval-Augmented Generation).
- Reference Guides: Documentation on trigger input shapes and LLM output schemas.
- Templates: Pre-configured workflow snippets.
Sources: packages/@n8n/instance-ai/src/knowledge-base/tests/materialize-knowledge-base.test.ts:60-110, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:4-10
Technique Categorization
The AI categorizes workflows into specific techniques to retrieve relevant best practices:
| Technique | Description |
|---|---|
| Chatbot | Receiving and replying to messages in a conversation. |
| Scraping | Methodically collecting information from websites or APIs. |
| Triage | Classifying data for routing or prioritization (e.g., lead scoring). |
| Document Processing | Handling files like PDFs, images, or spreadsheets. |
| Knowledge Base | Using centralized information (Vector DBs) for Q&A. |
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:182-220
AI Node Selection Logic
The Assistant follows strict heuristics when selecting nodes to ensure the resulting workflows are robust and use native n8n features instead of generic code blocks.
Native Node Preference
The Assistant is programmed to prioritize native nodes over the Code Node for performance and maintainability.
- Edit Fields (Set): Used for adding, renaming, or mapping fields.
- Filter/If/Switch: Used for conditional logic.
- Split Out/Aggregate: Used for array manipulations and item combining.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:300-330
Multi-Agent System Support
For complex requests involving "teams of agents," the system implements a hierarchical structure using the AI Agent Tool.
This diagram demonstrates the relationship where a main agent manages specialized sub-agents via tools, each requiring its own language model connection.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:64-79
Component Specification
Connection-Changing Parameters
The Instance AI identifies specific parameters that alter the physical structure (inputs/outputs) of a node. These must be identified during the discovery phase:
- Merge Node: The
numberInputsparameter. - Switch Node: The
mode(rules vs. expression) determines the number of output branches. - AI Agent: The
hasOutputParsertoggle adds a specific input port for schema definition.
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:246-260
Ingestion vs. Query Pattern
For Knowledge Base (RAG) features, the assistant architectural recommendation follows a split-workflow pattern:
- Ingestion Workflow: Triggered by file watchers or schedules to process and index documents into a Vector Database.
- Query Workflow: Triggered by user queries to retrieve context and generate AI responses.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:6-15
Conclusion
The Instance AI Assistant is a sophisticated orchestration layer that bridges the gap between natural language intent and complex workflow automation. By utilizing a structured multi-agent approach, a dedicated knowledge base of best practices, and a preference for native node configurations, it ensures that generated workflows are technically sound, scalable, and aligned with n8n's architectural standards.