Schema для AI tools в n8n: как задать безопасный контракт для агента ¶

Обновлено: 2026-05-29

Короткий ответ ¶

Schema для AI tool — это контракт между агентом и workflow. Она должна объяснять не “что примерно можно сделать”, а какие параметры допустимы, какие поля обязательны, какие значения запрещены и что произойдёт после вызова tool. Хорошая schema уменьшает hallucination tool calls: агент реже придумывает лишние параметры, не отправляет свободный текст туда, где нужен enum, и не получает доступ шире, чем требуется задаче.

Schema — это не prompt ¶

Prompt описывает роль агента, а schema описывает интерфейс действия. Нельзя компенсировать слабую schema длинной инструкцией вроде “пожалуйста, не ошибайся и передавай правильные поля”. Модель всё равно может сгенерировать лишний параметр, неверный статус или опасное действие.

Сравнение:

Признаки плохой схемы ¶

Плохая tool schema обычно выглядит удобно, но опасно:

{
  "action": "string",
  "data": "object",
  "comment": "string"
}

Проблемы:

• action может стать чем угодно: delete, refund, send;
• data не ограничивает поля;
• нет ID сущности;
• нет идемпотентного ключа;
• нет причины действия;
• невозможно сделать нормальную validation;
• reviewer не понимает риск.

Для AI tools лучше использовать узкие действия. Один tool — одна понятная операция.

Пример хорошей схемы ¶

Для tool, который создаёт черновик ответа в тикете:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["ticket_id", "reply_body", "category", "confidence", "source_ids"],
  "properties": {
    "ticket_id": {
      "type": "string",
      "description": "Внутренний ID тикета из trigger payload"
    },
    "reply_body": {
      "type": "string",
      "minLength": 20,
      "maxLength": 2500,
      "description": "Черновик ответа клиенту без отправки"
    },
    "category": {
      "type": "string",
      "enum": ["billing", "technical", "access", "other"]
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    },
    "source_ids": {
      "type": "array",
      "items": {"type": "string"},
      "minItems": 1
    }
  }
}

Даже такую схему надо проверять отдельным node: schema помогает модели, но не заменяет серверную валидацию.

Naming: как агент понимает tool ¶

Название tool должно быть глаголом и объектом, а не абстракцией:

Описание tool должно включать границы:

Creates a draft reply in the support ticket. It does not send the reply to the customer.
Use only when the user question is understood and at least one source_id supports the answer.

Так агенту проще выбрать правильный tool и не использовать write-операцию для read-only задачи.

Required fields и enum ¶

Обязательные поля должны быть не “для красоты”, а для контроля workflow. Для большинства AI tools полезны:

• external_id или ticket_id — чтобы не потерять item;
• action_reason — короткое объяснение;
• confidence — численный сигнал для gate;
• source_ids — источники для RAG/ответов;
• idempotency_key — если tool создаёт или меняет данные;
• dry_run — если есть тестовый режим;
• requires_human_review — если agent сам видит риск.

Enum снижает расползание значений: high|normal|low лучше, чем свободный текст “очень срочно”.

Разделяйте read и write tools ¶

Не делайте один tool manage_customer, который может и читать, и обновлять клиента. Разделите:

• get_customer_profile;
• list_customer_orders;
• create_customer_note;
• update_customer_status.

Read tools можно разрешать шире. Write tools должны иметь валидацию, audit log и иногда human approval.

Версионирование схемы ¶

Schema меняется: добавляются поля, меняются enum, появляются новые правила. В production полезно хранить версию:

{
  "schema_version": "2026-05-29",
  "tool_name": "create_reply_draft",
  "ticket_id": "T-1001"
}

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

• сравнивать ошибки до/после изменения;
• воспроизводить старые executions;
• не ломать replay;
• понимать, какой prompt и schema дали плохой output.

Валидация после AI ¶

После tool call проверьте:

1. JSON валиден;
2. нет дополнительных полей;
3. ID существует в исходном payload;
4. enum входит в allowlist;
5. строки не превышают лимит;
6. source IDs реально были retrieved;
7. write-действие имеет idempotency_key;
8. dangerous action уходит на approval.

Если проверка не прошла, не чините всё молча. Одна repair-попытка допустима, но после повторной ошибки лучше отправить на review.

FAQ ¶

Можно ли использовать одну универсальную schema для всех tools?
Лучше нет. Универсальная схема почти всегда превращается в action + data, а это сложно валидировать и безопасно ревьюить.

Schema гарантирует правильный tool call?
Нет. Она повышает вероятность правильного формата, но final gate должен быть в workflow: validation, allowlist, approval и логирование.

Что важнее: enum или description?
Оба важны. Enum ограничивает варианты, description помогает агенту выбрать правильное значение.