Agent Framework & LLM Tooling
Relevant source files
The following files were used as context for generating this wiki page:
- packages/@n8n/agents/AGENTS.md
- packages/@n8n/agents/examples/basic-agent.ts
- packages/@n8n/ai-workflow-builder.ee/src/code-builder/prompts/index.ts
- packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts
- packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts
- packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts
The Agent Framework provides a system for building, managing, and executing AI agents within n8n. It allows developers to create autonomous or semi-autonomous entities that use Large Language Models (LLMs) to perform tasks, use tools, and maintain memory. The framework separates agent definitions from the execution engine, enabling agents to operate as first-class persisted artifacts rather than just nodes within a standard workflow.
Sources: packages/@n8n/agents/AGENTS.md, packages/cli/src/modules/mcp/tools/workflow-builder/mcp-instructions.ts:182-184
Core Framework Architecture
The framework utilizes a fluent builder pattern for public primitives. User code configures agents, tools, and memory through these builders, which call a internal .build() method during execution. The engine uses an EngineAgent class to inject infrastructure concerns like credentials and checkpoint storage before execution.
Sources: packages/@n8n/agents/AGENTS.md:10-15, packages/@n8n/agents/AGENTS.md:73-84
Component Relationship
The following diagram illustrates the relationship between core SDK components.
LLM Tooling & Integration
Agents interact with the environment through tools. A Tool defines its purpose through a description and enforces data structures using Zod schemas for inputs and outputs.
Tool Execution Flow
Tools can perform synchronous actions or suspend execution for human intervention. The suspend and resume pattern allows for "Human-in-the-loop" workflows where an agent pauses for approval before continuing.
Native Node vs. Code Node Tooling
The framework prioritizes native n8n nodes for tooling to ensure visual debugging and better user experience. Developers should map specific services to their native counterparts.
| Use Case | Recommended Node/Tool |
|---|---|
| Research | SerpAPI Tool, Perplexity Tool |
| Messaging | Slack Tool, Gmail Tool |
| Calculations | Calculator Tool |
| Sub-Agents | AI Agent Tool |
| Data Cleaning | Edit Fields (Set) |
| Item Grouping | Aggregate |
Sources: packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:178-190, packages/@n8n/ai-workflow-builder.ee/src/prompts/agents/discovery.prompt.ts:211-218
Memory & State Management
Agents maintain state through memory builders. The Memory class allows agents to store conversation history and observation logs. Persistence is handled via resourceId and threadId, ensuring continuity across different sessions.
Multi-Agent Systems
The framework supports hierarchical agent structures through the AI Agent Tool (@n8n/n8n-nodes-langchain.agentTool). This allows a "Main" orchestrator agent to call specialized "Sub-Agents" as tools. Each sub-agent can have its own chat model and specialized instructions.
Knowledge Base Best Practices
When implementing Knowledge Base (RAG) agents, the framework follows a specific pipeline for data ingestion and retrieval.
- Ingestion: Documents are loaded via a
Data Loader, split using aText Splitter(recommended size 500-1000 characters), and converted into vectors via anEmbeddingsnode. - Storage: Vectors are stored in databases like Pinecone, Qdrant, or Supabase.
- Retrieval: The AI Agent uses a
Tool Vector Storeto query the database during the generation phase.
Sources: packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:8-30, packages/@n8n/workflow-sdk/src/prompts/best-practices/guides/knowledge-base.ts:121-125
Development Patterns
Code Implementation
Agents are defined using the Agent class from the SDK. Credentials are never touched directly; instead, they are declared by name and resolved by the engine.
import { Agent, Tool } from '@n8n/agents';
const myAgent = new Agent('assistant')
.model('anthropic/claude-sonnet-4-5')
.credential('anthropic')
.instructions('Be helpful.');
Sources: packages/@n8n/agents/AGENTS.md:65-71, packages/@n8n/agents/examples/basic-agent.ts:12-14
Internal Runtime Components
The package structure separates the SDK surface from runtime internals:
sdk/: Contains fluent builders (Agent, Tool, Memory).runtime/: Contains the execution engine (agent-runtime.ts), tool adapters, and stream helpers.workspace/: Provides sandbox and filesystem access for tools.
Sources: packages/@n8n/agents/AGENTS.md:27-55
Summary
The Agent Framework & LLM Tooling provides a robust structure for creating AI-driven entities in n8n. By leveraging a fluent SDK, modular tools, and structured memory, it enables complex multi-agent architectures and high-fidelity "Human-in-the-loop" interactions while maintaining strict data schemas and credential security.