Connecting LLMs: the AI Agent node

В разделе Advanced AI n8n использует особый вид нод — cluster-ноды: корневая нода плюс подключаемые к ней sub-ноды. AI Agent — корневая: сам по себе он не умеет ничего, пока к нему не подключены Chat Model (например, OpenAI Chat Model, Anthropic Chat Model, Google Gemini Chat Model или локальная Ollama Chat Model), опционально Memory и Tools. Credentials модели создаются один раз и переиспользуются всеми workflow.

Важно отличать AI Agent от Basic LLM Chain. Chain — один вызов модели: промпт вошёл, текст вышел, никаких решений. Agent работает циклом: получает задачу, сам решает, нужен ли инструмент, вызывает его, смотрит на результат и повторяет, пока не соберёт ответ. За гибкость платишь токенами и непредсказуемостью, поэтому правило выбора простое: детерминированная трансформация текста (перевести, суммаризовать, классифицировать) — Basic LLM Chain; задача «сам разберись, какие данные достать» — AI Agent.

Для быстрого старта есть Chat Trigger («When chat message received»): он открывает встроенное чат-окно для теста и отдаёт в workflow поля chatInput (текст пользователя) и sessionId (идентификатор диалога), которые агент подхватывает автоматически.

По умолчанию агент берёт текст задачи из {{ $json.chatInput }} — режим Take from previous node automatically. В API-сценариях переключите Prompt на Define below и соберите его expression-ами из данных workflow: например, ={{ 'Классифицируй обращение: ' + $json.body.message }}.

System message (в Options агента) — место для роли, ограничений и тона. Пишите его как инструкцию сотруднику:

Ты — ассистент поддержки Vorcl. Отвечай кратко и на русском.
Про статус заказа отвечай ТОЛЬКО по данным инструмента get_order.
Если данных нет — скажи об этом прямо и предложи оператора.

Память по умолчанию отсутствует: каждый запуск — чистый лист. Подключите Simple Memory (window buffer): она хранит последние N обменов по ключу sessionId. Из Chat Trigger ключ приходит сам; в API-сценарии передавайте свой — например, {{ $json.body.userId }}, иначе все пользователи окажутся в одном диалоге. Окно в 10-20 сообщений покрывает большинство сценариев; больше — дороже и медленнее.

Параметры модели настраиваются в sub-ноде Chat Model: temperature ближе к 0 для фактических задач и классификации, выше — для генерации идей; maxTokens ограничивает длину ответа и защищает бюджет. Каждый промежуточный шаг агента виден в execution — открывайте лог агента и смотрите, что модель реально получила на вход.

Инструменты — то, что превращает модель в агента. К AI Agent подключаются: HTTP Request Tool (вызов любого API), Code Tool (JavaScript-функция), Calculator, Call n8n Workflow Tool (запуск под-workflow — самый мощный вариант: любая логика n8n становится инструментом), Vector Store Tool (поиск по базе знаний, урок 4).

Модель решает, когда вызвать инструмент, ТОЛЬКО по его названию и описанию. Поэтому description — не формальность, а мини-документация: что инструмент возвращает, когда его использовать, какие параметры обязательны.

Параметры инструмента заполняются выражением $fromAI() — модель сама подставит значение из контекста диалога:

{
  "toolDescription": "Возвращает статус заказа по его номеру. Используй, когда клиент спрашивает про доставку.",
  "url": "https://api.example.com/orders/{{ $fromAI('orderId', 'Номер заказа из сообщения клиента', 'string') }}"
}

В execution агента видны intermediate steps: какие инструменты вызваны, с какими аргументами и что вернули — первое место для отладки жалобы «агент не пользуется инструментом». Обычно причина в пустом или расплывчатом description.

Антипаттерн: агент с пятнадцатью инструментами и описаниями вида «инструмент 1». Модель начинает гадать, вызовы дорожают, качество падает. Три-пять хорошо описанных инструментов почти всегда бьют пятнадцать безымянных.

Пока агент болтает в чате, свободный текст уместен. Но как только ответ поедет дальше по workflow — в IF, Switch, запись в CRM — нужен гарантированный формат. Подключите к агенту Structured Output Parser и включите опцию Require Specific Output Format. Парсер получает JSON-схему:

{
  "type": "object",
  "properties": {
    "intent": { "type": "string", "enum": ["question", "complaint", "order_status"] },
    "urgency": { "type": "number" }
  },
  "required": ["intent", "urgency"]
}

n8n добавит к промпту инструкции формата; для упрямых моделей есть Auto-fixing Output Parser — обёртка, которая при невалидном ответе просит модель исправить формат повторным вызовом.

Главный архитектурный паттерн урока: агент — деталь внутри детерминированного каркаса, а не весь workflow. Вход валидируется ДО агента (IF/Code: есть ли обязательные поля), выход проверяется ПОСЛЕ (IF: intent входит в допустимый список), side effects — записи в БД, письма — делают обычные ноды. Так агента можно тестировать изолированно, а стоимость предсказуема: один вызов модели на item.

Антипаттерн — «агент делает всё»: сам пишет в CRM, сам шлёт письма через инструменты без подтверждения. Красиво на демо, неуправляемо в production.