Instance AI & Assistant

Relevant source files

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

• 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/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts
• packages/@n8n/instance-ai/src/knowledge-base/tests/materialize-knowledge-base.test.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/data-analysis.ts
• packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts
• AGENTS.md

Instance AI, identified in the user interface as the n8n Assistant, refers to the specialized backend systems and AI agents that facilitate automated workflow building and instance management within n8n. The system coordinates between discovery agents, code builders, and best-practice repositories to generate executable workflows from natural language prompts.

Sources: AGENTS.md:73, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:80-82

Architecture and Data Flow

The Instance AI architecture follows a multi-stage pipeline where a user's intent is analyzed, relevant integration nodes are discovered, and the final workflow logic is generated using the n8n Workflow SDK.

Workflow Generation Pipeline

The system processes requests through three primary phases:

1. Discovery Phase: The Discovery Agent identifies necessary n8n nodes and connection-changing parameters by searching the node registry and internal best practices.
2. Design Phase: The system maps node connections, handles item cardinality (identifying where executeOnce: true is needed), and applies architectural patterns like linear chains or parallel branches.
3. Code Building Phase: An expert agent generates JavaScript code using the n8n-workflow-sdk, which is then validated and converted into a saved workflow.

The diagram shows the sequential flow from initial user input to the final persistence of a generated workflow.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:40-47, packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:327-340, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:133-162

Discovery Agent

The Discovery Agent identifies relevant n8n nodes and their specific connection requirements. It categorizes user prompts into "Techniques" to retrieve targeted implementation guidance.

Workflow Techniques

The system uses specific technique categories to ground AI reasoning:

Technique	Description
chatbot	Receives and replies to direct messages (Telegram, Slack, etc.)
scheduling	Running actions at specific times or intervals
scraping_and_research	Collecting information from external websites or APIs
triage	Classifying data for routing or prioritization
document_processing	Handling content within files (PDFs, images, Excel)
data_extraction	Pulling specific information from internal data

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:98-115, packages/quality/testing/playwright/expectations/workflow-builder/1768236115215-unknown-host-POST-_v1_messages-343a818e.json:34-51

Node Selection Logic

The agent prioritizes native n8n nodes over the Code node to improve user experience and visual debugging. It utilizes specific tools to determine node capabilities:

• search_nodes: Finds nodes by name or Connection Type (e.g., ai_tool, ai_languageModel).
• get_node_details: Retrieves properties and <connections> data to identify connection-changing parameters like mode or hasOutputParser.
• get_best_practices: Pulls internal documentation for the identified techniques.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:137-160, packages/quality/testing/playwright/expectations/workflow-builder/1768236115215-unknown-host-POST-_v1_messages-343a818e.json:57-112

Code Builder Agent

The Code Builder generates executable JavaScript for n8n workflows using the Workflow SDK. It follows a strict mandatory process to ensure code validity.

Mandatory Build Process

You must follow these steps in order to generate a workflow:

1. Requirement Extraction: Quote and analyze the user request.
2. Suggested Nodes: Call get_suggested_nodes with the identified techniques.
3. Discriminator Identification: Identify resource/operation combinations (e.g., googleDrive with resource: file, operation: download).
4. Design Mapping: Trace item counts between nodes. If a node should not multiply based on input items, the builder applies executeOnce: true.
5. SDK Generation: Write the code using imports like import { workflow, node, trigger, expr } from '@n8n/workflow-sdk'.
6. Validation: Run validate_workflow to check for syntax or architectural errors.

Sources: packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts:342-420, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:133-162

SDK Implementation Patterns

The Code Builder utilizes standardized patterns for complex logic:

The diagram represents the pattern used to converge data after parallel branching.

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

Knowledge Base System

Instance AI includes a system for managing "Best Practices" and reference documentation in a local sandbox environment. This content is used to ground agents in current n8n methodologies.

Materialization and Manifests

The system materializes a "Knowledge Base" bundle into a workspace. It tracks content using a manifest file with a schemaVersion (currently version 4) and a contentHash.

• Best Practices: Markdown files for techniques like scheduling or data-analysis.
• Reference Docs: Documentation for trigger input shapes and LLM output shapes (e.g., OpenAI, Anthropic).
• Templates: Materialized from CDN index files to provide starting points for workflows.

Sources: packages/@n8n/instance-ai/src/knowledge-base/tests/materialize-knowledge-base.test.ts:40-100

Retrieval-Augmented Generation (RAG) Patterns

For workflows utilizing the knowledge_base technique, the system follows a specific split-pipeline architecture:

1. Ingestion Workflow: Fetches documents, uses the Recursive Character Text Splitter (chunk size 500-1000), generates embeddings, and inserts them into a Vector Store (Pinecone, Supabase, etc.).
2. Query Workflow: Receives a user question, performs a semantic search in the Vector Store, and passes the context to an AI Agent or Chat Model.

Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:10-50

Advanced AI Features

Multi-Agent Systems

For requests involving "teams of agents," Instance AI utilizes the AI Agent Tool. This node embeds a complete sub-agent that the main agent invokes as a tool via the ai_tool connection.

Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:60-75

Managed Credentials (Gateway)

When available, Instance AI leverages Gateway credits. This allows the builder to discover nodes that can use managed credentials, enabling the workflow to run without the user manually configuring API keys for certain LLMs or third-party services.

Sources: packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:110-116