How to Build an AI Agent Using n8n Self-Hosted

# Customer Support AI Agent in n8n — Build Guide

## 1. Prerequisites

**Self-hosted n8n (Docker):**
- n8n ≥ 1.19.0 (LangChain nodes required). Update your `docker-compose.yml`:
  ```yaml
  environment:
    - N8N_ENCRYPTION_KEY=<your-key>
    - DB_POSTGRESDB_HOST=postgres
    - N8N_AI_ENABLED=true
  ```
- Persistent volume mapped to `/home/node/.n8n`.

**Credentials to create in n8n (Credentials → New):**
- **OpenAI API** – paste your key.
- **Postgres** – host, port, database, user, password for your knowledge base.
- (Optional) **Postgres Chat Memory** – same or separate DB for storing chat history.

**Database prep:**
- Ensure your KB table exists, e.g. `docs(id, title, content, tags)`.
- For memory, n8n auto-creates `n8n_chat_histories` on first run.

---

## 2. Workflow Architecture

Nodes required:
1. **Chat Trigger** (`@n8n/n8n-nodes-langchain.chatTrigger`) – entry point with `sessionId`.
2. **AI Agent** (Tools Agent type) – orchestrator.
3. **OpenAI Chat Model** – sub-node of Agent (LLM).
4. **Postgres Chat Memory** – sub-node of Agent (history per user).
5. **Tool: Postgres** (or **Workflow Tool** wrapping a Postgres query) – KB search.
6. *(Optional)* **Vector Store Tool** if you later add embeddings.

Flow: `Chat Trigger → AI Agent` with Chat Model, Memory, and Tool(s) attached to the agent.

---

## 3. Step-by-Step Build

**Step 1 – Create workflow & add Chat Trigger.**
- Mode: `Hosted Chat` (public URL) or `Embedded`.
- Enable **"Make chat publicly available"** if exposing externally.

**Step 2 – Add AI Agent node.**
- Connect from Chat Trigger.
- Agent type: **Tools Agent**.
- System Message:
  ```
  You are a helpful customer support assistant for <Product>.
  Answer strictly using product documentation. If unsure, call the
  "searchKnowledgeBase" tool. Cite doc titles. If no match, say so.
  ```

**Step 3 – Attach Chat Model.**
- Sub-node: **OpenAI Chat Model**.
- Credential: OpenAI API.
- Model: `gpt-4o-mini` (cost-effective) or `gpt-4o`.
- Temperature: `0.2` for factual support.

**Step 4 – Attach Memory.**
- Sub-node: **Postgres Chat Memory**.
- Credential: Postgres.
- Session Key expression:
  ```
  ={{ $json.sessionId }}
  ```
- Context Window Length: `10` messages. This partitions history per user automatically.

**Step 5 – Add the Knowledge Base Tool.**
- Sub-node: **Postgres Tool** (under Tools).
- Tool Name: `searchKnowledgeBase`
- Description (critical – the agent uses this to decide when to call):
  ```
  Searches product documentation. Input: a concise search query string.
  Returns matching doc titles and content snippets.
  ```
- Operation: **Execute Query**.
- Query (use `$fromAI` so the LLM fills the argument):
  ```sql
  SELECT title, LEFT(content, 800) AS snippet
  FROM docs
  WHERE content ILIKE '%' || {{ $fromAI('query','search term','string') }} || '%'
     OR title   ILIKE '%' || {{ $fromAI('query','search term','string') }} || '%'
  LIMIT 5;
  ```
- For production, replace `ILIKE` with `tsvector` full-text search or pgvector similarity.

**Step 6 – (Optional) Response formatting.**
Add an **Edit Fields** node after the agent if exposing via webhook/API to shape the output:
```json
{ "reply": "={{ $json.output }}", "session": "={{ $('Chat Trigger').item.json.sessionId }}" }
```

---

## 4. Testing & Activation

1. Click **Open Chat** on the Chat Trigger.
2. Test conversation memory:
   - "My name is Sam." → then "What's my name?" → should recall.
3. Test tool invocation:
   - "How do I reset my API token?" → check execution log; the Agent should show a call to `searchKnowledgeBase` with a `query` argument.
4. Inspect **Executions** tab → expand AI Agent node → verify `intermediateSteps` contains tool calls and observations.
5. Toggle **Active** (top right) to enable the public chat URL: `https://<your-n8n>/webhook/<chatId>`.

---

## 5. Troubleshooting Tips

- **Agent ignores the tool:** Sharpen the tool description; state *when* to use it. Vague descriptions are the #1 cause.
- **Memory not persisting:** Confirm `sessionId` is stable per user (pass it from your frontend, not regenerated per request). Check `n8n_chat_histories` table rows.
- **`$fromAI` undefined:** You're on an older n8n — upgrade to ≥ 1.62, or use a Workflow Tool with explicit input schema instead.
- **Postgres permission errors:** Grant `SELECT` on `docs` to the n8n DB user; memory user needs `CREATE, INSERT, SELECT`.
- **Token overruns / slow replies:** Lower context window to 6, trim `LEFT(content, 500)`, or switch to `gpt-4o-mini`.
- **Docker can't reach Postgres:** Use the container service name as host (e.g.,

# n8n Self-Hosted Customer Support AI Agent Build Guide

## 1. Prerequisites

**Self-Hosted n8n Setup:**
- n8n running via Docker with persistent volume (`docker run -d -p 5678:5678 -v n8n_data:/home/node/.n8n n8nio/n8n`)
- Ensure webhook URLs are publicly accessible or use ngrok for local testing

**API Keys & Credentials:**
- OpenAI API key (gpt-4 or gpt-3.5-turbo recommended)
- Postgres connection details (host, port, database, user, password)
- Store credentials in n8n's credential manager, never hardcode

**Database Setup:**
- Postgres table with schema: `id`, `content`, `metadata`, `embedding` (for semantic search), `created_at`
- Populate with product documentation chunks

---

## 2. Workflow Architecture

**Core Nodes Required:**
1. **Chat Trigger** – Webhook entry point for user messages
2. **Set Variable (User Context)** – Extract userId, sessionId from payload
3. **Memory Node** – Store/retrieve conversation history per user
4. **AI Agent (ReAct)** – Orchestrates tool selection and reasoning
5. **Chat Model (OpenAI)** – LLM backbone
6. **Postgres Node (Query Tool)** – Search documentation knowledge base
7. **HTTP Node (Optional)** – Call external APIs if needed
8. **Chat Send Response** – Return response to user

---

## 3. Step-by-Step Build

**Step 1: Create Chat Trigger**
- Node type: `Chat Trigger`
- Configure webhook path: `/customer-support`
- Authentication: API key or Bearer token
- Extract: `userId`, `message`, `sessionId` from request body

**Step 2: Set Variable for Session Management**
- Node type: `Set` 
- Create expressions:
```json
{
  "userId": "{{ $input.first().json.userId }}",
  "sessionId": "{{ $input.first().json.sessionId || $input.first().json.userId }}_{{ Date.now() }}",
  "userMessage": "{{ $input.first().json.message }}"
}
```

**Step 3: Configure Memory Node**
- Node type: `Memory`
- Storage type: `Window Buffer` (keep last 10 messages)
- Key pattern: `conversation_{{ $vars.sessionId }}`
- Add user message to memory before querying AI

**Step 4: Build Postgres Query Tool (Preparation)**
- Node type: `Postgres`
- Name this sub-workflow as "Search Documentation"
- Query template:
```sql
SELECT content, metadata FROM documentation 
WHERE content ILIKE '%' || $1 || '%' 
LIMIT 5
```
- Parameter: `{{ $input.first().json.query }}`

**Step 5: Configure AI Agent**
- Node type: `AI Agent` (ReAct model)
- LLM: OpenAI Chat Model
- System prompt:
```
You are a helpful customer support agent. You have access to our product documentation. 
When a user asks about features, pricing, or usage, search the documentation first.
Be concise and friendly. Always cite documentation sources.
```
- Tools:
  - **Search Documentation** (Postgres node) – Input: user query, Output: relevant docs
  - **Provide Answer** – Direct response without external search

**Step 6: Add Chat Model Node**
- Model: `gpt-3.5-turbo` or `gpt-4`
- Temperature: `0.7`
- Max tokens: `500`
- Include conversation history: `{{ $vars.memory.messages }}`

**Step 7: Response & Memory Update**
- Node type: `Chat Send Response`
- Map agent output to response field
- Add response to memory with role `assistant`
- Persist memory state to Postgres session table (optional)

**Step 8: Error Handling**
- Add error catch node before response
- Return: `"I encountered an issue. Please try again or contact support directly."`

---

## 4. Testing & Activation

**Local Testing:**
- Use Postman or curl to send test messages:
```bash
curl -X POST http://localhost:5678/webhook/customer-support \
  -H "Content-Type: application/json" \
  -d '{"userId":"user123","message":"How do I reset my password?","sessionId":"sess_abc"}'
```

**Activation:**
- Deploy workflow to production
- Configure Chat Trigger webhook for production domain
- Monitor execution logs in n8n UI for failures
- Set up alerts for failed executions (optional)

---

## 5. Troubleshooting Tips

| Issue | Solution |
|-------|----------|
| Memory not persisting | Verify storage backend configured; check Redis/DB connectivity |
| Postgres timeouts | Increase query timeout; optimize SQL with indexes on `content` |
| Agent loops | Reduce tool count; add max iteration limit (4-5 steps) |
| Token overflow | Implement message summarization for old history; use `sliding_window` memory |
| OpenAI rate limits | Implement backoff retry; use gpt-3.5-turbo; batch requests |

**Debug Mode:**
- Enable workflow execution logging in n8n settings
- Add `debug` parameter to Chat Trigger for verbose output
- Test memory retrieval: Add Debug node after Memory node to inspect conversation state

---

**Estimated build time:** 2-3 hours. Start with basic Q&A, then layer memory and tools incrementally for stability.

Of course. Here is a complete, step-by-step guide for building your customer support AI agent in a self-hosted n8n instance.

### 1. Prerequisites

Before building, ensure the following are configured in your self-hosted n8n environment:

*   **n8n Instance:** A running self-hosted n8n instance (Docker is ideal).
*   **OpenAI Credentials:** Go to **Credentials** > **Add credential**, search for "OpenAI API," and add your API key.
*   **Postgres Credentials:** Go to **Credentials** > **Add credential**, search for "Postgres," and add your database connection details (host, user, password, database).
*   **Postgres `pgvector` Extension:** For effective knowledge base searching, your Postgres database should have the `pgvector` extension installed and your documentation table must contain vector embeddings for semantic search.

### 2. Workflow Architecture

This workflow uses a modular, agentic design. You will use the following n8n nodes:

*   **Trigger:** `Chat Trigger` - Provides a webhook to receive user messages.
*   **Agent Core:** `AI Agent` - The central orchestrator that manages the conversation flow, state, and tool usage.
*   **Language Model:** `LangChain Chat Model (OpenAI)` - Connects the agent to the OpenAI API for reasoning and response generation.
*   **Memory:** `LangChain Conversation Window Buffer Memory` - Stores conversation history, segmented by user ID.
*   **Tool:** `Postgres` - The action node the agent can call to query your knowledge base.

### 3. Step-by-Step Build

Follow these steps to construct the workflow on your n8n canvas.

**Step 1: Configure the Chat Trigger**
1.  Add a `Chat Trigger` node to the canvas.
2.  This node exposes a webhook URL. You will

### 1. Prerequisites
- **n8n Setup**: Self-hosted n8n via Docker (e.g., `docker run -it --rm --name n8n -p 5678:5678 -v ~/.n8n:/home/node/.n8n n8nio/n8n`). Access at `http://localhost:5678`. Ensure version ≥1.0 for AI nodes.
- **API Keys/Credentials**:
  - OpenAI: Create credential in n8n (Connections > Add Credential > OpenAI). Use your API key.
  - Postgres: Create credential (Connections > Postgres). Provide host, database, user, password, port (default 5432). Assume KB table `docs` with columns `id`, `content`, `title` for RAG-style search.
- Enable AI nodes in n8n settings if not active.

### 2. Workflow Architecture
Core nodes:
- **Chat Trigger**: Entry point for user chats; auto-manages session IDs for per-user history.
- **AI Agent** (connected to Chat Trigger output): Orchestrates reasoning.
  - **Chat Model**: OpenAI (GPT-4o-mini for efficiency).
  - **Memory**: Window Buffer Memory (k=5 for recent history per session).
  - **Tools**: Postgres Query Tool (custom: searches KB via SQL with user query embedding/keyword).
- Optional: Error Trigger for handling failures.

High-level flow: User msg → Chat Trigger → AI Agent (uses Memory + Tool if needed) → Response.

### 3. Step-by-Step Build
1. **Create New Workflow**: In n8n, click "New" > name it "Customer Support AI Agent".
2. **Add Chat Trigger**:
   - Drag "Chat Trigger" node.
   - Config: Allowed Hosts: `*` (or your domain). Response Mode: "Respond to Webhook".
   - Save. This generates a chat URL (e.g., `/webhook/chat-trigger/...`).
3. **Add AI Agent Node**:
   - Connect Chat Trigger → AI Agent.
   - Config: Agent Type: "Tools Agent". Prompt: `You are a helpful customer support agent for our product. Use the Postgres tool to search documentation for accurate answers. Always be polite and concise.`.
   - Max Iterations: 5. Attach Chat Trigger input as `{{ $json.message }}`.
4. **Configure Chat Model in AI Agent**:
   - Add Resource: OpenAI Chat Model.
   - Credential: Your OpenAI cred.
   - Model: `gpt-4o-mini`. Temperature: 0.1. Max Tokens: 1000.
5. **Add Memory in AI Agent**:
   - Add Resource: Window Buffer Memory.
   - Config: Max Messages: 10 (stores per Chat Trigger session ID).
6. **Create Postgres Tool**:
   - In AI Agent, Add Tool > "Postgres" (or HTTP if custom).
   - Better: Use "Code" Tool for SQL execution.
     - Tool Name: "search_docs".
     - Tool Description: "Searches product docs in Postgres KB. Input: query string. Returns relevant snippets.".
     - Code (JS snippet):
       ```javascript
       const { query } = require('pg'); // n8n handles cred
       const client = await getPostgresClient(items[0].json.query);
       const res = await client.query(`
         SELECT title, content FROM docs 
         WHERE to_tsvector('english', content) @@ to_tsquery('english', $1)
         ORDER BY ts_rank LIMIT 3
       `, [input]);
       return { results: res.rows.map(r => `${r.title}: ${r.content.slice(0,500)}`).join('\n') };
       ```
     - Credential: Postgres cred. (Adapt SQL for your schema; use pgvector for embeddings if advanced.)
7. **Connect & Save**: AI Agent output auto-handles response via Chat Trigger. Activate workflow.

### 4. Testing & Activation
- **Test**: Open generated chat URL in browser/incognito (new session). Ask: "How do I reset my password?" → Agent queries Postgres, responds with history.
- **Multi-Session**: Open multiple tabs; history persists per session ID.
- **Activate**: Toggle "Active" in workflow editor. Embed chat URL in your site via iframe: `<iframe src="your-n8n-chat-url"></iframe>`.
- Monitor executions in n8n UI.

### 5. Troubleshooting Tips
- **No History**: Ensure Chat Trigger session ID flows to Memory (`{{ $json.chatId }}`).
- **Postgres Errors**: Test cred separately (add temp Postgres node). Check Docker network if DB external.
- **Rate Limits**: OpenAI: Monitor usage; fallback to `gpt-3.5-turbo`. n8n queue mode for scale.
- **Tool Not Called**: Refine prompt/tool desc; check AI Agent logs for reasoning.
- **Docker Issues**: Expose ports, volumes persist data. Logs: `docker logs n8n`.
- Debug: Add "Respond to Webhook" node post-Agent for raw outputs.

(Word count: 612)