Запускаемый пример для курса «Устройство агентов» и подготовки к проекту разбора инцидентов. Агент получает готовый дифф, находит определение applyDiscount(), читает вызывающий код и запускает одну фиксированную проверку. Результатом становится замечание с основаниями и журнал инструментов.
Задача взята из урока «Исследование источника данных». Изменение подставляет код скидки в SQL, а вызывающая функция передаёт значение из параметра запроса. Проверка с кодом, содержащим апостроф, воспроизводит отказ. Исходники небольшие, SQLite работает в памяти, отдельного сервера или аккаунта GitHub для запуска не требуется.
Реализации на Python и TypeScript используют официальный OpenAI Agents SDK, одну задачу и одинаковый формат результата. Выберите знакомый язык. SDK ведёт агентный цикл. Код примера ограничивает инструменты и проверяет результат по данным запуска. Учебные уроки разбирают механизм цикла по частям, этот репозиторий показывает законченный запуск на готовом SDK.
Нужны Node.js 26 для подготовленной проверки приложения и среда выбранного языка. TypeScript запускается самой Node.js. Для Python нужны Python 3.14 и uv. Версии инструментов объявлены в mise.toml, зависимости закреплены lock-файлами.
Для TypeScript выполните команды из корня репозитория.
make setup
make demoДля Python выполните другой вариант команд из того же каталога.
make setup AGENT_LANG=python
make demo AGENT_LANG=pythonВ режиме demo модель заменена подготовленной последовательностью ответов. SDK Runner, чтение файлов и проверка SQLite выполняются. Этот режим работает без ключа и показывает механику вызовов, обоснованность вывода настоящей модели он не измеряет. Результаты сохраняются в var/typescript.json и var/python.json. Сокращённый вывод обеих реализаций лежит в examples/ с пометкой demo.
Скопируйте конфигурацию и заполните её локально.
cp .env.example .envЗадайте MODEL_ID и OPENAI_API_KEY. Затем запустите выбранную реализацию.
make run
make run AGENT_LANG=pythonДля совместимого Chat Completions API задайте MODEL_API=chat_completions, MODEL_BASE_URL, MODEL_ID и MODEL_API_KEY. Модель и API должны поддерживать инструменты и структурированный результат. Возможности разных провайдеров проверяются отдельно. Ключи не добавляйте в Git. Отправка трейсов SDK во внешний сервис отключена.
В режиме live модель сама выбирает поиск и чтение исходников. Порядок её действий может отличаться от демонстрационного. Полный проход с настоящей моделью требует настроенного API-доступа.
В отчёте есть mode, status, findings, check и trace. Каждое замечание указывает путь, строку, объяснение и диапазоны исходников, на которые оно опирается. Код проверяет формат отчёта, фактический запуск проверки и то, что указанные диапазоны прочитаны. Правильность объяснения читатель оценивает по исходникам и журналу.
Значения status=success и check.passed=false совместимы. Задачей агента служит исследование дефекта. Подготовленная проверка падает на дефекте, и агент объясняет этот результат. Изменять или исправлять приложение пример не умеет.
Список доступных инструментов фиксирован.
| Инструмент | Результат |
|---|---|
read_diff |
Подготовленный дифф |
list_files |
Список файлов задачи |
search_files |
Не более 20 совпадений подстроки в исходниках и тестах |
read_file |
До 40 строк файла с адресом диапазона, offset начинается с нуля |
run_check |
Результат одной заданной команды проверки приложения |
Чтение ограничено каталогом fixture/. Произвольных команд, записи файлов и внешней публикации среди инструментов нет. Число обращений к модели, число инструментов, время и объём выдачи ограничены. При отказе CLI сохраняет статус, доступный журнал и причину остановки.
Начните с fixture/task.txt и fixture/change.diff. Затем откройте реализацию агента на выбранном языке. В agent.ts или agent.py находятся объявления инструментов, инструкции, выбор модели и вызов SDK. В workspace.ts и workspace.py находятся исполнение инструментов и проверка ссылок. В demo-model.ts и demo_model.py находятся только подготовленные ответы для демонстрации.
В учебном проекте эти же роли сохранятся. К инструментам исследования добавятся исправление, проверка кандидата и публикация PR. Копировать подготовленный ответ демонстрационной модели в настоящий workflow не требуется.
Для проверки обеих реализаций установите оба набора зависимостей.
make setup-all
make checkТесты проходят через настоящий SDK Runner. Они проверяют работу инструментов, предел шагов, запрет выхода из каталога и ссылок на непрочитанные данные. Тесты самого примера проходят. Подготовленный дефект проверяется отдельно командой make fixture-check, она ожидаемо завершается с ошибкой и сообщает об одном упавшем тесте.
Дополнительные проверки форматов, ссылок и workflow описаны в hk.pkl. Команда mise run check вызывает весь набор. Хуки можно установить командой hk install.
Hexlet поддерживает этот учебный пример. Код распространяется под лицензией MIT.