Как я победил галлюцинации, заменив AGENTS.md на AGENTS.db

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

Изначально я попытался создать полноценный end-to-end граф в LangGraph. Но постоянно возникали неожиданные баги из-за внешних факторов: отсутствующие PDF, невозможность найти статьи, ошибки парсинга, 503 ошибки или сломанный JSON. Казалось, что придётся писать отдельного агента-кодера только для обработки этих крайних случаев.

Решение

Вместо мастер-воркфлоу я переключился на создание CLI-инструментов, которые может использовать агент-кодер.

• Настройка: Запуск qwen3.6:35b через Ollama внутри обвязки PI coding agents, работающей в Docker-песочнице.
• Поток: Каждый файл — это узел (шаг или целый воркфлоу для достижения конкретного результата), и агент выполняет их один за другим.

Если что-то ломается, я предусмотрел 3 уровня исправлений:

1. Уровень 1 (авто): Агент вручную делает работу (например, находит недостающий URL).
2. Уровень 2 (авто): Агент обнаруживает краткосрочный повторяющийся паттерн и пишет скрипт для него.
3. Уровень 3 (человек в цикле): Если агент находит баг в моих CLI-инструментах, он помечает его, предлагает исправление и останавливается, чтобы сохранить чистоту кода — ждёт моего одобрения перед редактированием.

Архитектура памяти

Не зная о стандартных соглашениях именования AGENTS.md, я изначально выбрал такую конфигурацию:

• instructions.md: информировал агента о всём воркфлоу, архитектуре и том, как его выполнять.
• memory.md: постоянная кросс-сессионная память агента, в основном хранящая, с какими багами/проблемами он столкнулся и как их исправил.
• workflow_checkpoints.db: SQLite3 база данных, используемая как временное хранилище для воркфлоу, которая позже переносится в PostgreSQL (используется нашим Django-приложением) после проверок качества для изоляции продакшена.

Проблема

Агент начинал правильно, но когда доходило до миграции данных заметок в базу Django, всё ломалось. У меня был CLI-инструмент migrate.py, который агент мог вызывать (упомянутый в instructions.md), но он начинал использовать встроенный Python, делал синтаксические ошибки, мигрировал данные с битым форматированием, а иногда полностью пропускал миграцию некоторых таблиц.

После нескольких неудач я внёс следующие изменения:

1. Добавил шаг планирования.
2. Полностью переключил слой памяти на agents.db.

Вот схема базы:

Новая настройка движка

• Таблица instructions полностью заменила instructions.md. Она даёт агенту изолированные пошаговые инструкции с чёткими целями, конкретными действиями, доступными CLI-инструментами и чётким определением успеха.
• Таблица memories содержит опыт прошлых запусков: что сломалось и как это исправили.

Я предварительно заполнил таблицу memories всем, что пошло не так в предыдущих запусках, и тем, что агент должен был сделать в этих случаях, используя синтетические воспоминания.

Поток выполнения

Агенту было поручено проходить шаг за шагом по таблице instructions. Для каждого шага он запрашивает таблицу memories (просто получая tldr) как краткую сводку: что нужно сделать, как это сделать и что может пойти не так. Если он сталкивается с новой проблемой, просто добавляет её в memories.

Эти изменения позволили мне аудитировать, что агент намеревается сделать (план), и вставлять исправления, если нужно. Это позволило иерархически запрашивать инструкции и баги и полностью устранило предыдущие проблемы.

Дополнительные рекомендации

Хотя я просто попросил агента читать базу данных (сказав, когда это делать), более надёжный способ — отредактировать саму обвязку, чтобы она вставляла правильные инструкции и воспоминания, экономя больше токенов на SQL-запросах на каждом шаге.

Налог на гибкость

Использование обвязки PI coding agents в качестве оркестратора добавляет гибкости, но делает всё слишком непредсказуемым. Несмотря на то, что поток в основном иерархический, я теперь застрял на том, что прошу его выполнить полный прогон, ловлю галлюцинации и обновляю memories...