Как создать AI-агента на Python: цикл, tools и память

AI-агент отличается от одиночного вызова LLM наличием цикла. Модель получает цель и состояние, решает — ответить или вызвать инструмент, приложение выполняет действие и возвращает наблюдение в контекст. Цикл повторяется до финального ответа или лимита шагов.

Минимальная архитектура

Агент состоит из пяти частей:

1. модель, способная запросить tool call;
2. каталог инструментов с именами, описаниями и схемами аргументов;
3. исполнитель, который валидирует аргументы и вызывает разрешённую функцию;
4. состояние: сообщения, результаты инструментов и служебные поля;
5. условия остановки.

Псевдокод цикла:

state = {"messages": [user_message]}

for step in range(MAX_STEPS):
    decision = call_model(state, tools=tool_schemas)
    if decision.final_answer:
        return decision.final_answer

    call = validate_tool_call(decision.tool_call)
    observation = execute_allowed_tool(call)
    state["messages"].append(observation)

raise RuntimeError("Agent step limit exceeded")

LLM предлагает действие, но приложение остаётся контролирующей стороной.

Как описывать инструменты

Хороший tool выполняет одну понятную операцию. Название и описание должны объяснять, когда его использовать, а JSON Schema — ограничивать аргументы. Не создавайте универсальный инструмент run_any_shell_command: модель сможет сделать больше, чем требуется задаче.

Исполнитель должен проверять инструмент по allowlist, валидировать типы, устанавливать timeout и ограничивать объём результата. Для опасных действий — отправки письма, оплаты, удаления — требуется подтверждение пользователя или отдельная политика доступа.

Ошибку инструмента возвращают модели как структурированное наблюдение, но не бесконечно. Например, сетевой запрос можно повторить дважды, а неверный аргумент лучше сразу объяснить модели. Каждый вызов записывают в audit log: кто инициировал, какой tool, какие безопасные аргументы и чем закончился вызов.

Память агента — не обязательно векторная БД. В рамках одного запуска достаточно состояния сообщений. Долгосрочную память добавляют только для конкретной задачи и с правилами удаления данных.

Остановка и тестирование

Без лимитов агент может зациклиться: повторять неуспешный поиск, вызывать два инструмента друг за другом или расходовать токены без прогресса. Минимальные предохранители — MAX_STEPS, общий timeout, бюджет токенов/денег и дедупликация одинаковых вызовов.

Тестировать нужно не только финальный текст. Зафиксируйте сценарии:

• простой вопрос без инструментов;
• правильный выбор tool и аргументов;
• отказ инструмента;
• попытка вызвать запрещённый tool;
• запрос на опасное действие без подтверждения;
• достижение лимита шагов.

Хороший первый агент решает одну узкую задачу с двумя-тремя инструментами. Добавление десятков tools ухудшает выбор модели и расширяет поверхность атаки. Сначала добейтесь предсказуемого цикла, наблюдаемости и безопасной остановки, затем наращивайте автономность.