Как настроить Async Tool Calling в OpenAI API для долгих операций

Async Tool Calling предназначен для инструментов, результат которых появляется не сразу. Надёжная интеграция отделяет принятие задания от его завершения и связывает продолжение с устойчивым идентификатором операции.

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

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

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

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

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

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

1. Создайте функцию start_report(period, department, idempotency_key), которая быстро возвращает job_id и статус queued. Ключ идемпотентности строится на стороне приложения и повторно используется при сетевом повторе.
2. Опишите асинхронный инструмент по официальной схеме. Не обещайте модели мгновенный результат: явно укажите возможные состояния queued, running, completed и failed.
3. Сохраните связь response_id, tool_call_id, job_id и пользователя в транзакции. Без этой таблицы поздний результат легко присоединить не к тому диалогу.
4. Получайте статус контролируемым опросом или внутренним событием. Применяйте экспоненциальную задержку и конечный дедлайн; не опрашивайте очередь в бесконечном цикле.
5. После completed передайте результат в продолжение исходного ответа. При failed передайте структурированную ошибку с retryable и не просите модель скрыть сбой.

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

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

Если для ответа нужен месячный отчёт, вызови start_report ровно один раз. Пока статус queued или running, скажи, что отчёт готовится, без выдуманных цифр. После completed сверь period и department в результате. При failed объясни причину и разрешай повтор только если retryable=true.
Общие правила:
1. Используй только переданные данные и разрешённые инструменты.
2. Не заполняй пропущенные значения догадкой.
3. Перед действием проверь идентификаторы, права и границы задачи.
4. При конфликте данных верни status=needs_review и назови конфликт.
5. Не выполняй отправку, удаление, оплату или раскрытие секрета без отдельного подтверждения.
6. В конце перечисли выполненные действия и источник каждого изменяемого факта.

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

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

Вход: подготовь отчёт отдела Support за август 2026. Первый вызов возвращает job_id=rpt_731, queued; через 40 секунд статус completed и 1 842 обработанных обращения.

Ожидается один job с тем же idempotency_key, промежуточное сообщение без цифр и финальная сводка, где значение 1 842 взято из результата rpt_731. Повторный webhook не создаёт вторую публикацию.

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

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

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

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

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

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

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