Рабочий процесс n8n с подтверждением человеком, OpenAI-совместимым API и валидацией JSON Schema

Решение: подтверждайте действие, а не только извлечение данных

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

Поэтому надёжная архитектура n8n использует три этапа контроля:

1. Извлечение: OpenAI-совместимое API возвращает структурированные данные.
2. Валидация: n8n проверяет соответствие данных JSON Schema.
3. Подтверждение: AI Agent в n8n может вызвать значимый инструмент только после подтверждения человеком.

Это не позволяет некорректным данным попасть к проверяющему и отделяет подтверждённое выполнение от вывода модели.

OneMux предоставляет доступ к ведущим моделям ИИ через единый OpenAI-совместимый API. Его можно использовать как маршрут доступа к модели, если документация эндпоинта и выбранной модели подтверждает поддержку формата запроса и параметров, необходимых для вашей конфигурации n8n. В этой статье не утверждается, что интеграция OneMux и n8n тестировалась.

Предварительные требования

Вам понадобятся:

• Экземпляр n8n с доступом к узлам HTTP Request, Code и, если применимо, AI Agent.
• Канал подтверждения, поддерживаемый вашей конфигурацией n8n, например n8n Chat, Slack, Telegram, электронная почта или другой документированный канал.
• Доступ к OpenAI-совместимому API. При использовании OneMux начните с краткого руководства OneMux и проверьте актуальный эндпоинт, способ аутентификации, идентификаторы моделей и поддерживаемые параметры запроса в документации OneMux.
• JSON Schema, описывающая объект, который вы хотите извлечь.
• Инструмент назначения, например обновление CRM или отправка сообщения, который не должен запускаться без проверки человеком.

Не следует считать, что каждый OpenAI-совместимый эндпоинт поддерживает все возможности структурированного вывода. Проверьте поддержку response_format, JSON Schema, вызовов инструментов и выбранной модели. Каталог моделей OneMux поможет ознакомиться с доступными вариантами моделей, но сам по себе не доказывает поддержку конкретной конфигурации узла n8n.

Рекомендуемый рабочий процесс n8n

Практический рабочий процесс может использовать следующие узлы:

1. Webhook или другой триггер получает исходный текст.
2. HTTP Request отправляет текст на эндпоинт совместимой модели.
3. Code разбирает и проверяет возвращённый объект.
4. IF направляет некорректные результаты в ветку ошибки или ручной корректировки.
5. AI Agent получает проверенный объект и доступ к значимому инструменту.
6. Проверка человеком приостанавливает рабочий процесс перед запуском этого инструмента.
7. Подтверждённый инструмент записывает данные или отправляет сообщение.

В запросе на извлечение следует запрашивать только те поля, которые нужны рабочему процессу. Компактная схема для обращения в службу поддержки может выглядеть так:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["category", "priority", "summary", "customer_email"],
  "properties": {
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "account", "other"]
    },
    "priority": {
      "type": "string",
      "enum": ["low", "normal", "high", "urgent"]
    },
    "summary": {
      "type": "string",
      "minLength": 1
    },
    "customer_email": {
      "type": "string",
      "format": "email"
    }
  }
}

Настройка OpenAI-совместимого запроса

В узле HTTP Request используйте базовый URL и инструкции по аутентификации из документации провайдера. Не указывайте URL, специфичный для провайдера, без предварительной проверки его корректности для вашей учётной записи и региона.

Приведённая ниже структура запроса носит иллюстративный характер. Поддержка response_format и его структуры JSON Schema зависит от выбранных эндпоинта, модели и конфигурации n8n.

{
  "model": "YOUR_DOCUMENTED_MODEL_ID",
  "messages": [
    {
      "role": "system",
      "content": "Extract the requested fields. Do not guess missing values. Return only an object matching the supplied schema."
    },
    {
      "role": "user",
      "content": "{{$json.source_text}}"
    }
  ],
  "temperature": 0,
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "support_request",
      "strict": true,
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["category", "priority", "summary", "customer_email"],
        "properties": {
          "category": {"type": "string"},
          "priority": {"type": "string"},
          "summary": {"type": "string"},
          "customer_email": {"type": "string"}
        }
      }
    }
  }
}

В примере намеренно используется идентификатор модели-заполнитель. Выберите модель, для которой в документации указана совместимость с выбранным эндпоинтом. Если строгий вывод по JSON Schema недоступен, используйте поддерживаемый JSON-режим только в том случае, если ваш путь валидации может безопасно отклонять ответы, не соответствующие схеме. Один лишь JSON-режим не равнозначен валидации по схеме.

Проверка ответа перед выполнением

Провайдеры могут помещать сгенерированный контент в разные поля. Перед написанием парсера изучите один реальный ответ в n8n. Следующий узел Code предполагает, что модель вернула строку JSON в message.content; измените путь в соответствии с фактически получаемым ответом.

const raw = $json.choices?.[0]?.message?.content;

if (typeof raw !== 'string') {
  throw new Error('Model response did not contain message.content as a string');
}

let extracted;
try {
  extracted = JSON.parse(raw);
} catch (error) {
  throw new Error('Model returned invalid JSON');
}

const required = ['category', 'priority', 'summary', 'customer_email'];
const missing = required.filter((key) => extracted[key] === undefined || extracted[key] === '');

const validCategory = ['billing', 'technical', 'account', 'other'].includes(extracted.category);
const validPriority = ['low', 'normal', 'high', 'urgent'].includes(extracted.priority);
const validEmail = typeof extracted.customer_email === 'string' &&
  /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(extracted.customer_email);

if (missing.length || !validCategory || !validPriority || !validEmail) {
  throw new Error('Extracted object failed application validation');
}

return [{ json: { extracted } }];

Для промышленного использования замените эту упрощённую проверку на поддерживаемый валидатор JSON Schema там, где это позволяет ваше развёртывание n8n. Схема в запросе и схема, применяемая при валидации, должны иметь совместное версионирование. Добавьте версию схемы в результат, если последующим системам нужно различать редакции.

Добавление подтверждения человеком для инструмента AI Agent

Используйте проверенный объект как контекст для AI Agent. Предоставьте Agent узко определённый инструмент, например CreateSupportTicket, вместо широкого доступа к базе данных. Настройте проверку человеком для выбранного инструмента в Tools Panel AI Agent.

В документации n8n указано, что рабочий процесс приостанавливается, когда Agent пытается использовать инструмент, требующий проверки. Проверяющий может подтвердить вызов, разрешив инструменту выполниться с предложенными входными данными, или отклонить его, отменив действие. n8n поддерживает несколько каналов подтверждения, включая встроенный интерфейс чата и интеграции со Slack, Telegram, Discord, Teams, электронной почтой, WhatsApp, Google Chat и Outlook email. Актуальные шаги настройки и сведения о каналах см. в официальной документации n8n по human-in-the-loop.

Полезное сообщение на подтверждение должно показывать предлагаемое действие и параметры:

The AI wants to use {{ $tool.name }} with the following parameters:
{{ JSON.stringify($tool.parameters, null, 2) }}

В исходной документации для этого контекста проверки указаны $tool.name и $tool.parameters. Сделайте сообщение понятным и добавьте исходный запрос или ссылку на обращение, если проверяющему нужен дополнительный контекст.

Системный промпт Agent также должен объяснять поведение при проверке:

The CreateSupportTicket tool requires human approval. If approval is denied, do not retry automatically. Tell the user that the action was not completed and explain what information or correction is needed.

Ограничения и устранение неполадок

Модель возвращает Markdown или дополнительный текст

Проверьте, поддерживает ли эндпоинт отправленные вами параметры структурированного вывода. Если нет, удалите неподдерживаемые параметры, уточните инструкцию и оставьте валидацию в узле Code обязательным барьером. Никогда не отправляйте непроверенный объект в инструмент записи.

n8n не может найти ожидаемое поле ответа

Изучите результат работы HTTP Request и обновите парсер. OpenAI-совместимые API могут использовать общие соглашения для запросов, но различаться деталями ответов и поддерживаемыми параметрами.

Запрос на подтверждение слишком расплывчатый

Используйте узко определённый инструмент и добавьте $tool.name вместе с $tool.parameters в сообщение на подтверждение. Не просите проверяющего подтвердить непрозрачную инструкцию вроде «обработать этот запрос».

Отклонённый вызов инструмента приводит к циклу

Добавьте в системный промпт Agent явное поведение при отклонении и настройте рабочий процесс так, чтобы после отклонения путь действия завершался или направлялся на уточнение. В документации n8n рекомендуется объяснить, какие инструменты требуют подтверждения и как Agent должен отвечать на отказ.

Проверяющие подтверждают некорректные данные

Соответствие схеме не доказывает семантическую корректность. Показывайте вместе фрагмент источника, извлечённые поля и предполагаемое действие. Для рабочих процессов с высоким воздействием требуйте, чтобы проверяющий самостоятельно подтвердил чувствительные поля.

Заключение

Самый безопасный шаблон n8n для структурированного извлечения — не «позволить модели записывать данные напрямую». Извлекайте данные в ограниченный объект, проверяйте его, а затем размещайте подтверждение человеком перед инструментом, который изменяет внешний мир. OpenAI-совместимое API может упростить доступ к моделям, а n8n предоставляет средства оркестрации и контроля подтверждений. При использовании OneMux применяйте документированный совместимый эндпоинт и параметры модели, проверяйте конфигурацию в собственной среде и рассматривайте неподдерживаемые возможности структурированного вывода как причину остановиться или перейти на отдельно проверяемый путь обработки ответа.