Как создать ИИ-агента: агентный цикл, архитектурные паттерны и первый рабочий сценарий

ИИ-агент — это программа, в которой языковая модель (LLM) выбирает следующий шаг к цели, получает результат инструмента и решает, продолжать работу, остановиться или передать решение человеку. Инструменты бывают и у чат-бота: агента отличает именно этот цикл принятия решений. От обычного скрипта агент отличается тем, что последовательность шагов не прописана в коде заранее.

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

Три термина, на которых держится остальной текст:

Из чего состоит ИИ-агент

Агент — программный конвейер, а не текстовая настройка в чате: код-оркестратор собирает контекст из базы знаний и результатов инструментов, отправляет его модели и исполняет ее решения.

Модель. Удобнее строить агента на LLM с поддержкой вызова инструментов (function calling): без нее запрос на вызов приходится выпрашивать промптом и разбирать из свободного текста. Еще пригодятся устойчивая работа с длинным контекстом и рассуждение, которое видно в логах, — так агента проще отлаживать. Внутри одного агента нередко работает несколько моделей: мощная строит план, легкая вызывает инструменты, отдельная оценивает результат.

Инструменты. Агент передает модели описание каждого инструмента: имя, назначение, параметры в виде JSON-схемы. Модель возвращает не действие, а структурированный запрос на вызов — какую функцию вызвать и с какими аргументами; точный формат зависит от API. Клиентский инструмент исполняет уже приложение, то есть код агента, и в этой точке находится контроль. Размытое описание без схемы дает разный результат от запуска к запуску.

Память. Ее делят на два слоя:

• краткосрочная — история диалога с ролями сообщений: системный промпт, пользователь, модель, инструмент;
• долговременная — то, что переживает сессию: факты о пользователе, база знаний.

Краткосрочная память растет на каждом шаге, и ее сокращают одним из трех способов:

1. Отрезать старое — агент забудет то, что было в начале.
2. Сжать историю в резюме.
3. Вынести ее во внешнее хранилище и доставать поиском.

Для хранения обычно хватает привычной СУБД. Историю можно держать в PostgreSQL, а расширение pgvector добавить, если нужен векторный поиск по смыслу. Расход токенов считают отдельно — это учет стоимости, а не часть памяти. Данные разных пользователей изолируют.

Ограничения. Принцип — запрещено все, что не разрешено явно. Критические действия (изменение настроек, выкатка, удаление) агент не выполняет сам, а готовит отчет и ждет подтверждения человека (human in the loop). Секреты не кладут в промпт и командную строку.

Агентный цикл: как агент доходит до результата

На примере агента для работы с кодом цикл выглядит так:

1. Получить цель и ограничения.
2. Собрать минимальный контекст, например структуру проекта.
3. Составить план безопасных действий.
4. Вызвать инструменты: чтение, поиск, правка, команда.
5. Проверить результат: тесты, линтер, сверка с требованиями.
6. Остановиться, запросить решение человека или пойти на новый круг.

На каждом круге к контексту добавляется вывод инструмента, следующий запрос к модели длиннее, а модели тарифицируют по токенам. Ответ модели вероятностный: запросы с разницей в одно слово могут пройти разной траекторией и по разной цене.

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

Скелет цикла в коде

Это учебный скелет, а не готовый агент: он показывает, где стоят лимит шагов, детектор петель и подтверждение опасного действия. Ответ модели имитирует функция fake_llm, поэтому ключи API и библиотеки не нужны. Схемы аргументов инструментов и обработка исключений опущены ради краткости. Проверено на Python 3.9.6, 22.10.2026.

import json

def search_order(order_id: str) -> str:
    return {"1042": "передан в доставку"}.get(order_id, "заказ не найден")

def cancel_order(order_id: str) -> str:
    return f"заказ {order_id} отменен"

# имя -> (функция, нужно ли подтверждение человека)
TOOLS = {"search_order": (search_order, False), "cancel_order": (cancel_order, True)}

def fake_llm(history):
    """Имитация ответа модели."""
    if history[-1]["role"] == "user":
        return {"tool": "search_order", "args": {"order_id": "1042"}}
    return {"answer": "Статус заказа: " + history[-1]["content"]}

def run_agent(task, llm=fake_llm, max_steps=5):
    history = [{"role": "user", "content": task}]
    seen = set()
    for _ in range(max_steps):
        decision = llm(history)
        if "answer" in decision:
            return decision["answer"]
        name, args = decision["tool"], decision["args"]
        key = (name, json.dumps(args, sort_keys=True))
        if key in seen:
            return "Остановка: повторный вызов с теми же аргументами"
        seen.add(key)
        if name not in TOOLS:
            return "Остановка: неизвестный инструмент " + name
        func, needs_approval = TOOLS[name]
        if needs_approval and input(f"Выполнить {name}? [y/N] ").strip().lower() != "y":
            return "Остановка: действие не подтверждено"
        history.append({"role": "tool", "content": func(**args)})
    return "Остановка: исчерпан лимит шагов"

print(run_agent("Где мой заказ 1042?"))

В консоли появится Статус заказа: передан в доставку: на первом шаге имитация модели просит вызвать search_order, на втором видит результат и отвечает. Если имитация всегда просит один и тот же вызов, агент остановится на втором шаге, а cancel_order без ответа y не выполнится.

Чтобы подключить настоящую модель, fake_llm заменяют функцией, которая отправляет в API историю и описания инструментов со схемами аргументов, а полученный запрос на вызов переводит в словарь вида {"tool": ..., "args": ...}. Формат истории и ролей тоже придется привести к требованиям API. Дальше добавляют проверку аргументов по схеме, обработку исключений инструментов и лог шагов. Детектор в скелете ловит только точные повторы.

Как выбрать архитектурный паттерн

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

Пример для ReAct — доставить человека из Москвы в Краснодар на любом транспорте: агент проверяет самолет, если билетов нет — поезд, если билет нашелся — оценивает цену и бронирует. Каждый шаг зависит от предыдущего.

Если сомневаешься, разумная отправная точка — ReAct с лимитом шагов: он подходит большинству задач, хоть и не всегда оптимально. Отходить от него стоит по признакам задачи. Длинный план, который по ходу может устареть, — повод посмотреть на Plan-and-Execute. План, не зависящий от промежуточных наблюдений, — на ReWOO. Независимые вызовы при важном времени ответа — на LLMCompiler. Дорогая ошибка — повод добавить шаг оценки. В каждом случае выигрыш подтверждают на своих сценариях, а не по названию паттерна. Chain-of-Thought в этот список не входит: это прием промпта для рассуждения по шагам, а не архитектура агента.

Когда нужен не один агент, а несколько

Агенту с десятком инструментов бывает трудно выбрать нужный, а неоднородную задачу, где одна часть планируется, а другая нет, плохо решает один паттерн. Тогда задачу декомпозируют: один агент только бронирует билеты, другой планирует поездку в целом. Жесткого порога здесь нет, и сначала стоит проверить, не хватит ли одному агенту более точных описаний инструментов.

Узкая роль может снизить число галлюцинаций за счет ограниченного контекста, перекрестная проверка агентов вскрывает нюансы, а простые подзадачи можно отдать дешевой модели. В команде агентов для разработки полезна отдельная роль ревьюера, который сверяет артефакты остальных и ищет противоречия.

Два распространенных варианта взаимодействия — координатор (supervisor), который раздает задачи и собирает результаты, и передача управления между агентами (network), когда агенты сами вызывают друг друга. Бывают и другие схемы, например иерархия координаторов. Размер системы сам по себе схему не выбирает: решают маршрутизация и контроль. Если каждый переход нужно видеть и проверять в одной точке, удобнее координатор; если маршрут естественно идет от агента к агенту, проще передача управления.

Цена мультиагентности — обмен контекстом. Каждому агенту дают то, что нужно для его подзадачи: цель, ограничения, результаты предыдущих этапов. Если этого не сделать, агент заново собирает сведения, а это лишние вызовы и токены; общая долговременная память тоже помогает. Ошибка, не пойманная на одном этапе, усиливается на следующих, поэтому результат проверяют на каждом стыке между агентами.

Свой код, фреймворк или no-code

Реализовать агента можно тремя путями:

В разработке ИИ-агентов без высокой нагрузки фреймворк — частый рабочий выбор: типовой цикл и память уже собраны, а свой код оправдан там, где важны каждый вызов и его цена. Имена функций в библиотеках меняются между версиями, поэтому код из старых туториалов сверяй с документацией. Проектирование и программирование агентов разбирают на курсе «Разработка ИИ-агентов».

Как выбрать первую задачу и поставить ее агенту

Хорошая первая задача повторяется, имеет ясные входы и выходы, проверяется локально и не требует необратимых действий. Плохие кандидаты — управление релизом, выкатка в прод, разовые задачи, задачи с неясным контекстом, секретами и платежами.

Перед стартом ответь на пять вопросов:

1. Что на входе?
2. Что на выходе?
3. Чем подтверждается результат?
4. Что агенту запрещено?
5. Когда он обязан остановиться?

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

Разница не в длине. Во второй постановке названы источники истины, разрешенные действия, запреты, способ проверки, формат результата и точка остановки.

От учебного скелета к первому рабочему сценарию ведут пять шагов:

1. Выбрать задачу по критериям выше.
2. Описать один-три инструмента со строгими схемами аргументов.
3. Подключить модель вместо fake_llm и собрать ReAct-цикл с лимитом шагов и подтверждением опасных действий.
4. Запускать агента на копии проекта или в отдельной ветке и вести лог шагов.
5. Сравнить результат с ручным на нескольких примерах.

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

Выводы

Коротко о главном:

• ИИ-агент — это код вокруг LLM: цикл, инструменты, память и ограничения. Модель выбирает следующий шаг и предлагает вызов, исполняет его программа.
• Поддержка вызова инструментов в модели упрощает работу: запрос на вызов приходит структурированным, а не разбирается из текста.
• Паттерн выбирают по задаче и проверяют на своих сценариях: ReAct — когда шаг зависит от предыдущего, Plan-and-Execute — когда длинный план может потребовать пересмотра, ReWOO — когда план можно составить до результатов инструментов, LLMCompiler — когда часть вызовов можно выполнить параллельно.
• Несколько агентов имеют смысл, когда одному трудно выбирать среди многих инструментов или задача неоднородна. Каждому дают нужный контекст, а результат проверяют на каждом стыке.
• Первая задача — повторяющаяся, проверяемая и обратимая, с лимитом шагов и подтверждением критических действий человеком.

Где применяются ИИ-агенты на практике

Первых агентов чаще всего ставят на разработку и тестирование, поддержку по базе знаний и разбор алертов — туда, где задача повторяется, а результат можно проверить. Внедрение агентов в рабочие процессы разбирают на курсе «ИИ-агенты: продвинутое внедрение и использование». Посмотреть, как агентов собирают вживую, можно на бесплатных вебинарах — открытые уроки Otus.

Смежные темы: RAG-агент для автоматизации инцидент-менеджмента, Что такое искусственный интеллект, Нейросети: как работают и где применяются.

FAQ

Можно ли собрать агента на локальной модели?
Да, если модель поддерживает вызов инструментов. Окно контекста для агента обычно увеличивают, а с ним растет потребность в памяти сверх той, что занимают веса модели. Точный расход зависит от модели и конфигурации, поэтому ограничением чаще становится видеопамять или ОЗУ.

Обязательно ли подключать RAG?
Нет. RAG — один из способов подложить модели документы. Если ответы должны опираться на внутреннюю базу знаний, поиск по ней обычно подключают как отдельный инструмент.

Зачем писать своего агента, если есть готовые агенты для программирования?
Для работы с кодом своего писать не нужно: готовые агенты в IDE и терминале уже читают файлы и прогоняют тесты. Свой нужен для предметной задачи со своими системами и правилами остановки.