TNWS AI

Гайд · TNWS AI

Как обработать invalid_final_output в OpenAI Agents SDK

WindowsmacOSLinuxWeb#нейросети#API#OpenAI Agents SDK
8 мин—

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

Что вы настроите и когда это полезно

Практическая задача этого руководства — безопасно завершить запуск, если финальный ответ модели не прошёл валидацию объявленного output_type. Сценарий полезен не сам по себе, а как часть проверяемого приложения: после выполнения должен существовать машинно проверяемый признак успеха. Мы не оцениваем результат «на глаз» и не подменяем тест красивым ответом модели.

Сведения и названия API сверены 12 сентября 2026 года по официальной документации OpenAI Agents SDK: первоисточник. В статье намеренно нет цен, региональных обещаний и неподтверждённых лимитов: они не требуются для этого сценария. Если ваша установленная версия расходится с документацией, сначала зафиксируйте версию и воспроизведите минимальный пример в отдельном окружении.

Подтверждённый контракт

  • Точный ключ обработчика — invalid_final_output.
  • Эта ветка предназначена для ошибки финальной валидации, а не для произвольного сетевого сбоя.
  • Fallback обязан соответствовать тому же output_type, который объявлен у агента.
  • Обработчик не повторяет модельный запрос и не переигрывает побочные эффекты уже выполненных tools.
  • Возврат None означает отказ от восстановления: исходная ошибка продолжит распространяться.

Эти пункты — граница решения. Не расширяйте её предположениями. Например, успешный HTTP-код не всегда означает нужное бизнес-состояние, а наличие строки в ответе не доказывает, что сработал правильный обработчик. В следующих шагах для каждого утверждения есть отдельная проверка.

Что подготовить

  • изолированное тестовое окружение, где можно безопасно вызвать описанный API;
  • актуальную версию пакета или приложения и возможность посмотреть её локально;
  • тестовые данные без секретов, персональных сведений и реальных платёжных реквизитов;
  • лог или счётчик, позволяющий отличить модельный вызов, tool execution и локальную проверку;
  • автоматический тест, который завершается ненулевым кодом при несовпадении ожидаемых полей.

Не помещайте API-ключи в код, prompt, traceback или публикуемый лог. В примерах, где ключ вообще требуется, он должен поступать из переменной окружения. Для локального Ollama ключ обычно не является частью показанного HTTP-контракта; не добавляйте фиктивную авторизацию.

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

  1. Опишите финальную структуру через Pydantic и задайте её в output_type агента.
  2. В обработчике проверьте тип ошибки, затем создайте консервативный объект того же класса. Не заполняйте неизвестные данные правдоподобными догадками.
  3. Верните RunErrorHandlerResult(final_output=typed_fallback). Для аудита сохраните признак needs_review=True внутри бизнес-схемы.
  4. В тесте заставьте модель или тестовый provider вернуть невалидный ответ и проверьте тип final_output, а не только текст.

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

Минимальный воспроизводимый пример

Скопируйте пример в отдельный файл. Он специально содержит проверки assert или явные throw: при нарушении контракта процесс не должен продолжать работу как будто всё успешно.

from pydantic import BaseModel
from agents import Agent, RunErrorHandlerInput, RunErrorHandlerResult, Runner

class OrderSummary(BaseModel):
    order_id: str | None
    status: str
    needs_review: bool

agent = Agent(
    name="order_reader",
    instructions="Извлеки сводку заказа. Не выдумывай поля.",
    output_type=OrderSummary,
)

def invalid_output(data: RunErrorHandlerInput[None]):
    return RunErrorHandlerResult(
        final_output=OrderSummary(
            order_id=None, status="validation_failed", needs_review=True
        ),
        include_in_history=False,
    )

result = Runner.run_sync(
    agent,
    "Заказ 781, статус в исходнике отсутствует",
    error_handlers={"invalid_final_output": invalid_output},
)
assert isinstance(result.final_output, OrderSummary)
assert result.final_output.needs_review is True

Если пример написан на JavaScript, сохраните его как .mjs и запустите современной версией Node.js с глобальным fetch. Python-пример запускайте в том же virtualenv, где установлен тестируемый SDK. Не смешивайте версии из глобального и проектного окружений.

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

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

Ожидаемый результат: OrderSummary(order_id=None, status="validation_failed", needs_review=True). Номер не переносится в fallback автоматически: обработчик не должен притворяться повторным парсером.

Зафиксируйте ожидаемый результат буквально в тесте. Не сравнивайте весь естественно-языковой ответ модели, если контракт выражается типом или отдельным полем. Для недетерминированного текста проверяйте структурный инвариант; для API — HTTP-код и обязательные JSON-поля; для последовательности — порядок событий.

Негативный тест

Верните из обработчика обычную строку при output_type=OrderSummary. Проверка должна выявить несовпадение контракта. Затем верните None и убедитесь, что исходная ошибка не маскируется.

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

Готовый prompt для ревью

Этот prompt не исполняет настройку вместо кода. Он помогает проверить пропущенные условия после того, как вы приложили конфигурацию и вывод тестов.

Сделай ревью fallback для invalid_final_output: перечисли каждое поле output_type, источник его значения и риск выдумывания. Если значение не подтверждено, предложи явный sentinel и флаг ручной проверки.

Ответ верни таблицей: условие, доказательство из кода или лога, статус PASS/FAIL, минимальное исправление. Не додумывай отсутствующие версии, поля или результаты. Если доказательства нет, ставь FAIL.

Как пользоваться prompt

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

Независимая проверка результата

Проверка должна выполняться на двух уровнях. Первый — локальный контракт: функция возвращает правильный тип, JSON содержит точные поля, callback сохраняет порядок. Второй — наблюдаемое состояние системы: модель не была вызвана до валидации, tool не исполнился до approval, либо модель появилась или исчезла в контрольном списке.

Запишите таблицу тестов с колонками «вход», «ожидаемая ветка», «наблюдаемый признак», «фактический результат». Минимум нужны успешный сценарий, намеренно ошибочный сценарий и пограничный ввод. Если есть side effects, используйте fake tool или sandbox. Повторный запуск теста не должен создавать заказ, платёж или удаление.

Не делайте вывод по одному скриншоту интерфейса: он не показывает порядок внутренних событий и быстро устаревает. Предпочтительны вывод unit-теста, сериализованный ответ API и счётчик обращений тестового provider-а.

Типичные ошибки и исправления

Проверяется только отсутствие исключения

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

Комментарий принимают за гарантию

Фраза «здесь tool не вызывается» ничего не доказывает. Подставьте fake tool, увеличивающий счётчик, и сравните его после запуска. То же относится к model stub и callback.

В тест попадают реальные побочные эффекты

Для approval, retry и восстановления ошибок используйте заглушки. Повторяемый модельный запрос и повторяемый платёжный tool — разные риски. Сначала докажите порядок локально, затем выполняйте ограниченную интеграционную проверку.

Версия молча отличается

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

Чек-лист финальной проверки

  • Задача сформулирована как наблюдаемый результат, а не как «получить хороший ответ».
  • Имена классов, параметров, ключей и endpoint сверены с официальным первоисточником 12 сентября 2026 года.
  • В коде нет токенов, персональных данных и реальных реквизитов.
  • Успешный тест проверяет точный тип, поле, порядок или состояние.
  • Негативный тест действительно активирует противоположную ветку.
  • Model stub и fake tool считают обращения, если порядок имеет значение.
  • Побочные эффекты не повторяются из-за retry или восстановления.
  • Логи не используются как единственное доказательство, если доступна программная проверка.
  • Ограничения и несовместимость версий описаны явно.
  • Перед production-запуском тест повторён в том же окружении зависимостей.

Ограничения

Этот гайд подтверждает конкретный технический контракт, но не качество ответа нейросети, безопасность всей системы и не соответствие вашей организации нормативным требованиям. Настройки SDK и API меняются. Дата проверки указана выше; при обновлении зависимости снова откройте первоисточник и прогоните оба теста.

Также пример не задаёт универсальные таймауты, лимиты денег или объём памяти. Такие числа зависят от инфраструктуры и бизнес-риска. Используйте измерения собственного стенда, но не публикуйте их как свойства продукта без воспроизводимой методики.

FAQ

Нужно ли указывать цену или тариф?

Нет. Для этого сценария цена не меняет проверяемый контракт. Если вы добавляете стоимость в собственную документацию, сверяйте официальный pricing в день публикации и указывайте валюту, единицу тарификации и дату.

Почему нельзя ограничиться ручной проверкой?

Ручной результат легко принять за успех неправильной ветки. Автоматический assert или throw повторяем и обнаруживает регрессию после обновления SDK, модели или сервера.

Что сохранять в CI?

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

Что делать при расхождении с документацией?

Сначала воспроизведите минимальный пример без фреймворка приложения. Зафиксируйте версию и полный текст ошибки без секретов. Затем проверьте документацию именно этой версии; не маскируйте расхождение универсальным try/except.

Первоисточник

Читайте также

ГайдыWindowsmacOS12 сентября 2026

Как проверять агента в терминале через REPL OpenAI Agents SDK

Запускаем run_demo_loop, проверяем многошаговый контекст и streaming, составляем сценарий ручной приёмки и отделяем REPL от автоматических тестов.

7 мин 
ГайдыWindowsmacOS12 сентября 2026

Как исправить ошибку reasoning item ID в OpenAI Agents SDK

Разбираем reasoning_item_id_policy=omit: когда удалять ID из переносимой истории, какие входы политика не меняет и как проверить исправление Responses API 400.

7 мин 
ГайдыWindowsmacOS12 сентября 2026

Как настроить lifecycle hooks в OpenAI Agents SDK для аудита вызовов

Подключаем RunHooks и AgentHooks, считаем вызовы модели и инструментов, не записываем секреты и проверяем порядок событий агентного запуска.

7 мин 

Подбор

Какую нейросеть выбрать

Пройти опрос

Комментарии

Пока тихо. Скажите первое слово