AI-агент с нуля: пошаговый гайд

Чат-бот отвечает на вопросы. Агент решает задачи. Это фундаментальное различие, которое определяет следующую эру разработки. AI-агент не просто генерирует текст — он планирует, использует инструменты, проверяет результаты и итерирует до тех пор, пока задача не решена. В этом гайде мы разберём архитектуру агента с нуля и покажем, как собрать своего.

Чат-бот — это stateless система «вопрос-ответ». Вы спрашиваете — он отвечает. Каждое сообщение обрабатывается изолированно (или с минимальным контекстом окна чата). Чат-бот не может открыть файл, вызвать API, проверить результат или исправить ошибку.

AI-агент — это система, которая умеет действовать. У агента есть цель, набор инструментов и цикл рассуждений. Он получает задачу, составляет план, выполняет шаги, проверяет результат и корректирует подход при необходимости. Claude Code — пример AI-агента: он не просто генерирует код, а читает файлы, запускает команды, исправляет ошибки.

Каждый AI-агент состоит из трёх фундаментальных компонентов: reasoning loop (цикл рассуждений), tools (инструменты) и memory (память). Убери любой — и агент деградирует до чат-бота.

1. Reasoning Loop (Цикл рассуждений)

Сердце агента — это цикл Plan → Execute → Verify (PEV). На этапе планирования агент анализирует задачу и определяет последовательность шагов. На этапе выполнения он использует инструменты для реализации каждого шага. На этапе проверки он оценивает результат и решает: задача выполнена, или нужна корректировка.

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

2. Tools (Инструменты)

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

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

• File tools: read_file, write_file, list_directory — работа с файловой системой
• Shell tools: execute_command — запуск команд в терминале
• API tools: http_request — вызов внешних сервисов
• Search tools: web_search, grep — поиск информации
• Database tools: query, migrate — работа с БД
• Communication tools: send_message, send_email — взаимодействие с людьми

3. Memory (Память)

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

Долгосрочная память — это то, что делает агента по-настоящему мощным. Это может быть файл с заметками (как CLAUDE.md), векторная база данных с прошлыми решениями, или структурированное хранилище знаний о проекте. Агент с памятью учится на опыте и не повторяет одни и те же ошибки.

MCP — это открытый протокол от Anthropic, который стандартизирует взаимодействие AI-агентов с инструментами. До MCP каждый разработчик изобретал свой формат описания инструментов, свой протокол вызовов, свою обработку ответов. MCP решает это — один протокол для всех.

Как работает MCP

MCP-сервер экспортирует набор tools с JSON Schema описанием параметров. Клиент (AI-агент) подключается к серверу, получает список инструментов и может их вызывать. Это как REST API, но специально спроектированный для AI: с описаниями, примерами и типизацией, которые помогают модели правильно использовать инструмент.

• Transport: stdio (локальный) или HTTP+SSE (удалённый)
• Discovery: клиент запрашивает список tools при подключении
• Invocation: JSON-RPC вызов с параметрами, результат в JSON
• Типизация: JSON Schema для входных параметров и результатов
• Экосистема: тысячи готовых серверов — GitHub, Slack, PostgreSQL, файловая система

Это ядро любого эффективного AI-агента. Разберём каждый этап подробно.

Plan (Планирование)

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

На этом этапе агент также определяет критерии успеха: как он поймёт, что задача выполнена? Это может быть: тесты проходят, приложение компилируется, API возвращает ожидаемый ответ. Без критериев успеха агент не знает, когда остановиться.

Execute (Выполнение)

Агент последовательно выполняет шаги плана, используя доступные инструменты. Каждый шаг — это вызов инструмента с конкретными параметрами и обработка результата. Читает файл, анализирует структуру, пишет код, запускает тесты.

Ключевой принцип: один шаг — одно действие. Агент не пытается сделать всё за один вызов инструмента. Он читает файл, анализирует его, потом редактирует конкретную часть, потом проверяет результат. Маленькие шаги = меньше ошибок.

Verify (Проверка)

После каждого шага (или группы шагов) агент проверяет результат. Компилируется ли код? Проходят ли тесты? Совпадает ли результат с ожиданиями? Если нет — агент возвращается к планированию и корректирует подход. Это то, что делает агента устойчивым к ошибкам.

Минимальный агент состоит из цикла, который управляет взаимодействием между AI-моделью и набором инструментов. Вот концептуальная архитектура.

Основной цикл

Цикл агента работает так: 1) отправить текущий контекст (задача + история действий) в модель, 2) получить от модели решение (текст или вызов инструмента), 3) если вызов инструмента — выполнить его и добавить результат в историю, 4) если текст — проверить, считает ли модель задачу завершённой. Повторять до завершения или лимита итераций.

Регистрация инструментов

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

Управление контекстом

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

Файловая система

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

Терминал

Запуск shell-команд позволяет агенту: устанавливать зависимости (npm install), запускать тесты (npm test), билдить проект (npm run build), проверять статус Git. Терминал — это «руки» агента в операционной системе.

Веб-поиск и API

Агент может искать информацию в интернете, вызывать внешние API, получать данные из сервисов. Это расширяет его возможности за пределы локальной среды. MCP-серверы для GitHub, Slack, базы данных — всё это инструменты агента.

Агент в продакшне отличается от локального прототипа несколькими критическими аспектами.

• Безопасность: sandboxing инструментов, ограничение доступа к файловой системе и сети
• Rate limiting: контроль количества вызовов API модели и инструментов
• Мониторинг: логирование каждого шага агента для отладки и аудита
• Timeout: ограничение времени на выполнение задачи (агент может зациклиться)
• Human-in-the-loop: запрос подтверждения для опасных действий (удаление, деплой)
• Стоимость: контроль расхода токенов — длинный reasoning loop стоит денег

Паттерны масштабирования

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

AI-агенты — это не просто технология. Это новая парадигма разработки. Вместо того чтобы писать код руками или даже генерировать его через чат — вы проектируете системы агентов, которые решают задачи автономно. Это agentic engineering.

Навык проектирования агентов становится одним из самых востребованных в индустрии. Понимание reasoning loops, tool design, memory management, multi-agent coordination — это то, что отличает AI-инженера от AI-пользователя.

В BRIQ.TEAM мы строим AI-агентов с третьей недели курса. К концу второго месяца студенты создают полноценные multi-agent системы, которые автоматизируют реальные бизнес-процессы. Это не теория — это работающий код.