ReAct-агент¶
Агент решает задачи по шагам: находит нужные файлы, читает код, вызывает инструменты, проверяет результат и повторяет цикл до завершения. Мысли и итоговый ответ он пишет на языке вашего вопроса; в ответе называет изменённые файлы и как их запустить.
Бесплатно агент работает в режиме чтения: находит ошибку и объясняет её. В Pro он сам правит файлы и проверяет правки тестами.
В приложении¶
Агент работает в чате: отдельной страницы и меню у него нет. Режимы включаются под полем ввода страницы «Чат», настройки — в «⚙ Настройки чата» вверху справа.
| Элемент | Что делает |
|---|---|
| Ctrl+Enter | Разово отправить сообщение агенту (Enter — обычный чат). Состояние чипов не меняется |
| Чип «Агент: файлы» | Пока включён, каждое сообщение выполняет агент с доступом к записи файлов (эквивалент --write; Pro или пробные правки). Без чипа агент только читает |
| Чип «План» | Агент составляет нумерованный план и не изменяет файлы |
| ⚙ Настройки чата → Агент | «Макс. итераций» (1–50, по умолчанию 15); в Pro — флажок «Без лимита» |
| ⚙ Настройки чата → Git: … | Git-инструменты агента: инициализировать репозиторий, работать без git или включить обратно (подробнее) |
| Стоп | Прервать выполнение |
Шаги рассуждений и вызовы инструментов появляются в ответе по мере работы; под
ответом — строка вида [агент | 6 итер. | тесты пройдены].
Режим плана¶
- Включите чип «План» и опишите задачу.
- Агент изучит проект в режиме чтения и ответит нумерованным списком шагов.
- Под ответом появится «▶ Выполнить план». Нажмите — агент получит задачу «Реализуй план: …» и выполнит её. Запись файлов при этом разрешена, только если включён чип «Агент: файлы».
План можно сначала обсудить или поправить новым запросом в режиме плана: выполняется всегда последний.
Без лимита итераций (Pro)¶
Флажок «Без лимита» в «⚙ Настройки чата» снимает ограничение на число шагов:
агент работает, пока не вызовет finish. Его по-прежнему останавливают
кнопка «Стоп», блокираторы циклов и жёсткий потолок в 200 итераций.
Защита от бесполезных циклов¶
- Повтор того же действия с теми же аргументами, если с тех пор ничего не изменилось, не выполняется.
- Блокиратор бесполезных циклов: если инструмент завершился ошибкой два раза подряд (даже с разными аргументами), агент получает предупреждение, а третья попытка в этом запуске блокируется — нужно сменить подход или завершить ответом. Успешный вызов сбрасывает счётчик. На автоматическую проверку тестами перед завершением блокиратор не действует.
- Остановка застрявшего запуска: если четыре шага подряд ничего не выполнили (повтор уже сделанного действия или попытка вызвать заблокированный инструмент), запуск завершается с объяснением. Так бывает у небольших моделей; помогает назвать в задаче конкретный файл или функцию либо выбрать модель побольше.
Каким Python запускаются тесты¶
run_tests запускает pytest интерпретатором проекта, а не программы. Порядок
выбора:
FLUXION_TEST_PYTHON— путь к интерпретатору, если файл существует;- виртуальное окружение проекта:
.venv,venvилиenvв его папке; - при запуске из исходников — интерпретатор, которым запущен Fluxion;
- в собранной программе — первый интерпретатор, в котором есть pytest:
сначала системный
python/pyиз PATH (заглушка Microsoft Store пропускается), затем окружение обучения Fluxion (%LOCALAPPDATA%\Fluxion\training_env). Если pytest нет нигде, Fluxion ставит его в своё окружение обучения — системный Python не трогается.
Если pytest в выбранном окружении нет, агент сообщит путь интерпретатора.
Установите pytest в venv проекта (.venv\Scripts\python -m pip install pytest)
или укажите другой Python в FLUXION_TEST_PYTHON.
Запуск¶
❯ /agent Fix the failing test in tests/test_parser.py
❯ /agent --write Add docstrings to all public functions in utils.py
Без флага --write агент только читает
Запись файлов (write_file, edit_file) и git_commit доступны только с
--write (Pro). git_status и git_diff работают и в режиме чтения.
В CLI лимит шагов задаётся --iter N (по умолчанию 50).
Инструменты¶
| Инструмент | Описание |
|---|---|
list_files |
Список файлов проекта (папка или glob, например **/*.py) |
read_file |
Прочитать файл; длинные файлы читаются по диапазону строк |
grep |
Поиск по регулярному выражению во всех текстовых файлах |
search_code |
Поиск по смыслу в проиндексированном проекте (RAG) |
write_file |
Создать/перезаписать файл |
edit_file |
Точечное редактирование |
run_tests |
Запустить pytest |
web_search |
Веб-поиск: встроенный или SearXNG, если включён |
git_status |
Статус рабочего дерева |
git_diff |
Показать изменения |
git_commit |
Закоммитить изменённые агентом файлы |
finish |
Завершить задачу |
search_code доступен, когда проект проиндексирован (страница «Проект» или
/index). Агент видит только результаты из текущего проекта; если индекс собран
по другой папке, он предложит переиндексировать.
Формат вызова инструментов¶
С бэкендами llama.cpp и Ollama агент по умолчанию работает в режиме
структурированных вызовов: каждое действие — JSON-объект, а JSON-схема
компилируется в грамматику, так что модель физически не может выдать
некорректное действие (пропущенный путь, выдуманный инструмент, обрывки
Observation: в файлах).
{"thought": "Исправлю оператор.", "tool": "edit_file", "path": "calc.py",
"old": " return a - b", "new": " return a + b"}
| Переменная | Значение |
|---|---|
FLUXION_AGENT_FORMAT |
auto (по умолчанию), json или text (классический ReAct) |
FLUXION_API_STRUCTURED=1 |
Включить JSON-схему для API-бэкенда (только если провайдер поддерживает response_format: json_schema) |
Если бэкенд отклоняет схему (например, Ollama старше 0.5), агент автоматически переключается на текстовый формат в том же запуске. Понимаются оба формата ответа, поэтому переключение безопасно.
Git safety¶
- Auto-checkpoint — перед первой записью агент делает снимок рабочей папки
(
refs/fluxion/checkpoints/), не трогая ваши незакоммиченные файлы - Rollback —
/rollbackв CLI возвращает проект к состоянию до агента, включая удаление созданных им файлов - Commit из агента — коммитятся только файлы, изменённые агентом;
.envи ключи не коммитятся никогда
API¶
curl -X POST http://localhost:8765/api/agent/run \
-H "Content-Type: application/json" \
-d '{"task": "Fix the failing test", "allow_write": true}'
Подробнее — в API reference.