Схемы инструментов (Tools & JSON Schema)

1. Обзор концепции и системная проблема

Представьте, что вы пригласили нового помощника в офис и сказали ему: «Вот тут у нас есть специальная программа, пользуйся ею». Но не объяснили, какие кнопки что делают и какие поля нужно заполнять. Конечно, помощник растеряется.

Чтобы языковая модель знала, какими цифровыми инструментами она обладает, разработчики передают ей Схему инструментов (Tool Schema).

Это компактное описание, составленное по стандарту JSON Schema:

• Название (Name): короткое имя кнопки (например, book_hotel).
• Описание (Description): зачем нужна это действие человеческими словами.
• Параметры (Parameters): какие данные нужны для запуска (город, дата заезда, количество гостей).

Ментальная модель: должностная инструкция для ИИ: список инструментов на поясе мастера с четким описанием, когда использовать молоток, а когда отвертку.

2. Как выглядит реальная схема инструмента

{
  "name": "calculate_mortgage",
  "description": "Рассчитывает ежемесячный платеж по ипотечному кредиту.",
  "parameters": {
    "type": "object",
    "properties": {
      "loan_amount": {
        "type": "number",
        "description": "Полная сумма кредита в гривнах, например 1500000"
      },
      "years": {
        "type": "integer",
        "description": "Срок кредита в годах от 1 до 30"
      },
      "interest_rate": {
        "type": "number",
        "description": "Годовая процентная ставка в процентах, например 7.5"
      }
    },
    "required": ["loan_amount", "years"]
  }
}

3. Четыре золотых правила составления хорошей схемы

1. Пишите описание так, будто объясняете стажеру: укажите не только что делает инструмент, но и когда его НЕ следует вызывать.
2. Приводите примеры в поле описания: «формат даты строго YYYY-MM-DD, например 2026-05-18».
3. Ограничивайте варианты с помощью enum: если статус заказа может быть только трех видов, пропишите строго: ["pending", "shipped", "delivered"].
4. Отмечайте обязательные поля в массиве required: если функция не может работать без email клиента, не позволяйте модели запускать ее вслепую.

4. Практические инженерные сценарии в продакшене

01. Интеграция с внешним API

Используйте схемы инструментов для автоматизации вызовов внешних API, обеспечивая строгую валидацию входных данных.

02. Обработка пользовательских запросов

Создайте систему, которая обрабатывает запросы пользователей, используя схемы для определения необходимых параметров и их типов.

03. Генерация документации

Автоматически генерируйте документацию для API, основываясь на схемах инструментов, чтобы обеспечить актуальность и точность.

5. Подводные камни, типовые ошибки и безопасность

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