Chat & Agent Framework

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/chains/prompts/parameter-types/system-message.ts
• packages/@n8n/ai-workflow-builder.ee/src/subgraphs/test/integration/techniques.json
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/chatbot.ts
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/data-analysis.ts
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/knowledge-base.ts
• packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/notification.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/cli/src/modules/chat-hub/chat-hub-workflow.service.ts
• packages/frontend/@n8n/design-system/src/components/AskAssistantChat/AskAssistantChat.stories.ts
• packages/frontend/editor-ui/src/app/constants/workflowSuggestions.ts
• packages/nodes-base/AGENTS.md
• packages/testing/playwright/AI-TEST-CHEAT-SHEET.md
• packages/testing/playwright/CONTRIBUTING.md

The Chat & Agent Framework in n8n provides a robust system for creating, managing, and executing AI-powered conversational workflows. It enables the dynamic construction of workflows that can interact with users through chat interfaces, leverage large language models (LLMs), utilize tools, and maintain conversational context. This framework is central to n8n's AI capabilities, powering features like the AI assistant and enabling developers to build sophisticated agents for various tasks.

The core of the framework is the ChatHubWorkflowService, which dynamically assembles workflows based on user input, conversation history, and a predefined set of tools. These workflows are built using specialized LangChain nodes, such as the AI Agent, Chat Trigger, and Memory nodes, to create complex, stateful, and intelligent automations.

Architecture Overview

The framework is composed of several key services, nodes, and UI components that work together to provide a seamless chat and agent experience.

Core Components

Component	Description	Source File
ChatHubWorkflowService	A backend service responsible for dynamically creating and managing chat-related workflows, including the main chat flow and title generation.	packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts
AI Agent Node	The central orchestrator of AI logic. It processes user input, uses tools, interacts with LLMs, and manages memory to generate responses.	packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts
Chat Trigger Node	The entry point for user messages in a chat-based workflow. It captures input and initiates the workflow execution.	packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:397-406
Memory Nodes	Components like MemoryBufferWindow and MemoryManager that store and retrieve conversation history, providing context for the AI agent.	packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:592-603
Model Nodes	Integrations with various LLM providers (e.g., OpenAI, Anthropic, Google Gemini) that provide the core language understanding and generation capabilities.	packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:440-590
Tool Nodes	Standard n8n nodes that are exposed to the AI Agent, allowing it to perform actions like sending emails, searching databases, or calling APIs.	packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:103-106
AskAssistantChat Component	The Vue.js frontend component that renders the chat interface, displays messages, and handles user interactions.	packages/frontend/@n8n/design-system/src/components/AskAssistantChat/AskAssistantChat.stories.ts

High-Level Data Flow

The following diagram illustrates the high-level data flow when a user sends a message in the chat interface.

Dynamic Workflow Construction

A key feature of the framework is the ability to construct workflows dynamically at runtime. The ChatHubWorkflowService is responsible for this process.

Sources: packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts

createChatWorkflow Method

When a user initiates or continues a conversation, the createChatWorkflow method is called. It assembles a complete n8n workflow in memory, tailored to the current conversation.

This method constructs a workflow with the following key nodes:

• Chat Trigger: To receive the user's message.
• Restore Chat Memory: A MemoryManager node to load the conversation history.
• Merge: To combine the incoming message with the restored history.
• AI Agent: The core logic node.
• Chat Model: The specific LLM node (e.g., OpenAI, Anthropic).
• Memory: A MemoryBufferWindow node connected to the agent for context.
• Clear Chat Memory: A MemoryManager node to clear the history after the agent responds.
• Tool Nodes: Any tools provided to the agent.

Sources: packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:51-110, packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:321-395

The diagram below shows the structure of the dynamically generated chat workflow.

createTitleGenerationWorkflow Method

A similar, but simpler, workflow is created by createTitleGenerationWorkflow. Its purpose is to generate a concise title for a new conversation based on the user's first message. It uses a dedicated system prompt for this task.

This workflow consists of:

1. Chat Trigger
2. Title Generator Agent (an AIAgent node)
3. Chat Model

Sources: packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:112-161, packages/cli/src/modules/chat-hub/chat-hub-workflow.service.ts:664-679

AI Agent and Prompting Strategy

The AI Agent is guided by a comprehensive system prompt that defines its behavior, principles, and operational sequence.

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

Core Principles

• Silent Tool Execution: The agent should execute tools without providing commentary between calls.
• Parallel Execution: All tools, including node creation (add_nodes), support parallel execution to improve efficiency.
• Mandatory Best Practices: The agent MUST enforce best practices documented for different workflow techniques (e.g., Chatbot, RAG), even if not explicitly requested by the user.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:70-77, 100-110

Workflow Creation Sequence

The agent follows a strict, multi-phase sequence to build workflows, ensuring robustness and correctness.

Phase	Name	Description
1	Categorization	Categorize the user's prompt and search for best practices documentation.
2	Examples	(Optional) Search for relevant workflow examples.
3	Discovery	Search for all required node types simultaneously.
4	Analysis	Get details for all discovered nodes to understand their inputs and outputs.
5	Creation	Add all required nodes to the canvas, preferably in parallel.
6	Connection	Connect the nodes based on the analysis.
7	Configuration	Configure parameters for every node. This is mandatory.
8	Validation	Run validate_workflow to check for structural issues.

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

System Message vs. User Prompt

A critical aspect of the prompting strategy is the strict separation of the System Message from the User Message/Text.

• System Message: Defines the AI's role, capabilities, task description, and behavioral instructions. This content is static and persistent.
• User Message/Text: Contains dynamic, execution-specific content like user input, variables from other nodes, and workflow context.

This separation ensures consistent AI behavior while allowing for dynamic context in each execution.

Correct Usage Example:

{
  "text": "=The research topic is: {{ $json.researchTopic }}",
  "options": {
    "systemMessage": "You are an orchestrator agent... Your task is to: 1. Call Tool A, 2. Call Tool B..."
  }
}

Sources: packages/@n8n/ai-workflow-builder.ee/src/chains/prompts/parameter-types/system-message.ts, packages/@n8n/ai-workflow-builder.ee/src/tools/prompts/main-agent.prompt.ts:405-498

Frontend Chat Interface

The user-facing part of the framework is the AskAssistantChat Vue component, which provides a rich, interactive chat experience.

Sources: packages/frontend/@n8n/design-system/src/components/AskAssistantChat/AskAssistantChat.stories.ts

Message Types

The chat UI supports various message types to display information clearly.

Type	Role	Description
text	assistant / user	A standard text message. Can contain Markdown for rich formatting, including lists, tables, and links.
block	assistant	A formatted block with a title and content, often used for summaries or step-by-step instructions.
code-diff	assistant	Displays a code differential, useful for showing changes to code or configurations.
code-snippet	assistant	Displays a block of code with syntax highlighting.
tool	assistant	Represents a tool call, showing its status (running, completed, error) and optionally its inputs and outputs.
event	assistant	Represents a non-display event in the conversation, such as end-session.
error	assistant	Displays an error message to the user.

This diagram shows the different message types supported by the UI.

Best Practices for Agentic Workflows

The system includes documented best practices for building common types of agentic workflows.

Chatbot Workflows

• Shared Memory: When a workflow has multiple triggers (e.g., a schedule and a chat trigger), they MUST be connected through shared memory or data stores to ensure the chatbot has access to all relevant context.
• Context Management: Utilize memory nodes to maintain conversation history for follow-up questions.
• Message Attribution: Disable the default "n8n workflow" attribution on messages for a more natural user experience.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/chatbot.ts:14-25, 41-44

Knowledge Base (RAG) Workflows

• Separate Workflows: Use a dedicated "Ingestion Workflow" to process and index documents and a separate "Query Workflow" for retrieval and answering questions.
• Consistent Embeddings: It is CRITICAL to use the same embedding model for both indexing documents and querying the vector store.
• Optimal Retrieval: Limit the number of retrieved documents to 3-5 for the best balance of context and performance. Use a low temperature (0-0.3) for factual, accurate answers.

Sources: packages/@n8n/ai-workflow-builder.ee/src/tools/best-practices/knowledge-base.ts:10-14, 50-52, 65-68