AI агент в n8n с локален модел през Ollama

01Какво ще научиш

• Разликата между Basic LLM Chain (верига) и AI Agent (агент) и кога кое.
• Как да свържеш n8n с Ollama — и от контейнер, и директно.
• Как да избереш модел, който умее да вика инструменти, и защо контекстът има значение.
• Системно съобщение, памет (Simple Memory) и как да ограничиш безкрайните цикли.
• Три инструмента: заявка към външна услуга, малък код и справка в Postgres.
• Как агентът да върне точен JSON (Structured Output Parser) — пример с класификатор на съобщения.
• Как да държиш агента под контрол: права само за четене и одобрение от човек.

02Преди да започнеш

• Минал си Обучения 1 и 2 от серията n8n (работещ n8n, webhook и HTTP Request).
• Имаш Ollama 🔒 локално с поне един изтеглен модел — виж DevStation · Обучение 2. Използвана е версия 0.35.
• n8n е вдигнат както в DevStation · Обучение 3 (Docker Compose) или директно на машината. Уроците следват n8n 2.x (стабилната версия към 01.10.2026 е 2.41).
• По желание Postgres с отделна база за примера със справка (не базата, в която n8n пази себе си).
• Видеокарта с няколко GB видеопамет помага; на процесор агентът работи, но бавно.

03Стъпки

1. Верига или агент

   n8n има два начина да пуснеш езиков модел. Защо е важно да ги различаваш? Защото веригата е предвидима и евтина, а агентът е гъвкав, но по-бавен и по-труден за контрол.

   Възел	Какво прави	Памет и инструменти	Ползвай за
   Basic LLM Chain	Един промпт → един отговор, по избор през парсер на изхода	Без памет, без инструменти	Превод, преформатиране, резюме, класификация по прост критерий
   AI Agent	Получава модел и инструменти, сам решава кои да извика и колко пъти	Има памет и инструменти (поне един)	Задачи на няколко стъпки: потърси, реши, извърши

   Съвет: ако задачата се решава с един промпт, започни с веригата. Агентът се оправдава, когато пътят до отговора не е известен предварително.

2. Избери модел, който умее инструменти

   Агентът вика инструменти чрез „tool calling“ — моделът трябва да го поддържа. В библиотеката на Ollama 🌐 глобален такива модели носят значка tools. Към 01.10.2026 значката имат:

   Модел	Размер на файла	Таван на контекста	Бележка
   qwen2.5:7b	4.7 GB	32K	Моделът от предните уроци; добър за начало
   qwen3:8b	5.2 GB	40K	Носи още значката thinking (разсъждава)
   llama3.1:8b	4.9 GB	128K	Дълъг контекст
   llama3.2:3b	2.0 GB	128K	Малък — за слаби машини и бързи опити

   bash · в Ubuntu (WSL2)копирай

   ollama pull qwen2.5:7b
   ollama list

   Без значката tools не очаквай агентът да работи с инструменти — ⚠️ не сме проверявали какво точно се случва. Изборът на модел е като избор на колега: по-малкият е бърз, но греши по-лесно. За агент започни от 7–8b.

   ⚠️

   Контекстът по подразбиране е малък

   Ollama по подразбиране отваря 4k контекст на видеокарти под 24 GiB и препоръчва за агенти поне 64000. Но всеки модел има таван (таблицата горе), а повече контекст значи повече памет. Практично: задай стойност в рамките на тавана и на видеопаметта си, например 32000 за qwen2.5:7b. Както в Обучение 2, променливите на сервиза стоят в override, не в ~/.bashrc.
   bash · override на сервизакопирай

   sudo systemctl edit ollama
   # в редактора, под реда [Service]:
   #   Environment="OLLAMA_CONTEXT_LENGTH=32000"
   sudo systemctl daemon-reload && sudo systemctl restart ollama

3. Свържи n8n с Ollama (credential)

   В n8n: Credentials → Create credential → Ollama. Има само едно задължително поле — Base URL. Ключ не ти трябва: полето „API key“ е само за Ollama зад прокси с автентикация (праща се като Bearer токен) — остави го празно.

   Къде работи n8n	Base URL
   В Docker (Docker Desktop), Ollama на хоста	http://host.docker.internal:11434
   В Docker на Linux	същото, но в compose има extra_hosts: "host.docker.internal:host-gateway" (вече е в стека от DevStation · Обучение 3)
   Директно на машината (не в контейнер)	http://localhost:11434; при грешка ECONNREFUSED ::1 — http://127.0.0.1:11434

   Защо не localhost в контейнер? Вътре в контейнера localhost е самият контейнер. Провери от контейнера:

   bash · от папката на стекакопирай

   docker compose exec n8n wget -qO- http://host.docker.internal:11434/api/tags

   Трябва да видиш JSON със списък на моделите. Адресът е без /v1 — n8n говори с родния интерфейс на Ollama.

   ⚠️

   Контейнерът не стига до Ollama?

   Същата препоръка като в DevStation · Обучение 3: Ollama слуша само на loopback (безопасно), а промяната му се прави през sudo systemctl edit ollama и се придружава от затваряне на порта в защитната стена за всички освен собствената машина. Прочети предупреждението там, преди да пипаш адреса за слушане.

4. Първи тест: Basic LLM Chain

   Преди агента провери, че моделът отговаря. Workflows → Create workflow → Manual Trigger → Basic LLM Chain. В промпта избери Define below и напиши примерно Обясни накратко какво е агент. Отговори на български. Към веригата закачи под-възела Ollama Chat Model: твоят credential и моделът qwen2.5:7b (списъкът с модели се тегли от твоя Ollama; ⚠️ страницата на нода в документацията още показва стари имена на Llama 2 — не им вярвай).

   настройки · Ollama Chat Modelкопирай

   Model: qwen2.5:7b
   Options:
     Sampling Temperature: 0.2   # ниско = по-предсказуемо
     Top K / Top P: по подразбиране

   Натисни Execute workflow. Отговорът е в панела Output — обикновено в полето text (⚠️ виж как се казва при теб). Ако работи, основата е готова.

5. AI Agent с памет

   Сега агентът. Започни нов работен процес: Chat Trigger → AI Agent. Към агента закачи три неща: Ollama Chat Model (същият credential), Simple Memory и поне един инструмент (следващата стъпка). Без инструмент възелът няма да тръгне.

   настройки · AI Agentкопирай

   Prompt: Connected Chat Trigger Node     # (или Define below)
   System Message:
     Ти си помощник на екипа. Отговаряй само на български, кратко и конкретно.
     Ползвай инструментите, когато ти трябва информация, която не знаеш.
     Ако не намериш отговора след 3 опита, отговори: "Не намерих информация."
     Днешна дата: {{ $now.toFormat('dd.MM.yyyy') }}
   
   Options:
     Max Iterations: 10             # по подразбиране; ограничава циклите
     Return Intermediate Steps: on  # за проверка кой инструмент е викан
   
   Ollama Chat Model:
     Model: qwen2.5:7b
     Sampling Temperature: 0.1      # ниско за работа с инструменти
   
   Simple Memory:
     Session Key: по подразбиране за чата
     Context Window Length: 10      # последните 10 размени

   💡

   Как работи паметта — и докъде стига

   Simple Memory пази последните разговори, за да може агентът да отговори на „а кога?“ след предишен въпрос. Това е памет за сесията — не се запазва между сесии и документацията не препоръчва възела при n8n в режим на опашка. За по-трайно пазене има Postgres Chat Memory (сам създава таблица; задай отделен Session Key за всеки разговор). Веригата (стъпка 1) няма памет изобщо. Ако Simple Memory дава грешка, махни го и го добави наново — често идва от стара версия на възела.

   Отвори чата на нода и попитай: Казвам се Мария. Как се казвам? Ако агентът отговори правилно, паметта работи.

6. Три инструмента

   Инструментите са „ръцете“ на агента. Най-важното е описанието — моделът чете именно него, за да реши кога да извика инструмента. Пиши го като инструкция на колега: какво прави и какво да му подаде.

   а) HTTP Request 🌐 глобален — външна услуга

   Добави HTTP Request като инструмент към агента. Параметрите могат да се попълват от модела чрез $fromAI() — там „ключът“ е подсказка, не връзка към поле.

   настройки · HTTP Request (инструмент)копирай

   Description: Взема кратка прогноза за времето за град. Подай името на града.
   Method: GET
   URL: https://wttr.in/{{ $fromAI('city', 'Име на града', 'string') }}?format=3

   Внимание: това е външна услуга — името на града излиза от машината ти. За чувствителни данни ползвай само локални инструменти.

   б) Custom Code 🔒 локално — малък код

   Инструмент с твой код, JavaScript или Python. Входът на инструмента е в променливата query; връщаш текст. ($fromAI() тук не работи — входът е само query.)

   Custom Code (JavaScript)копирай

   // Description: Брои думите в подаден текст. Входът е самият текст.
   const words = String(query).trim().split(/\s+/).filter(Boolean);
   return String(words.length);

   в) Postgres 🔒 локално — справка в база

   Добави Postgres като инструмент: операция Execute Query. Заявката е с $1, а стойността идва от модела. n8n обезопасява параметрите на заявката срещу SQL инжекция.

   настройки · Postgres (инструмент)копирай

   Description: Търси контакт по име или имейл. Подай част от името или имейла.
   Operation: Execute Query
   Query:
     SELECT name, email, company
     FROM contacts
     WHERE name ILIKE '%' || $1 || '%'
        OR email ILIKE '%' || $1 || '%'
     LIMIT 5;
   Options → Query Parameters:
     {{ $fromAI('query', 'Име или имейл за търсене', 'string') }}

   ✅

   Потребител само за четене, отделна база

   Credential-ът за този инструмент да е на потребител с права само SELECT върху нужната таблица, в отделна база — не в базата на самия n8n. Тогава и най-лошата грешка на модела не може да промени данни. ⚠️ Заявката не е пускана от нас; провери таблицата и имената на колоните при себе си.

7. Човек одобрява опасното

   Когато даваш инструмент с реален ефект (изпраща съобщение, променя запис, трие), моделът не бива да го вика сам. n8n има Human-in-the-loop за инструменти: в панела Tools на агента добавяш стъпка „Human review“ и канал за одобрение (чат на n8n, Slack, Telegram, Gmail и др.), после закачаш рисковите инструменти към нея. При такова викане работният процес спира и чака „Approve“ или „Deny“ от човек; при отказ действието не се изпълнява. Подробности — в документацията на n8n (връзката е в „Източници“). ⚠️ Наличността на функцията зависи от твоята версия на n8n — провери в панела.

8. Структуриран изход: отговор с точна форма

   Защо? Свободният текст не може да се прати на следващ възел. Когато искаш полета (категория, приоритет), моделът трябва да върне JSON по твоя схема. На веригата или агента включваш Require Specific Output Format и закачаш Structured Output Parser. Схема можеш да зададеш по два начина: Generate from JSON Example (n8n взема имената и типовете; всички полета стават задължителни) или Define using JSON Schema (ръчно; $ref не се поддържа).

   Structured Output Parser · схема (JSON Schema)копирай

   {
     "type": "object",
     "properties": {
       "category": { "type": "string", "enum": ["urgent", "normal", "low", "spam"] },
       "sentiment": { "type": "string", "enum": ["positive", "neutral", "negative"] },
       "summary": { "type": "string", "description": "Резюме в едно изречение" },
       "action_required": { "type": "boolean" }
     },
     "required": ["category", "sentiment", "summary", "action_required"]
   }

   Пример: класификатор на съобщения. Manual Trigger → Edit Fields (Set) с поле message (примерен текст) → Basic LLM Chain с парсера → IF, който праща спешните по друг клон.

   Basic LLM Chain · промпт (Define below)копирай

   Анализирай следното съобщение и го класифицирай.
   
   Съобщение: {{ $json.message }}
   
   Върни резултат по зададената схема.

   След веригата провери в панела Output къде са полетата — обикновено под output (⚠️ не сме го пускали), например {{ $json.output.category }}. В IF сравни категорията с urgent.

   💡

   Когато моделът греши формата

   Малките модели понякога връщат невалиден JSON. В документацията на n8n има и Auto-fixing Output Parser, предвиден за поправяне на невалиден изход (⚠️ не сме го пускали). По-голям модел също помага.

9. Когато нещо не върви

   ❌

   Агентът зацикля в повиквания на инструменти

   Остави Max Iterations на разумна стойност (по подразбиране 10), държи температурата ниска, направи описанията на инструментите по-ясни и добави в системното съобщение кога да спре („след 3 неуспешни опита отговори, че не си намерил“). Включи Return Intermediate Steps, за да видиш какво вика.
   ❌

   Агентът не вика инструмент или вика грешно

   Най-вероятно моделът няма значка tools, е твърде малък, или контекстът е препълнен от описанията (виж стъпка 2). ⚠️ Това е наша преценка, не е от документацията — пробвай модел от таблицата и по-голям контекст.
   ❌

   „400 Invalid value for 'content': expected a string, got null“

   В промпта има израз, който не дава стойност. Провери, че полетата, които ползваш, съществуват. При Connected Chat Trigger Node махни празните стойности от chatInput.
   ❌

   „No prompt specified“ или „A Chat Model sub-node must be connected“

   Първото: смени Prompt от „Connected Chat Trigger Node“ на „Define below“ (когато не идва от Chat Trigger). Второто: към нода не е закачен модел — използвай бутона + Chat Model.
   ❌

   Първата заявка е бавна или изтича времето

   При първата заявка моделът се зарежда в паметта. Виж с ollama ps дали е зареден и дали е върху видеокартата (Обучение 2); пробвай по-малък модел за тестове.
   ❌

   Не се свързва с Ollama

   Виж стъпка 3: host.docker.internal в контейнер, без /v1, и за грешка с ::1 — адресът 127.0.0.1 (когато n8n не е в контейнер).

04Проверка

Чеклист

• Моделът е изтеглен, носи значката tools, а контекстът е зададен в рамките на тавана му.
• Контейнерът стига до Ollama през host.docker.internal; credential-ът е записан, адресът е без /v1.
• Тестът с Basic LLM Chain връща отговор.
• AI Agent има модел, Simple Memory и поне един инструмент; системното съобщение е написано.
• Агентът отговаря на въпрос, който зависи от предишно съобщение (паметта работи).
• С Return Intermediate Steps се вижда кой инструмент е викан; няма безкраен цикъл.
• Инструментът за Postgres ползва потребител само за четене; рисковите инструменти са зад одобрение от човек.
• Structured Output Parser връща договорените полета, а IF ги използва.

Тест

05Какво следва

06Източници

1. n8n: AI Agent · Tools Agent · чести проблеми — остарялата настройка „Agent Type“, Max Iterations, грешките с промпта.
2. n8n: Ollama Chat Model · чести проблеми (Docker, host.docker.internal, ::1) · credential за Ollama.
3. n8n: Simple Memory · Postgres Chat Memory.
4. n8n: Basic LLM Chain · Structured Output Parser.
5. n8n: Custom Code Tool · Postgres · HTTP Request като инструменти.
6. n8n: Use AI for parameters ($fromAI()) · Human-in-the-loop for tools.
7. Ollama: дължина на контекста 🔒 локално — стойности по подразбиране и препоръка за агенти.
8. Библиотеката на Ollama 🌐 глобален: qwen2.5 · qwen3 · llama3.1 · llama3.2 — значка „tools“, размери и таван на контекста.