Что такое ИИ-агент изнутри: собираем цикл ReAct на Python без фреймворков

Паттерн ReAct (от reasoning + acting, «рассуждение плюс действие») лежит в основе почти каждого агентного фреймворка. Но сами фреймворки оборачивают его в десятки абстракций, и разработчик теряет понимание, что именно происходит между запросом к модели и, например, чтением файла на диске. Разбор ниже опирается на пошаговое объяснение цикла без единого фреймворка: только Python, JSON и HTTP-запрос к API.

Что понадобится?

• Python 3.10+ и умение запускать скрипт из терминала
• API-ключ DeepSeek (регистрация на platform.deepseek.com, работает из России напрямую)
• Базовое понимание JSON и HTTP-запросов
• Около 40 минут свободного времени
• Текстовый редактор или IDE (VS Code, PyCharm, любой привычный)

Фреймворки вроде LangChain или CrewAI здесь не нужны. Весь агент собирается из трёх файлов.

Пошаговая инструкция

1. Разберитесь, чем агент отличается от обычного запроса к модели.

В простом приложении вы отправляете модели вопрос и показываете ответ. Если для решения нужны данные из файла, приложение само читает его заранее и вкладывает содержимое в промпт. Модель через текстовое API не получает доступа к вашей файловой системе.

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

Ключевое: последовательность шагов не прописана заранее. Вы задаёте агенту набор доступных инструментов и ограничения, а модель решает, что вызывать, по ходу работы.

2. Опишите инструменты для модели.

Чтобы модель могла запросить инструмент, в API передают его имя, назначение и схему аргументов в формате JSON. Схема описывает допустимые данные, но не содержит саму Python-функцию.

Пример описания инструмента чтения файла:

{
  "type": "function",
  "function": {
    "name": "read_file",
    "description": "Читает содержимое файла по указанному пути",
    "parameters": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Путь к файлу"
        }
      },
      "required": ["path"]
    }
  }
}

Для инструмента запуска команд в терминале (Bash) схема аналогична: обязательный аргумент command и необязательный timeout.

3. Соберите три компонента агента в коде.

Реализация состоит из трёх элементов:

• DeepSeekClient отправляет запрос к API и получает ответ
• Agent управляет историей сообщений и циклом «запрос к модели, выполнение инструмента, новый запрос»
• Классы инструментов (каждый в отдельном файле) выполняют конкретные операции: читают файл, запускают команду в терминале

4. Постройте цикл ReAct.

Вот как работает один оборот цикла:

• Агент отправляет модели список messages (системный промпт (начальная инструкция, задающая роль и ограничения модели), задачу пользователя, всю предыдущую историю) и список доступных инструментов.
• Модель возвращает ответ. Если в нём есть массив tool_calls, значит, модель запросила действие.
• Агент читает имя инструмента и аргументы, проверяет, что такой инструмент есть в списке допустимых, и вызывает его.
• Результат оформляется как сообщение с ролью tool и полем tool_call_id, которое связывает результат с конкретным вызовом.
• Агент добавляет и запрос модели, и результат инструмента в историю messages, затем снова обращается к модели.

Один ответ модели может содержать несколько вызовов. Агент обрабатывает их последовательно.

5. Задайте условия остановки.

Агент проверяет каждый ответ модели. Если есть запросы инструментов, цикл продолжается. Если модель вернула текст без новых вызовов, агент принимает его как финальный ответ.

Обязательно задайте лимиты:

• Максимум обращений к модели (в примере из источника: до 8)
• Максимум вызовов инструментов (до 16)

Если лимит исчерпан, а финального ответа нет, попытка завершается ошибкой. Отдельно: таймаут Bash-команды не останавливает весь цикл, а возвращает модели сообщение об ошибке, и она может выбрать другой шаг.

6. Помните, кто за что отвечает.

Модель выбирает действие. Агент решает, выполнять ли его. Инструмент делает работу. Граница безопасности проходит именно по агенту: инструкция в промпте «не меняй тесты» помогает модели принять верное решение, но реальный запрет на запись должен быть в коде и в правах файловой системы.

Что делать с этим прямо сейчас?

Автору Дзена. Понимание того, что такое ИИ-агент изнутри, позволяет не просто «пользоваться ChatGPT», а собрать помощника, который сам читает ваши черновики, проверяет факты по файлам и предлагает правки. Начните с двух инструментов: чтение файла и запуск команды.

Маркетологу. Агентный цикл ReAct можно применить для автоматической проверки посадочных страниц: агент читает HTML, запускает тест скорости, находит проблемы и предлагает исправления. Всё без фреймворков и подписок на платформы.

Предпринимателю в РФ. DeepSeek API работает из России напрямую, без VPN и прокси. Это один из немногих способов построить агента на внешней модели без обходных путей. Из российских аналогов для экспериментов подходят YandexGPT и GigaChat, но поддержка tool_calls в их API на момент публикации ограничена: проверяйте документацию.

Соберите минимального агента из трёх файлов, прогоните на одном падающем тесте и посмотрите историю messages целиком. Именно в этой истории видно, как модель «думает» и почему выбирает каждый следующий шаг. Когда вы один раз увидите этот цикл в сыром виде, любой агентный фреймворк станет прозрачным.