Как написать своего AI-агента: пошаговый гайд

Слово «AI-агент» звучит так, будто за ним стоит сложная система, доступная только большим командам. На деле рабочий агент — это довольно понятная конструкция: языковая модель, набор инструментов и цикл, который связывает их вместе. Если вы уже пробовали обращаться к модели через API, до собственного агента остаётся один шаг. В этом гайде разберём по шагам, как спроектировать и собрать агента, который не просто отвечает текстом, а выполняет действия: ищет данные, вызывает функции, работает с вашими системами и сам решает, что делать дальше.

Чем агент отличается от обычного запроса к модели

Обычный вызов модели — это «вопрос-ответ»: вы отправляете промпт, получаете текст, на этом всё заканчивается. Агент устроен иначе. Он получает цель, а не конкретную инструкцию, и сам выстраивает путь к ней: решает, какие данные нужны, вызывает инструменты, оценивает результат и повторяет цикл, пока задача не будет закрыта. Ключевое отличие — автономность в рамках заданных границ и возможность влиять на внешний мир через инструменты.

Если это разграничение пока кажется размытым, стоит начать с основ — мы подробно разбирали его в заметке «Что такое AI-агент простыми словами». Здесь же будем считать, что с понятием вы знакомы, и сосредоточимся на практике сборки.

Из чего состоит агент: цикл «контекст → действие → проверка»

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

Чтобы этот цикл заработал, агенту нужны четыре составляющие.

Модель — «мозг»

Модель принимает решения: какой инструмент вызвать, с какими аргументами, когда остановиться. От её качества напрямую зависит, насколько разумно агент планирует шаги. Для сложных многошаговых задач берут более мощные модели (уровня Claude Opus, GPT или Gemini старших версий), для простых и частых операций — модели полегче и подешевле.

Инструменты — «руки»

Сама по себе модель умеет только генерировать текст. Всё, что выходит за эти рамки — поиск в базе, отправка письма, запрос к API, запись в файл — она делает через инструменты. Технически это описанные функции, которые модель может вызвать, вернув структурированный запрос. Механику мы разбирали отдельно в материале «Tool calling: как ИИ вызывает инструменты» — это фундамент, без которого агента не собрать.

Память и контекст

Окно контекста модели ограничено, а задачи бывают длинными. Поэтому агенту нужна память: краткосрочная (история текущего диалога) и долгосрочная (факты, которые нужно помнить между запусками). Часто долгосрочную память реализуют через поиск по вашим данным — подход, который в мире ИИ называют RAG. Как он устроен, мы объясняли в заметке «Что такое RAG простыми словами».

Оркестрация — цикл, который всё связывает

Последний элемент — это код, который получает ответ модели, исполняет запрошенный инструмент, возвращает результат обратно в модель и повторяет всё заново. Именно оркестрация превращает набор компонентов в работающего агента.

Шаг 1. Сформулируйте задачу и границы

Начинать стоит не с кода, а с точного описания того, что агент должен делать. Ответьте себе на три вопроса: какую конкретную задачу он решает, какими инструментами для этого будет пользоваться и где проходят границы его полномочий. Хороший агент — узкий: «отвечает на вопросы клиентов по базе знаний и заводит тикет, если не знает ответа» гораздо реалистичнее, чем «ведёт всю поддержку». Чем уже задача, тем предсказуемее поведение и проще отладка.

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

Шаг 2. Выберите модель и способ доступа

Дальше нужен доступ к модели. У большинства провайдеров это API-ключ и несколько строк кода для первого запроса. Если вы ещё не проходили этот этап, у нас есть пошаговые инструкции: по Claude API и по OpenAI API. Принципиально важно, что для агента модель должна поддерживать вызов инструментов (function/tool calling) — это умеют все актуальные модели ведущих провайдеров.

На старте не гонитесь за самой мощной моделью. Соберите прототип на средней, убедитесь, что логика работает, и уже потом решайте, где нужна модель посильнее, а где можно сэкономить.

Шаг 3. Опишите инструменты

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

Типичный минимальный набор для практического агента: поиск по данным (например, база знаний или каталог), обращение к внешнему API и какое-то действие с побочным эффектом — создание записи, отправка уведомления. Начните с двух-трёх инструментов и наращивайте по мере необходимости.

Шаг 4. Соберите цикл агента

Сердце агента — цикл оркестрации. В упрощённом виде на псевдокоде он выглядит так:

сообщения = [системная_инструкция, задача_пользователя]

повторять (не более N раз):
    ответ = модель(сообщения, доступные_инструменты)

    если ответ содержит вызов инструмента:
        результат = выполнить_инструмент(вызов)
        добавить в сообщения: вызов и его результат
        продолжить цикл
    иначе:
        вернуть ответ  # агент закончил

Логика простая: пока модель просит вызвать инструмент, мы исполняем его и возвращаем результат обратно; как только модель отвечает обычным текстом без вызовов — задача решена. Ограничение N на число итераций обязательно: оно не даёт агенту зациклиться, если он «застрял». В системную инструкцию имеет смысл заложить описание роли агента, правила и напоминание проверять результат перед завершением — качество этой инструкции сильно влияет на поведение, и здесь пригодятся приёмы из заметки «Промпт-инжиниринг: практические приёмы».

Шаг 5. Добавьте память

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

Шаг 6. Подключите внешние системы через MCP

Когда инструментов становится много, а интеграции повторяются от проекта к проекту, писать их вручную под каждый агент неэффективно. Здесь помогает стандарт MCP (Model Context Protocol) — общий протокол, через который агент подключается к внешним сервисам: файлам, базам, CRM, мессенджерам. Вместо своей обёртки под каждый API вы используете готовый MCP-сервер, и агент получает набор инструментов «из коробки». Что это за серверы и как выбрать подходящий, мы разбирали в обзоре MCP-серверов. Для типовых интеграций это заметно ускоряет разработку.

Фреймворк или с нуля?

Собрать цикл агента вручную полезно хотя бы раз — так вы понимаете, что происходит внутри. Но для реальных проектов есть готовые фреймворки и SDK (например, OpenAI Agents SDK, Claude Agent SDK, LangGraph, CrewAI), которые берут на себя оркестрацию, память, параллельные под-агенты и обработку ошибок. Они экономят время, но добавляют свой слой абстракций, в которых тоже нужно разбираться.

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

Шаг 7. Тестирование и оценка

Агента нельзя проверить одним запуском: из-за вероятностной природы модели один и тот же вход иногда даёт разные пути решения. Поэтому нужен набор тестовых сценариев — типичных задач с ожидаемым результатом, которые вы прогоняете при каждом изменении промпта или инструментов. Для оценки применяют несколько подходов: строгие правила (проверка формата ответа, факт вызова нужного инструмента), сравнение с эталоном и «LLM-as-judge», когда качество ответа оценивает другая модель. Логируйте каждый шаг цикла — какие инструменты вызывались и с какими аргументами: без такой трассировки отлаживать поведение агента практически невозможно.

Безопасность: главное, что нельзя откладывать

Агент действует в реальном мире, поэтому ошибка или злоупотребление стоят дороже, чем у обычного чат-бота. Три базовых принципа. Первый — минимум прав: агент получает доступ только к тем действиям, которые ему действительно нужны, а необратимые операции требуют подтверждения человека. Второй — защита от промпт-инъекций: данные, которые агент читает извне (письма, страницы, документы), могут содержать скрытые инструкции, и модель способна принять их за команду. Как это работает и как защищаться, разобрано в заметке «Промпт-инъекция: что это и как защититься». Третий — журналирование: все действия агента должны фиксироваться, чтобы их можно было проверить. Общий взгляд на риски есть в материале «Безопасность ИИ для бизнеса».

Частые ошибки новичков

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

Вывод

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