Как создать ИИ-агента на Python: цикл, инструменты, память

Вы попробовали LangChain, собрали ИИ-агента на Python по примеру – и он заработал, но непонятно почему. Стоит поменять одну деталь, и он то зависает, то отвечает пустой строкой. Где искать причину, за слоями абстракций не видно.

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

Что такое ИИ-агент и почему модель сама ничего не делает

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

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

Отсюда рабочее определение, которым пользуются многие разработчики: агент – это LLM, которая работает в цикле и использует инструменты. Всё, что превращает модель в агента, – обычный код вокруг неё. Его называют обвязкой: она решает, что модель увидит, какие действия ей доступны и когда остановиться.

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

Инструменты: функция, схема и описание

Инструмент складывается из трёх частей:

• обычная функция на Python, которая делает работу: читает файл, обращается к API, считает;
• схема в формате JSON Schema – имя, назначение и параметры;
• словарь, который сопоставляет имя из схемы с функцией, чтобы код нашёл её, когда модель попросит.

Фреймворки вроде LangChain генерируют схемы автоматически. Без фреймворка схему для каждой функции пишете вы – и это не формальность: звать ли инструмент, модель решает по его описанию, и если оно расплывчатое, агент вызовет не то или не вызовет ничего. Пишите описание как для коллеги.

Список инструментов уходит модели при каждом вызове вместе с историей. У разных провайдеров устройство одинаковое: например, в API GigaChat пользовательские функции передаются в запросе отдельным массивом functions с именем и описанием. Пишете агента под российскую модель – механика та же.

Многие советуют давать одному агенту не больше 15–20 инструментов – это мягкий ориентир, а не правило. Меньше – агенту не хватает возможностей. Больше – модель хуже выбирает нужный, а описания занимают заметную часть контекста. Если задач больше, разумнее разделить их между несколькими специализированными агентами.

Как работает ИИ-агент: цикл – сердце всей конструкции

Схема простая: отправить модели историю и список инструментов, посмотреть на ответ. Если в ответе есть запросы на вызов инструментов – выполнить каждый, добавить в историю сам запрос и результат и снова вызвать модель. Если запросов нет, а есть текст, это финальный ответ, и цикл заканчивается.

Число оборотов заранее неизвестно. Простой вопрос решается за один шаг, сложная задача может потребовать 20 или 50 итераций. Поэтому цикл строят на while, а не на фиксированном числе вызовов.

В рабочем варианте к естественному условию выхода добавляют страховку – лимит итераций, например 10 раундов. Без него запутавшаяся модель может вызывать инструменты бесконечно, а вы будете платить за каждый вызов. Дошёл до лимита – агент честно сообщает, что не справился, и предлагает упростить запрос.

Второе обязательное дополнение – обработка ошибок. Упал инструмент – программа падать вместе с ним не должна. Ошибку превращают в обычный результат и возвращают модели, а в системном промпте просят в таком случае объяснить причину и предложить другой путь. Так агент может сам обойти проблему: попробовать другой инструмент или переспросить.

Память: от списка сообщений до файла и векторной базы

Память агента – не отдельная магия, а то, что вы решаете показать модели. Её удобно разложить на три уровня.

Первый уровень у вас уже есть – та самая история сообщений. Но живёт она только в памяти программы: закрыли и открыли снова – и агент уже не помнит, как зовут пользователя.

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

На большом объёме записей этот подход перестаёт работать – файл разрастается и съедает контекст. Тогда переходят к RAG и векторным базам, где в контекст попадают только записи, подходящие к текущему запросу.

Контекст – главный ограниченный ресурс агента

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

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

Перечислим основные приёмы:

• Обрезка истории. Оставлять системный промпт и последние сообщения, а старые отбрасывать. Грубо, но надёжно.
• Субагенты. Технически это отдельный массив контекста и ещё один вызов модели. Шумную подзадачу отдают субагенту, а в основной контекст возвращают только итог.
• Меньше инструментов. Описания тоже расходуют токены, поэтому ориентир не больше 15–20 инструментов на агента работает и здесь.

MCP: подключать или писать инструменты самому

MCP – протокол, через который агент подключает инструменты с внешних серверов. Вокруг него два заметных взгляда.

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

Практический критерий такой. Нужен готовый внешний инструмент, который кто-то уже упаковал в MCP-сервер, – подключайте. Строите агента ради понимания и контроля или вам важно, что именно видит модель, – начните со своих функций. Для модели обе разновидности выглядят одинаково: это просто записи в списке инструментов.

Что добавить перед реальным использованием

Учебный агент и агент, которому можно доверить работу, отличаются несколькими вещами. Главная – права. Инструменты с побочными эффектами, например отправку писем или удаление записей, запускают только после подтверждения человеком, а чтение и вычисления можно оставить автоматическими.

• Цикл на while с выходом, когда модель вернула текст без вызовов инструментов
• Лимит итераций, например 10 раундов, и понятное сообщение при его достижении
• Ошибки инструментов возвращаются модели как результат, а не роняют программу
• В системном промпте сказано, что делать при ошибке инструмента
• Опасные операции – только после подтверждения человека
• У каждого инструмента – точное описание, всего их не больше 15–20
• История обрезается или шумные подзадачи уходят субагентам

Ключевые термины

• Обвязка агента (harness) – Код вокруг языковой модели – цикл, инструменты, память, управление контекстом, – который превращает её в агента.
• Схема инструмента – Описание функции в формате JSON Schema – имя, назначение и параметры, – по которому модель понимает, как её вызвать.
• Агентный цикл – Повторяющийся шаг «вызвать модель → выполнить запрошенные инструменты → вернуть результат», который идёт, пока модель не даст финальный ответ.
• Окно контекста – Ограниченное число токенов, которые модель видит за один вызов: история, описания инструментов и их результаты.
• MCP (Model Context Protocol) – Открытый протокол, по которому агент подключает инструменты с внешних серверов и находит их во время работы.
• Субагент – Отдельный вызов модели со своим массивом контекста, которому поручают подзадачу, чтобы не засорять основной контекст.

Итог

Агент – это LLM в цикле с инструментами, а всё остальное вы пишете сами: схемы, цикл, память и правила работы с контекстом. Создание ИИ-агента удобно вести в таком порядке: вызов модели с историей, затем один-два инструмента со схемами, цикл с условием выхода и лимитом, память в файле и, наконец, управление контекстом. Сложное начинается не с кода, а с вопроса, что модель видит на каждом шаге. Поэтому, когда агент снова зависнет или ответит пустой строкой, начинайте отладку не с промпта, а с истории сообщений, которую он получил.

Проверьте себя

1. Агент сделал один вызов инструмента, после чего вы сразу запросили финальный ответ – и он оказался пустым. В чём наиболее вероятная причина?

• А. Инструмент вернул слишком мало данных
• Б. Модель сломалась и надо сменить провайдера
• В. Модель хотела вызвать ещё один инструмент, а цикла, который это позволяет, нет

2. Как агент понимает, что задача решена и из цикла пора выйти? (Верных ответов несколько.)

• А. Прошло 5 секунд
• Б. Достигнут заранее заданный лимит итераций
• В. Модель вернула текст и не запросила ни одного инструмента
• Г. Модель вызвала инструмент ровно один раз

3. Вы перезапустили программу, и агент забыл имя пользователя. Что поможет проще всего?

• А. Увеличить температуру модели
• Б. Дать агенту инструмент сохранения в файл и подставлять этот файл в системный промпт при старте
• В. Ничего: модель должна помнить пользователя сама

4. Вы дали агенту 40 инструментов, и он стал чаще выбирать не тот. Что разумно сделать?

• А. Добавить ещё инструментов на всякий случай
• Б. Сократить набор до 15–20 инструментов или разделить на нескольких специализированных агентов
• В. Убрать у инструментов описания, чтобы сэкономить токены

5. Какому инструменту нужно подтверждение человека перед запуском? (Верных ответов несколько.)

• А. Запрос погоды
• Б. Отправка письма клиенту
• В. Подсчёт выражения калькулятором
• Г. Удаление записи в базе