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

# 1. Компоненты архитектуры

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

01. LLM-ядро — модель, которая «думает»: GPT-4o, Claude, DeepSeek, GigaChat или локальная Llama. Это двигатель, но сам по себе он бесполезен без остальных компонентов.

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

03. Память — хранилище контекста: история диалога, факты о пользователе, база знаний компании. Без памяти агент амнезирует между вызовами.

04. Инструменты — руки агента: функции, API, браузер, файловая система. Всё, что превращает текст в реальное действие.

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

Ключевая идея — разделение «мышления» и «действия». Модель только предлагает, что сделать; выполнение берёт на себя среда (код). Это даёт контроль: вы можете запретить агенту удалять файлы, ограничить бюджет токенов на задачу или логировать каждый вызов. Модель никогда не получает прямой доступ к вашей системе — только через инструменты, которые вы ей выдали.

# 2. LLM-ядро и планировщик

Ядро агента — большая языковая модель, вызываемая через API. Её контракт прост: на вход — список сообщений и описание доступных инструментов, на выход — либо текст ответа, либо запрос на вызов инструмента (tool_call). Всё остальное — надстройка.

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

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

# 3. Память агента: краткосрочная, долгосрочная, рабочая

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

Краткосрочная память — это контекстное окно модели: текущий диалог, результаты последних вызовов инструментов, временные переменные. Она живёт только в рамках одного сеанса и ограничена размером контекста (обычно от 32K до 1M токенов). Переполнение контекста — частая причина «деградации» агента: модель начинает забывать начало инструкции. Лечится сжатием (суммаризацией) старых сообщений и обрезкой.

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

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

# 4. RAG и векторные БД

RAG (Retrieval-Augmented Generation) — главный механизм долгосрочной памяти. Идея: вместо того чтобы модель «знала» ваши документы, вы храните их отдельно и перед ответом подбираете нужные фрагменты по смыслу. Схема из трёх шагов: индексация (документы режутся на чанки и превращаются в эмбеддинги — векторы чисел), поиск (запрос тоже векторизуется и ищется по ближайшим соседям), генерация (найденные фрагменты добавляются в промпт, и модель отвечает с опорой на них).

Векторная база — это место, где лежат эмбеддинги и выполняется поиск по косинусной близости. Выбор базы зависит от масштаба и инфраструктуры. Для пилота на локальной машине хватает Chroma (встраивается прямо в Python, ноль настройки). Для продакшена чаще берут Qdrant (открытый, быстрый, Docker одной командой), Pinecone (управляемый SaaS) или pgvector (расширение PostgreSQL, если у вас уже есть Postgres и не хочется плодить сервисы).

# Установка стека для агента с памятью
python -m pip install openai-agents qdrant-client langgraph

# Локальный Qdrant для долгосрочной памяти (vector store)
docker run -p 6333:6333 -p 6334:6334 \
    -v qdrant_storage:/qdrant/storage \
    qdrant/qdrant

# Проверка: веб-дашборд и healthcheck
curl http://localhost:6333/healthz   # {"title":"ok",...}

# 5. Инструменты и function calling

Function calling — это протокол, по которому модель сообщает, какую из ваших функций она хочет вызвать и с какими аргументами. Вы описываете инструмент в JSON-схеме, модель возвращает структурированный запрос, ваш код выполняет функцию и возвращает результат обратно в диалог. Модель сама решает, когда и какой инструмент нужен, — вы только предоставляете каталог и исполняете вызовы.

Вот как выглядит JSON-схема инструмента, которую видит модель. Обратите внимание: описание (description) — это подсказка модели, когда использовать инструмент; чем точнее оно написано, тем реже модель будет вызывать его не к месту.

// JSON-схема инструмента (что видит модель)
{
  "type": "function",
  "function": {
    "name": "search_knowledge_base",
    "description": "Ищет по внутренней базе знаний компании. Используй, когда вопрос касается продуктов, цен или политик.",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Поисковый запрос на естественном языке"
        },
        "top_k": {
          "type": "integer",
          "description": "Сколько фрагментов вернуть (по умолчанию 3)"
        }
      },
      "required": ["query"]
    }
  }
}

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

# 6. MCP-протокол

MCP (Model Context Protocol) — открытый стандарт от Anthropic, который решает проблему «каждый инструмент подключается по-своему». Это как USB-C для AI-инструментов: вместо того чтобы писать кастомную обвязку под каждую интеграцию, вы подключаете готовый MCP-сервер, и агент получает унифицированный набор инструментов.

Архитектура MCP — клиент-серверная. MCP-сервер оборачивает какой-то источник данных или действие (файловую систему, GitHub, базу данных, браузер) и публикует его инструменты по стандартному протоколу. MCP-клиент (ваш агент) подключается к серверу и автоматически получает список доступных инструментов — их не нужно описывать вручную в JSON-схемах. Один и тот же сервер можно переиспользовать в разных агентах и фреймворках.

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

# 7. Паттерны ReAct и plan-and-execute

Паттерн — это способ заставить модель решать задачу по шагам, а не одним «выстрелом». Два базовых подхода покрывают большинство сценариев.

ReAct (Reason + Act) — цикл «мысль → действие → наблюдение». Модель пишет, что она думает сделать, вызывает инструмент, смотрит на результат и решает следующий шаг. Это самый гибкий паттерн: агент адаптируется по ходу, но может зациклиться или уйти в сторону без ограничений на число шагов. Подходит для задач, где путь заранее неизвестен: «найди причину ошибки в логах», «сравни два продукта и сделай вывод».

Plan-and-execute — сначала полный план, потом исполнение. Модель составляет список шагов, утверждает его, и только потом выполняет по порядку. Это предсказуемее и дешевле (меньше итераций), но план может устареть, если среда изменилась. Подходит для рутинных многошаговых задач: «собери отчёт по продажам за месяц и отправь в Slack».

# 8. Оркестрация и multi-agent

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

Multi-agent решает реальную проблему: у одной модели ограниченное окно внимания, и чем больше инструкций вы в неё запихнёте, тем хуже она следует каждой. Разделение на агентов с узкими ролями (исследователь, критик, писатель, валидатор) даёт каждому короткий и чёткий промпт. Плата — рост стоимости и сложности: каждое «обсуждение» между агентами тратит токены, а отладка такой системы сложнее.

Для графовой оркестрации де-факто стандарт — LangGraph: состояния, ветвления, циклы и человеческие подтверждения описываются как граф. На нашем сайте есть разбор фреймворка LangChain, на котором построен LangGraph, — смотрите карточку фреймворка оркестрации. Золотое правило: начинайте с одного агента и добавляйте второго только тогда, когда один объективно не тянет. Большинство «multi-agent»-проектов переусложнены и отлично работали бы как один хорошо спроектированный агент.

# 9. Стек 2026: LangGraph, CrewAI, OpenAI Agents SDK

К 2026 году рынок фреймворков стабилизировался вокруг трёх лидеров, каждый под свою нишу.

LangGraph — самый мощный и самый сложный. Графы состояний, явный контроль над циклами, персистентность, человеческие подтверждения и time-travel отладка. Выбор для продакшен-систем с нестандартной логикой. CrewAI — ролевые команды агентов: вы описываете агентов как сотрудников (роль, цель, бэкграунд) и запускаете «экипаж». Быстрый старт для multi-agent сценариев, но меньше контроля над низкоуровневой логикой. OpenAI Agents SDK — минималистичная библиотека от OpenAI: агенты, хендоффы (передача диалога между агентами), guardrails и трейсинг. Лучший выбор, если вы уже в экосистеме OpenAI и хотите минимум абстракций.

Правило выбора простое: нужна тонкая настройка циклов и ветвлений — LangGraph; нужен быстрый multi-agent прототип с ролями — CrewAI; нужно минимально и нативно для OpenAI — Agents SDK. Для всех трёх обязателен общий фундамент из этого гайда: память, инструменты, лимиты итераций и логирование.

# 10. Пример простого агента на Python

Собираем всё вместе: агент с памятью (история диалога), инструментом (поиск по векторной базе) и циклом ReAct на OpenAI Agents SDK. Это минимальный, но полноценный каркас — его можно расширять под свою задачу.

import asyncio
from agents import Agent, Runner, function_tool
from qdrant_client import QdrantClient

qdrant = QdrantClient("localhost", port=6333)

# Инструмент: поиск по долгосрочной памяти (RAG)
@function_tool
def recall(query: str) -> str:
    # эмбеддинг запроса + поиск ближайших чанков в Qdrant
    hits = qdrant_search(query, top_k=3)
    return "\n\n".join(h.text for h in hits)

# Агент: LLM-ядро + планировщик (ReAct) + инструмент + системный промпт
agent = Agent(
    name="support",
    instructions="Ты помощник поддержки. Отвечай только по базе знаний через recall. Если ответа нет — честно скажи.",
    tools=[recall],
)

async def main():
    # история = краткосрочная память; сохраняется между шагами
    history = []
    while True:
        user_input = input("Вы: ")
        if user_input.strip() == "exit":
            break
        result = await Runner.run(agent, history + [user_input])
        history.append(user_input)
        history.append(result.final_output)
        print("Агент:", result.final_output)

asyncio.run(main())

Обратите внимание на три архитектурных решения в этом коде. Память: history — краткосрочная, а qdrant — долгосрочная. Инструмент: модель видит recall и сама решает, когда к нему обратиться. Оркестрация: цикл while True — это и есть упрощённый ReAct-цикл, где модель за одну итерацию может сделать несколько вызовов инструментов, прежде чем вернуть финальный ответ.

# 11. Итог

Архитектура AI-агента — это не волшебство, а пять понятных компонентов: LLM-ядро, планировщик, память (краткосрочная, долгосрочная и рабочая), инструменты и оркестратор. Память через RAG и векторные базы отделяет полезного агента от амнезирующей болталки; function calling и MCP дают ему руки; паттерны ReAct и plan-and-execute — дисциплину; multi-agent оркестрация — масштаб. Начинайте с одного агента, узкой цели и минимального набора инструментов, а усложняйте архитектуру только под реальную необходимость.