Встроенный чат для отладки AI-воркфлоу

Встроенное окно чата открывается прямо в редакторе n8n. Оно нужно, чтобы быстро проверить, как AI-воркфлоу отвечает на сообщения, без подключения Telegram или сайтового виджета. Чат работает только вместе с нодой Chat Trigger — без неё кнопка открытия не появляется.

Окно не генерирует ответы само. Чтобы получить ответ, воркфлоу должен выполниться: либо в режиме разработки, либо после публикации.

Как это работает

Нода Chat Trigger добавляется так: на пустом холсте нажми + → в списке триггеров What triggers this workflow? выбери On chat message. На холсте нода появится под именем When chat message received. После добавления появляется кнопка Open chat — и на карточке самой ноды, и в нижней панели инструментов canvas.

Для отладки используй Test this trigger внутри настроек ноды или сразу открывай чат кнопкой Open chat. Каждое сообщение в таком режиме запускает воркфлоу один раз.

Для постоянной работы без повторных запусков нажми Publish в заголовке воркфлоу. В этом режиме чат слушает сообщения постоянно, пока воркфлоу опубликован.

Отдельной кнопки сохранения нет — все изменения сохраняются автоматически.

Типичные ошибки

• Кнопки Open chat нет → в воркфлоу не добавлена нода Chat Trigger; добавь её, кнопка появится.
• Отправил сообщение, бот молчит → воркфлоу не запущен; нажми Test this trigger или Open chat, либо Publish.
• Поменял системный промпт, ответы прежние → Test this trigger подхватывает правки только при новом запуске, а не на лету.
• Ищешь кнопку Save → её нет, воркфлоу сохраняется автоматически.
• Ждёшь, что в этом чате будут сидеть реальные пользователи → это инструмент разработки, для прода нужен внешний канал.

Добавление ноды на canvas

Чтобы продолжить цепочку, нужно вставить новую ноду после существующей или на пустой canvas. Для этого открывают панель выбора нод тремя способами: кнопка Open nodes panel в центре canvas, кнопка Add node на стрелке соединения и + на output-коннекторе любой ноды.

Панель называется What happens next?. В ней сразу видно категории и поле поиска.

Как это работает

• Клик по Open nodes panel или Add node открывает список.
• В поле Search nodes... вводят имя ноды или сервиса (например http, slack, schedule). Список фильтруется по мере ввода.
• Навигация по категориям: AI, Action in an app, Data transformation, Flow, Core, Human review, Add another trigger.
• Клик по названию ноды ставит её на canvas и сразу открывает панель Parameters.
• На пустом canvas можно нажать клавишу Tab — откроется та же панель без клика мышью.

Первая нода любого воркфлоу должна быть триггером (Schedule Trigger, Webhook, Manual и подобные). Обычные ноды-действия в начало ставить нельзя.

Типичные ошибки

• Поставил обычную ноду первой → воркфлоу не из чего стартовать → замени первую ноду на триггер из категории Core или через поиск.
• Ищут ноду по русскому названию → список остаётся пустым → вводи английское имя сервиса в поле Search nodes....
• Целятся мышью в мелкий + на стрелке → промахиваются → нажми Tab прямо на canvas.
• Открывают категорию Add another trigger после уже существующей ноды → добавляют лишний триггер → для обычного шага используй поиск или категории Action in an app и Data transformation.

Pin Data в n8n: как зафиксировать тестовый вход ноды

Pin Data — это способ «прибить» к ноде заранее заготовленные данные, которые n8n будет подставлять вместо настоящего входа на каждом тестовом запуске. Полезно, когда дёргать реальный источник (внешний воркфлоу, веб-хук, API) на каждое нажатие Execute workflow неудобно или невозможно.

Зачем это нужно

Часто отлаживается не сам триггер, а ноды после него — логика, маппинг, запрос в базу. Чтобы не звать каждый раз источник данных (другой воркфлоу, бот, форму), удобнее один раз получить пример настоящего входа, зафиксировать его на триггере и потом крутить запуски сколько нужно.

Поэтому Pin Data — это инструмент разработчика на этапе сборки, не часть рабочего воркфлоу. В боевом режиме закреплённые данные перестают использоваться: n8n берёт реальный вход.

Как это работает

К любой ноде с выходом можно прикрепить «запинённый» JSON. После этого:

• При запуске воркфлоу через UI (Execute workflow, тестовый прогон) n8n не вызывает саму ноду, а сразу выдаёт следующим нодам зафиксированные данные.
• Pin Data привязана к конкретной ноде, не к workflow целиком — можно запинить триггер и оставить остальные ноды живыми.
• На холсте у запинённой ноды появляется визуальный значок (булавка/иконка), чтобы не забыть, что данные «искусственные».

Удобнее всего пинить триггер: на нём поле выхода — то, что в боевом режиме приходит снаружи (Telegram-апдейт, тело веб-хука, поля Execute Workflow Trigger). Тестовый JSON собирают с теми же ключами, что отдаёт реальный источник.

Типичные ошибки

• Забыли про пин при отладке — в редакторе тестовые прогоны идут по закреплённым данным, а не по реальным, поэтому новый вход «не доходит». Боевому запуску пин не мешает, но перед проверкой на живых данных его лучше снять.
• Структура запинённого JSON не совпадает с реальным — отладка проходит идеально, но в проде ломается на полях, которых не было в тестовом примере; делайте пин из реальной execution, а не «на глаз».
• Запинили середину воркфлоу, забыли — переименовали поле в ноде до пина, а пин остался со старой структурой. Следующие ноды читают «фантомные» данные.
• Pin Data перепутали с переменными среды — пин не передаётся между воркфлоу и не сохраняется при экспорте на другую инсталляцию n8n как «конфиг»; это именно отладочный фиксаж.

Когда не подходит

Pin Data не заменяет настоящие тесты — это удобство в редакторе, не автоматизация. Если нужна повторяемая проверка с разными входами, лучше делать отдельный тестовый workflow или мини-набор тест-кейсов; пин подходит, когда хочется быстро прогнать «один и тот же» сценарий N раз.

Три ноды — одна модель, три разных задачи

В n8n запрос к языковой модели можно отправить тремя классами нод: нативная нода вендора (OpenAI, Anthropic, Google Gemini — пункт «Message a Model»), Basic LLM Chain и AI Agent. У всех трёх под капотом — вызов LLM, но устроены они по-разному и решают разные задачи. Выбор не на вкус: для одного кейса подходит одна, для другого — другая.

Когда что выбирать

• Нативная нода вендора — когда нужен один простой вызов к конкретной модели и больше ничего: классификатор текста, переписать одно сообщение, извлечь сущности по промпту. Минимум абстракций, максимум контроля над параметрами вендорского API (например, response_format у OpenAI). Память истории придётся собирать руками — нода её не ведёт.
• Basic LLM Chain — когда нужен один вызов, но с возможностью менять модели и/или вытаскивать структурированный вывод через парсер. Типичный кейс: «сгенерируй JSON по схеме». Сегодня модель OpenAI, завтра — Gemini, ноду переключать не надо, меняешь только sub-ноду Chat Model.
• AI Agent — когда модели нужны инструменты (поиск в БД, вызов API, доступ к Sub-Workflow) или память диалога между сообщениями пользователя. Бот, который помнит разговор, ассистент с инструментами, агент с RAG — это AI Agent. Бот, который отвечает на каждый вопрос отдельно, без памяти и инструментов, обходится Basic LLM Chain.

Типичные ошибки

• Поставил AI Agent, потому что «звучит модно», без инструментов и памяти → переплачиваешь токенами на служебный ReAct-промпт, получаешь то же, что дал бы Basic LLM Chain. Без tools — Chain.
• Взял нативную ноду OpenAI ради «структурированного JSON» → парсера у нативной ноды нет, ответ парсишь сам в следующей Code-ноде. Если нужен валидированный JSON по схеме — Basic LLM Chain с Output Parser sub-нодой.
• Подключил Chat Memory к Basic LLM Chain и ждёшь, что бот «запомнит» предыдущее сообщение → Basic LLM Chain не ведёт диалог, он делает один запрос за вызов. Для памяти диалога нужен AI Agent.
• Сменил вендора в нативной ноде → надо переписывать всю ноду заново (поля разные у OpenAI и Anthropic). В Basic LLM Chain / AI Agent — меняется только sub-нода Chat Model, остальное остаётся.

Что такое sub-нода

В n8n AI-ноды устроены как «родитель + дети». Родитель — основная нода (AI Agent, Qdrant Insert, Qdrant Vector Store…). Дети — sub-ноды, которые подключаются к специальным кружкам на нижней стороне родителя. Каждая sub-нода — это «поставщик ресурса» для родителя.

Какие бывают sub-ноды

• Embeddings — поставляет векторы (OpenAI / Cohere / Voyage / Google Gemini / bge / …).
• Chat Model — поставляет LLM для AI Agent, Basic LLM Chain и других AI-нод, например Guardrails.
• Document Loader — поставляет «нарезанные» куски документа.
• Text Splitter — внутри Document Loader, разбивает на чанки.
• Memory — поставляет историю диалога для AI Agent.
• Tool — поставляет инструменты, которые AI Agent может вызвать.

Когда родитель запускается (например, Qdrant Insert получил файл и собирается записать его в БД), он по очереди обращается к sub-нодам: «дай мне чанки», «переведи каждый чанк в вектор». Sub-ноды отвечают, родитель собирает результат.

Как выглядит sub-нода в параметрах родителя

Если открыть параметры родителя двойным кликом — справа выезжает панель параметров, а на нижней границе панели видны кружки sub-нод. Подключённая sub-нода показана как круглый цветной индикатор с иконкой провайдера. При наведении — всплывающая подсказка с именем и статусом.

Как заменить sub-ноду

1. Закрой панель параметров родителя (Esc).
2. На canvas найди подключённую sub-ноду — она расположена под родителем. Кликни на ней, нажми Delete (или правый клик → Delete). Sub-нода удалится, у родителя освободится слот.
3. На родителе освободившийся слот покажет «+» (например, Add document embedding). Нажми — справа откроется список доступных sub-нод нужного типа.

1. Выбери нужную sub-ноду — она автоматически подключится к родителю на освободившемся слоте.
2. Заполни параметры новой sub-ноды (credential, модель, режим).

Универсальный процесс добавления credential

Credential в n8n — это сохранённая «учётка» для подключения к сервису (API-ключ, OAuth-токен, логин/пароль и т.д.). Любая нода, которой нужна авторизация, выбирает credential из общего списка — поэтому добавлять его нужно один раз, а использовать можно из любого количества нод того же типа.

Пошагово

1. В левом меню n8n открой раздел Credentials.

1. Нажми кнопку Add credential (правый верхний угол).

1. В поиске введи название нужного типа credential — например, OpenAI, Header Auth, Postgres, Google — и выбери его из списка.

1. В шапке формы дай credential понятное имя — например, OpenAI школа или Postgres prod. По этому имени ты будешь выбирать его в нодах.

1. Заполни поля формы. Какие именно — зависит от типа: для API-ключевых это обычно одно поле API Key, для Header Auth — Name и Value заголовка, для Postgres — host/port/database/user/password, для OAuth — запуск OAuth-flow по кнопке.

1. Нажми Save. Готово — credential можно подключать к любой ноде, которая поддерживает этот тип.

Один URL вместо ключей всех провайдеров

LiteLLM-прокси — это единый шлюз, который принимает запросы в формате OpenAI и пересылает их к разным платным моделям: OpenAI, Anthropic, DeepSeek, Cohere и другим. Студент работает только с одним адресом и одним набором настроек.

Школа поднимает прокси, чтобы все студенты ходили через общий счёт. Школа платит провайдерам по одному договору и видит расход токенов каждого студента по отдельности. Студенту не нужно заводить личные billing-аккаунты и следить за лимитами.

OpenAI-совместимый интерфейс позволяет использовать прокси в n8n и SDK без изменений кода. Ноды и библиотеки отправляют запросы на школьный адрес, а не напрямую на api.openai.com.

Как это работает

В n8n credential OpenAi account указывает Base URL школьного прокси. Все запросы к моделям DeepSeek, Claude и остальным идут через этот credential. Модель указывается в параметре model как обычно.

Прокси не хранит модели у себя. Он только маршрутизирует запросы к внешним API и возвращает ответы. Поэтому он не заменяет self-hosted решения вроде Ollama.

Прямой ключ провайдера нужен только в двух случаях: когда требуется Assistants API или когда нужны параметры, которые прокси ещё не поддерживает. В остальных задачах весь трафик идёт через OpenAi account.

Типичные ошибки

• Считаешь OpenAi account отдельной моделью → запрос уходит не туда → выбирай имя модели из списка, который даёт школа.
• Меняешь значение model на имя из документации провайдера → модель не находится → уточняй у школы, какое имя доступно через прокси.
• Пытаешься вызвать Assistants API через прокси → запрос падает → используй прямой ключ OpenAI.
• Думаешь, что личный ключ запрещён → можно использовать, но по умолчанию весь учебный трафик должен идти через OpenAi account.
• Путаешь прокси с self-hosted моделью → ждёшь, что модели работают без интернета → LiteLLM только пересылает запросы к платным API.

Два эндпоинта к одним моделям

У OpenAI два разных эндпоинта для одних и тех же моделей: /v1/chat/completions и /v1/responses. Оба принимают запросы к gpt-4o и другим моделям, но формат запроса и ответа у них несовместим.

Chat Completions — старый и до сих пор поддерживаемый путь. Responses API — новый интерфейс, который OpenAI рекомендует для агентских сценариев.

Ключевое отличие не в модели, а в том, как ты передаёшь данные и хранишь контекст.

Как это работает

Chat Completions принимает массив messages. В ответе модель возвращает одно сообщение в choices[0].message. Всю историю разговора клиент должен хранить и отправлять заново при каждом запросе.

Responses API использует параметр input — это может быть строка или массив typed items. Поле instructions вынесено отдельно от сообщений. В ответе приходит массив typed output items (message, reasoning, function_call и другие).

Responses поддерживает stateful-цепочки через previous_response_id: OpenAI хранит предыдущие сообщения на своей стороне. Токены предыдущих запросов при этом всё равно учитываются при биллинге.

В Responses встроены инструменты Web Search, File Search и Code Interpreter — их можно включить без написания собственных функций.

В n8n-ноде OpenAI Chat Model есть переключатель Use Responses API, который меняет эндпоинт запроса. Через школьный прокси LiteLLM результат зависит от ноды, к которой подключена модель: AI Agent отвечает в обоих положениях, но с включённым переключателем n8n записывает в выполнение только оценку расхода — tokenUsageEstimate, где токены ответа модели всегда 0; Text Classifier с включённым переключателем падает на каждом элементе. С выключенным переключателем запрос идёт на /v1/chat/completions, и в выполнении виден настоящий расход — блок tokenUsage. Поэтому в задачах школы переключатель выключают всегда.

Это именно разные эндпоинты: формат Chat Completions, отправленный на /v1/responses, не сработает, и наоборот.

Типичные ошибки

• Оставили Use Responses API включённым при работе через школьный LiteLLM-прокси → у AI Agent в выполнении нет настоящего расхода токенов, только оценка с нулём на ответе, а Text Classifier падает на каждом элементе → выключи переключатель.
• Перенесли готовый воркфлоу с прямого OpenAI на прокси и не тронули тоггл → часть нод падает, у остальных пропадает настоящий расход токенов → проверь состояние переключателя в каждой OpenAI-ноде.
• Передали в запрос к /v1/chat/completions поля input, instructions или previous_response_id → ошибка валидации или поля просто игнорируются → используй только массив messages и храни историю на стороне клиента.
• Решили, что Responses API нужен только для новых моделей → gpt-4o доступен по обоим эндпоинтам, разница только в формате → не путай выбор эндпоинта с выбором модели.

Запустить одну ноду, не дёргая весь workflow

Execute step — это кнопка внутри панели ноды (открывается двойным кликом по ноде). По смыслу — младший брат большой кнопки Execute workflow внизу холста: та запускает весь воркфлоу с начала, эта — только текущую ноду. Удобно, когда настраиваешь параметры и хочешь сразу видеть, что отдаёт нода, не перезапуская всю цепочку.

Как это работает

Когда ты жмёшь Execute step, n8n берёт уже существующие данные на входе ноды (output предыдущей ноды из последнего прогона) и прогоняет через эту ноду. Сама нода выполняется реально: HTTP-запрос уходит, запись в базу пишется, письмо отправляется. Это не «сухой прогон», а полноценное выполнение — только одного шага.

Типичный сценарий: запустил весь воркфлоу один раз (Execute workflow), увидел что нода HTTP Request отдаёт не то, поправил поле URL, нажал Execute step — увидел новый результат за секунду. Предыдущие ноды повторно не выполнялись.

Типичные ошибки

• Жать Execute step на ноде, у которой ещё не было входных данных → «No input data», нода не запустится. Сначала прогони весь воркфлоу через Execute workflow или хотя бы триггер вручную, чтобы у каждой ноды появился output.
• Использовать Execute step для проверки изменений в предыдущих нодах → текущая нода работает со старым output, изменения не подхватятся. Если поправил предыдущую ноду — перезапусти её, а потом уже текущую.
• Тестировать ноду с побочным эффектом (запись в БД, отправка письма) на проде → каждый клик создаёт реальную запись. Использовать тестовый credential или временно подменять параметры на безопасные.

Что такое Simple Memory

Simple Memory — sub-нода n8n, которая хранит историю диалога прямо в оперативной памяти n8n. В поиске нод и на холсте она называется Simple Memory; в старых версиях n8n и в англоязычных гайдах её зовут Window Buffer Memory.

Нода не использует базы данных или внешние сервисы. История видна только своему воркфлоу и стирается при перезапуске n8n или после часа без обращений к ней (n8n 2.20.7). Между запусками одного воркфлоу в пределах этого часа история сохраняется (кухня, 25.10.2026, выполнения k1 996–998).

Как работает буфер

Нода хранит последние N пар «вопрос-ответ» — это называется «окно контекста» (Context Window).

По умолчанию Context Window Length = 5: агент помнит последние 5 сообщений пользователя и 5 ответов. Старые сообщения вытесняются новыми. Вызов инструмента агентом тоже занимает место в окне: при окне 1 агент с инструментом на следующей реплике уже не помнит, о чём шла речь (n8n 2.20.7, кухня k4 1697–1706).

Session ID

Каждый пользователь получает свою отдельную историю диалога. ID сессии определяется автоматически — из поля sessionId, которое Chat Trigger передаёт при каждом сообщении.

Автоматически — только пока поле sessionId доходит до агента во входящем элементе. Если перед агентом стоит нода, которая это поле убирает (например Guardrails), память падает с ошибкой No session ID found. Тогда в поле Session ID выбирают Define below и подают ключ сами — выражением из ноды чата.

У Telegram Trigger поля sessionId нет вовсе — ключ задают сами: Define below, Key = {{ $('Telegram Trigger').item.json.message.chat.id }}; число принимается как есть, у каждого чата своя история (n8n 2.20.7, кухня k1 996–999).

Разные сессии (разные вкладки браузера или разные пользователи) → разные истории диалога.

Когда использовать

• Простой чат-бот с памятью без необходимости сохранять историю между перезапусками n8n
• Быстрое прототипирование агентов с памятью
• Задачи, где история диалога нужна только в рамках одной сессии

<!-- TODO: дописать секцию «Ограничения и альтернативы» (Postgres Chat Memory, Zep) -->

Два режима воркфлоу: Unpublished и Published

В n8n у воркфлоу два состояния. Unpublished — черновик: ты редактируешь и можешь запускать его только вручную через Execute workflow, триггеры молчат. Published — живая версия: триггеры включены, Schedule срабатывает по расписанию, Webhook и Form принимают запросы по Production URL, polling-триггеры (Telegram, Gmail) слушают обновления. Переключает между состояниями кнопка Publish в правом верхнем углу редактора.

Version Name и Describe changes — каждая публикация это новая версия

При нажатии Publish n8n показывает диалог с двумя полями:

• Version Name — обязательное короткое имя версии. Любая строка, по которой ты потом узнаешь эту версию в истории. Хорошие примеры: журнал менеджера добавлен, webhook: новая схема заявки, fix: timezone for cron. Плохие: 123, update, асдф — через неделю ты не поймёшь что в этой версии было.
• Describe changes (опционально) — что именно поменялось с прошлой версии. Это короткий журнал в свободной форме: «добавил Stretch-ветку ai-классификации жалоб», «починил Switch L2 — было kebab-case, стало snake_case». Заполняй обязательно для значимых правок — себе через месяц спасибо скажешь.

Каждая публикация создаёт новую версию workflow. История версий доступна через Versions (рядом с Editor/Executions) — можешь посмотреть какой код был на каждой версии, откатиться на любую из них одной кнопкой Restore. Это и есть встроенный git-подобный version control для воркфлоу.

Sub-Workflow тоже публикуют

Воркфлоу, который вызывается из другого через Execute Workflow Trigger, тоже нужно публиковать. Родитель при вызове берёт последнюю опубликованную версию Sub-WF — если ты внёс правки и не нажал Publish, родитель их не увидит. Управляется той же кнопкой Publish.

Типичные ошибки

• Поправил опубликованный воркфлоу, забыл Publish заново → триггеры исполняют старую версию. После каждой правки — Publish.
• Дёргаешь Production URL у Unpublished воркфлоу → возвращает 404. Либо публикуй, либо открой редактор, нажми Execute workflow и шли на Test URL.
• Хочешь временно остановить воркфлоу → нажми Unpublish. Триггеры замолкают, Production URL перестаёт принимать запросы. Чтобы запустить обратно — снова Publish.

Публичный чат Chat Trigger — Make Chat Publicly Available

Тоггл Make Chat Publicly Available находится в Parameters ноды Chat Trigger. Он превращает встроенный чат в отдельную веб-страницу, доступную по ссылке. Без этого тоггла чат остаётся только внутри редактора n8n.

По умолчанию тоггл выключен. После включения появляются четыре дополнительных поля: Chat URL, Mode, Authentication и Initial Message(s).

Зачем это нужно

Тоггл нужен, когда чат должен работать как публичный интерфейс, а не только для теста внутри n8n. Он открывает доступ к воркфлоу через обычный браузер. До публикации workflow ссылка возвращает 404, поэтому тоггл только готовит адрес, но не делает страницу живой.

Как это работает

После включения тоггла в разделе Parameters раскрываются поля:

• Chat URL — Production-адрес страницы. Работает только после нажатия Publish.
• Mode — выбор между Hosted Chat и Embedded Chat. Подробности в соседней статье.
• Authentication — уровень доступа: None, Basic Auth или n8n User Auth.
• Initial Message(s) — текст первого сообщения бота. По умолчанию стоит стандартное английское приветствие n8n, его меняют на текст своего бота.

Типичные ошибки

• Включил тоггл и сразу открыл Chat URL — получил 404. Нужно нажать Publish, тоггл только готовит адрес.
• Внёс изменения в workflow после публикации — посетители чата не видят обновлений. После каждой правки требуется повторный Publish.
• Оставил Authentication = None и передал URL коллегам — любой, у кого есть ссылка, получает доступ к чату. Для закрытых сценариев ставь Basic Auth.
• Не заменил Initial Message(s) — посетитель видит стандартное английское приветствие n8n вместо текста своего бота.

Два способа показать чат: отдельная страница или виджет

Параметр Mode в ноде Chat Trigger появляется после включения Make Chat Publicly Available. Он решает, как именно пользователи будут открывать чат: через отдельную ссылку или через код на своём сайте.

Hosted Chat отдаёт готовую страницу по адресу из поля Chat URL. Embedded Chat даёт блок кода, который вставляют в HTML своей страницы. Оба режима работают только после нажатия Publish.

Как это работает

Mode находится в секции Parameters ноды Chat Trigger. Доступны два значения:

• Hosted Chat — n8n сам публикует страницу чата по адресу Chat URL. Пользователь переходит по ссылке и сразу видит интерфейс.
• Embedded Chat — n8n показывает блок с тегом <script>. Этот код копируют в HTML своей страницы, и чат появляется как виджет.

До публикации воркфлоу любой из адресов или скриптов возвращает 404. После Publish чат становится доступен в выбранном режиме.

Типичные ошибки

• Включил Mode, скопировал Chat URL или код, но чат отдаёт 404 → не нажал Publish → нажать Publish после любых изменений.
• Выбрал Hosted Chat, а ждёшь виджет в углу своего сайта → Hosted Chat всегда отдаёт отдельную страницу → переключить на Embedded Chat.
• Скопировал код встройки, но не можешь вставить его в HTML → Embedded Chat требует доступа к разметке страницы → выбрать Hosted Chat.
• Изменил Initial Message(s) или другие поля, а в чате старые данные → страница и виджет работают с последней опубликованной версией → нажать Publish заново.
• Embedded Chat не появляется на сайте → браузер блокирует внешний скрипт по CSP → добавить домен n8n в script-src.