Overview
The N8N AI Agent node connects to an external AI Agent service, enabling advanced AI-driven chat interactions with support for tool calling and memory management. It is designed to facilitate conversational AI workflows within n8n, allowing users to send messages to various AI models, optionally include images, maintain conversation history, and enable AI tools for enhanced capabilities.
Common scenarios where this node is beneficial include:
- Building chatbots that leverage powerful AI models like GPT-4 Turbo or Claude 3.
- Automating customer support conversations with context awareness.
- Integrating AI-powered image analysis by sending images alongside text messages.
- Using AI tools/functions dynamically during conversations (e.g., weather lookup).
- Managing session memory to store and retrieve conversation data across executions.
Practical example:
- A user sends a message "What’s the weather like today?" with tools enabled and a weather tool configured. The AI Agent can call the weather tool function and return the current weather information in the chat response.
Properties
| Name | Meaning |
|---|---|
| AI Model | Select the AI model to use. Options: GPT-4 Turbo, GPT-4, GPT-3.5 Turbo, Claude 3 Opus, Claude 3 Sonnet, Claude 3 Haiku, Gemini Pro. |
| Message | The main message text to send to the AI Agent. |
| System Message | Optional system prompt to set AI behavior and context before the user message. |
| Include Media | Whether to include an image in the chat message. Boolean true/false. |
| Media Source | Source of the media file if including media. Options: Upload File (base64), From URL, From Binary Data (from previous node). |
| Image File | Base64 encoded image data (used if Media Source is Upload File). |
| Image URL | URL of the image to analyze (used if Media Source is From URL). |
| Binary Property | Name of the binary property containing the image (used if Media Source is From Binary Data). |
| Include Conversation History | Whether to include previous messages for context in the chat. Boolean true/false. |
| Conversation History | JSON array of previous messages in OpenAI chat format, e.g., [{"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hi there!"}]. Used if Include Conversation History is true. |
| Enable Tools | Allow the AI to use tools and function calling during the chat. Boolean true/false. |
| Tools Configuration | JSON configuration of tools available to the AI Agent, e.g., functions it can call. |
| Advanced Options | Collection of optional parameters controlling generation: - Max Tokens (max tokens to generate, 0 = default) - Temperature (randomness control 0-1) - Top P (nucleus sampling diversity 0.01-1) - Frequency Penalty (reduce repetition -2 to 2) - Presence Penalty (encourage new topics -2 to 2) |
Output
The node outputs a JSON object per input item with the following structure:
message: The AI-generated chat response string.model: The AI model used for the response.operation: The operation performed ("chat").usage: Optional usage statistics about token consumption.tool_calls: Optional details about any tool/function calls made by the AI.memory: Optional memory data returned from the AI Agent.finish_reason: Reason why the generation finished (e.g., "completed").
If media was included, the AI Agent processes the image but the output remains textual chat responses; no direct binary output is produced by this node.
Dependencies
- Requires connection to an external N8N AI Agent API service.
- Requires an API key credential for authenticating requests to the AI Agent service.
- The AI Agent endpoint URL defaults to
http://localhost:5678but can be customized via credentials. - The node uses internal helper methods to send HTTP POST requests to the AI Agent API endpoints (
/chat,/tools,/memory).
Troubleshooting
- Missing API Key: If the API key is not provided or invalid, the node throws an error "N8N API key is required" or "Invalid N8N API key". Ensure the API key credential is correctly configured.
- Endpoint Not Found: Error "N8N AI Agent endpoint not found" indicates the AI Agent service is not running or not enabled on the specified URL. Verify the AI Agent service is active and accessible.
- Media Processing Issues: If including media, ensure the base64 data, URL, or binary property is valid and accessible. Invalid or missing media data may cause the request to fail.
- Tool Configuration Errors: When enabling tools, ensure the tools JSON configuration is valid and the tools exist on the AI Agent side.
- Token Limits: Setting max tokens too high may cause errors or truncated responses. Use reasonable values respecting model limits.
- Conversation History Format: The conversation history must be a valid JSON array of message objects with roles and content; malformed JSON will cause errors.
Links and References
- OpenAI Chat Completions API
- Anthropic Claude Models
- Google Gemini AI
- n8n Documentation: Creating Custom Nodes
- n8n Workflow Helpers: HTTP Request Helper