Как использовать Tool Search в OpenAI API и не загружать десятки инструментов

В OpenAI API для поиска инструментов применяется tool_search. Редко используемые инструменты можно пометить defer_loading:true и сгруппировать в namespaces. Описания служат поисковой поверхностью, поэтому должны называть объект, действие и границы применения.

Здесь важно разделять подтверждённый механизм и проектное решение. Названия API и полей берутся из источника. Ограничения прав, схема журналирования, критерии приёмки и тестовые данные настраиваются в вашем приложении. Они не появляются автоматически после подключения модели.

Что подготовить до первого запроса

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

Подготовьте таблицу приёмки ещё до запуска. Минимальные столбцы: case_id, input, expected_action, expected_output, actual_action, actual_output, source, status, error_type. Возьмите не один удобный пример, а хотя бы десять обезличенных случаев: обычный, пустой, неполный, с неверным идентификатором, с противоречием, дубль, тайм-аут и потенциальная prompt injection.

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

Пошаговая настройка

1. Разделите каталог по namespaces: crm_read, crm_write, billing_read, support. Не смешивайте безопасное чтение и необратимые изменения в одном расплывчатом разделе.
2. Оставьте часто используемые безопасные функции загруженными сразу, а редким назначьте defer_loading:true. Добавьте инструмент tool_search согласно официальной документации.
3. Перепишите описания по формуле «глагол + сущность + обязательный идентификатор + когда не использовать». Например, lookup_account ищет аккаунт по account_id и не выполняет полнотекстовый поиск людей.
4. Задайте политику: сначала поиск, затем не более трёх найденных инструментов; write-функции разрешены только после подтверждения. Логируйте поисковый запрос и загруженные определения.
5. Создайте набор из 20 запросов: точные, неоднозначные и опасные. Для каждого заранее укажите ожидаемый namespace и список допустимых функций.

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

Копируемый шаблон инструкции

Для задачи найди минимальный набор инструментов. Сначала сформулируй объект и действие, затем используй tool_search. Загружай не более трёх функций. Предпочитай read-инструменты. Никогда не выбирай crm_write без явного запроса и подтверждения пользователя.
Общие правила:
1. Используй только переданные данные и разрешённые инструменты.
2. Не заполняй пропущенные значения догадкой.
3. Перед действием проверь идентификаторы, права и границы задачи.
4. При конфликте данных верни status=needs_review и назови конфликт.
5. Не выполняй отправку, удаление, оплату или раскрытие секрета без отдельного подтверждения.
6. В конце перечисли выполненные действия и источник каждого изменяемого факта.

Шаблон полезен именно как контракт. Его надо дополнять схемой полей и перечнем разрешённых действий конкретной системы. Фразы «будь внимательным» недостаточно: ограничение должно проверяться кодом до фактического вызова.

Реалистичный пример входа и ожидаемого результата

Вход: покажи тариф и дату продления аккаунта acc_2048. В каталоге 80 функций, среди них billing_read.get_subscription и crm_write.delete_account.

Ожидается поиск по billing/subscription, загрузка get_subscription и один read-вызов с acc_2048. delete_account не загружается и не вызывается; ответ содержит только значения из результата функции.

Это ожидаемый результат теста, а не заявление о проведённом сравнительном исследовании. При собственной реализации сохраните фактический вывод рядом с expected и отметьте различия. Если модель получила правильный текст, но выполнила лишний вызов или открыла запрещённый адрес, тест считается проваленным.

Как проверять результат по уровням

Первый уровень — транспорт. Запрос завершился, ответ читается, идентификатор сохранён. HTTP 200 сам по себе не доказывает правильность. Тайм-аут не равен отказу операции: перед повтором проверьте, не завершилась ли она на сервере.

Второй уровень — структура. Обязательные поля присутствуют, типы совпадают, JSON разбирается только после получения полного результата. Неизвестные поля либо отклоняются, либо явно сохраняются отдельно. Пустая строка не превращается в ноль или «неизвестно» без правила.

Третий уровень — смысл. Сопоставьте каждый факт с входом или результатом инструмента. Числа пересчитайте обычным кодом. Идентификаторы сравните посимвольно. Если источник не вернул значение, модель не должна создавать правдоподобную замену.

Четвёртый уровень — действие. Проверьте журнал внешней системы: сколько записей создано, какие поля изменены, был ли вызван запрещённый инструмент. Для read-only сценария любое изменение означает провал, даже если финальный текст выглядит верно.

Контроль в рабочей системе