Привет, на связи команда GigaChain!

ReAct — фундаментальный паттерн, с которого началась эра LLM-агентов. Но как его реализовать сегодня, используя всю мощь function-calling и графовую логику? Разбираем эволюцию концепции, проводим чёткую грань между LangChain и LangGraph и пошагово разбираем создание гибкого ReAct-агента на современном стеке. Никакой магии, только воспроизводимый код и понятная теория.

Исторический момент

С выходом в 2022 году статьи «ReAct: Synergizing Reasoning and Acting in Language Models» началась современная эпоха LLM-агентов. Хотя отдельные идеи о взаимодействии LLM с внешним миром существовали и раньше, эта академическая статья дала простой, легко воспроизводимый и универсальный паттерн в виде чередования размышлений (Thoughts), действий (Actions) и наблюдений (Observations) при решении задач. Чтобы оценить этот вклад, можно провести параллель с другой революционной статьёй. В 2017 году «Attention Is All You Need» дала нам архитектуру Transformer, ту самую, на которой работают все (или почти все) современные LLM. Спустя пять лет «ReAct» совершила революцию иного рода, определив стандарт автономного решения многоэтапных задач через размышления и применение внешних инструментов.

Однако технологии не стоят на месте, и современная реализация ReAct-агентов существенно отличается от того, что было предложено в оригинальной статье. Изначально ReAct-паттерн полагался на работу с сырым текстом: модель генерировала ответ, содержащий специальные теги вроде «Thought:» и «Action:», а далее  парсила нужные фрагменты текста. Это был довольно хрупкий процесс, сильно зависящий от строгости промпта и стабильности вывода модели. Сегодня мы перешли к гораздо более надёжному подходу. Современные LLM специально обучены под вызов функций (function calling или tool calling). Вместо парсинга текста модель теперь возвращает структурированный JSON-объект с чётким указанием, какой инструмент и с какими аргументами необходимо вызвать. Фреймворки, такие как LangGraph, используют полученный от модели JSON, чтобы вызвать соответствующую функцию в коде. Результат выполнения этой функции затем оформляется как специальное сообщение с ролью tool — это четвёртый тип сообщений в диалоге, наряду с system, user и assistant. Такое сообщение предоставляет модели информацию о выполненном действии, которую она может использовать при дальнейших рассуждениях и формировании ответа пользователю.

Развитие фреймворков

Прежде чем переходить к реализации ReAct-агентов в коде, поговорим о фреймворках LangChain и LangGraph. Даже среди тех, кто активно работает с LLM-инструментами, порой сохраняется путаница: различия между LangChain и LangGraph не всем очевидны, а впечатления, сформированные в ранний период развития этих фреймворков, могут не отражать их текущее состояние. Поэтому имеет смысл коротко обозначить, чем они различаются и какова их роль сегодня.

LangChain как библиотека появился в октябре 2022 года и быстро стал набирать популярность. В апреле 2023 года проект обрёл юридическую форму, став стартапом и получив финансирование от инвесторов. 

LangChain предлагает универсальный набор компонентов для построения LLM-приложений: модели, цепочки вызовов и взаимодействий между компонентами, обработку векторных хранилищ, интеграцию с внешними данными и поддержку инструментов. Его основная цель — ускорить разработку и экспериментирование, при этом сохраняя гибкость. Фундаментальной абстракцией в LangChain, особенно с появлением LCEL (LangChain Expression Language), является цепочка (Chain), которая представляет собой направленный ациклический граф (дерево) (DAG). Это означает, что данные в цепочке движутся строго в одном направлении, от входа к выходу, без возможности вернуться на предыдущий шаг или создать цикл. Такой подход удобен для задач, где последовательность шагов заранее определена.

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

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

Осознав это фундаментальное ограничение, команда LangChain в начале 2024 года представила LangGraph. Идея, которую они предложили, была простой и элегантной: если Chain — это направленный ациклический граф, то агент — это граф с циклами.

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

• узлы (nodes) — это функции или другие вызываемые объекты (например, вызов LLM или инструмента);

• рёбра (edges) — это логика, которая на основе текущего состояния решает, к какому узлу перейти дальше;

• состояние (state) — это центральный объект, который передаётся от узла к узлу и аккумулирует всю информацию (входящие сообщения, результаты вызовов инструментов и т. д.).

Такой подход превращает «магию» агента в явную и управляемую схему, которую легко отлаживать, настраивать и расширять. Именно на этой мощной и гибкой основе мы и будем строить наш ReAct-агент. 

Делаем агента

Теория — это прекрасно, но давайте перейдём от слов к коду. Чтобы на практике увидеть возможности LangGraph, мы создадим простой, но вполне функциональный агент, который будет обладать всего двумя способностями (инструментами):

• искать информацию в интернете, чтобы отвечать на актуальные вопросы;

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

Этот простой сценарий «найти и сохранить» отлично демонстрирует полный цикл работы ReAct-агента: получение задачи, использование одного или нескольких инструментов и предоставление итогового результата. Мы не будем с нуля строить граф со всеми узлами и рёбрами вручную. Вместо этого мы воспользуемся удобной высокоуровневой функцией create_react_agent из langgraph.prebuilt, которая всё соберёт за нас.

Чтобы ReAct-агент заработал, нам надо подготовить:

• Подключение к модели, которая будет размышлять и решать, какие инструменты вызывать. Мы будем использовать GigaChat-2-Max, поскольку это самая мощная модель в линейке GigaChat от Сбера. При желании вы можете использовать любого другого провайдера, который вам доступен. Экосистема LangChain/LangGraph имеет готовые интеграции практически со всеми LLM. В коде от этого изменится буквально пара строчек.

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

• Начальная инструкция (системный промпт), которая задаёт агенту его роль, контекст и правила поведения.

Ниже представлен полный код нашего мини-агента. Давайте разберём основные моменты из него.

from pathlib import Path
from datetime import datetime, date
from pydantic import BaseModel, Field
from langchain.tools import tool

from langchain_gigachat.chat_models import GigaChat
from langgraph.prebuilt import create_react_agent
from ddgs import DDGS

# ──────────────────────────────────────────────────────────────
DATA_DIR = Path("agent_data"); DATA_DIR.mkdir(exist_ok=True)

llm = GigaChat(credentials="авторизационные_данные", verify_ssl_certs=False, scope="GIGACHAT_API_CORP", model='GigaChat-2-Max')



# ── append_to_file ──────────────────────────────────────────
class AppendArgs(BaseModel):
    filepath: str = Field(..., description="Имя текстового файла в ./agent_data")
    content:  str = Field(..., description="Текст для записи в файл")

@tool(
    args_schema=AppendArgs,
    description="Добавить строку в локальный текстовый файл (agent_data/...) "
)
def append_to_file(filepath: str, content: str) -> str:
    path  = DATA_DIR / Path(filepath).name                 # без ../
    stamp = datetime.now().strftime("[%d.%m.%Y %H:%M] ")   # DD.MM.YYYY
    with path.open("a", encoding="utf-8") as f:
        f.write(stamp + content.rstrip() + "\n")
    return f"✅ Записано в {path.name}"

# ── search_web ──────────────────────────────────────────────
@tool("search_web", description="Ищет в DuckDuckGo (RU, неделя, 5 ссылок)")
def search_web(query: str, max_results: int = 5) -> str:
    with DDGS() as ddgs:
        hits = ddgs.text(query, region="ru-ru", time="w", max_results=max_results)
        return "\n".join(f"{hit['title']}: {hit['body']} -- {hit['href']}" for hit in hits[:max_results])

# ── агент ───────────────────────────────────────────────────────
today = date.today().strftime("%d.%m.%Y")  # DD.MM.YYYY
system_prompt = (
    f"Сегодня {today}. "
    "Ты полезный ассистент. Используй search_web для поиска в интернете, "
    "append_to_file -- чтобы сохранять результаты."
)


agent = create_react_agent(model=llm,
                           tools=[search_web, append_to_file],
                           prompt=system_prompt)

# ── REPL ───────────────────────────────────────────────────
def run(query: str):
    resp = agent.invoke({"messages": [("user", query)]})
    for message in resp["messages"]:
        message.pretty_print()

if __name__ == "__main__":
    print("⚡ Мини-агент готов (поиск + запись). Пустая строка -- выход.")
    try:
        while True:
            q = input("> ").strip()
            if not q:
                break
            run(q)
    except (KeyboardInterrupt, EOFError):
        pass

В начале кода мы импортировали все необходимые библиотеки, создали директорию agent_data для файлов, которые будет создавать агент с помощью своего инструмента, и инициализировали модель GigaChat-2-Max. 

Далее в коде идёт описание инструментов. Они представляют собой Python-функции, обёрнутые в декоратор @tool. Этот декоратор автоматически преобразует функцию и её описание в JSON-схему, которую LLM сможет «понять» и использовать.  

Для инструмента записи в файл append_to_file мы применили Pydantic-модель AppendArgs, чтобы описывать аргументы filepath и content. Это один из возможных подходов по формированию описания инструмента для модели. Сама функция append_to_file открывает файл с названием, указанным агентом, и записывает информацию, которую ей также передаёт агент. Ему же в результате возвращается сообщение с ролью tool об успешной записи в файл.

Второй инструмент представляет собой функцию с обращением к поисковику DuckDuckGo. Это простой способ получить информацию из внешнего мира, поскольку для работы не требуются ключи доступа. В LangChain есть встроенный инструмент для работы с DuckDuckGo, но он содержит зависимость от старой библиотеки duckduckgo-search. Новая библиотека ddgs пока не имеет нативной интеграции с экосистемой LangChain, поэтому мы использовали самописную функцию search_web с декоратором @tool. Внутри функции происходит обращение по запросу, полученному от модели. Ответом на запрос является словарь из заголовков, ссылок и фрагментов контента, которые функция «сшивает» в одну строку и выдаёт как ответ для модели.

Имея инструменты и инициализировав модель, можно переходить к сборке агента. Для этого мы объявили системный промпт system_prompt как строку с форматированием, куда подставляется текущая дата. Это сделано, чтобы модель лучше ориентировалась во времени при отправке запросов в поисковик. Также мы указали ещё раз на назначение инструментов, доступных агенту.

Далее идет функция create_react_agent, в которую передаются модель, системный промпт и список инструментов. После этого агент готов обрабатывать запросы пользователя. Сами авторы LangChain не рекомендуют использовать эту функцию в эксплуатации, потому что она убирает полный контроль над происходящим. Вот как они предлагают реализовать эту функциональность.

Для обработки запросов в коде предусмотрена функция run(), внутри которой обращение к модели происходит через метод invoke() с передачей в него списка сообщений. Для простоты примера мы передали просто один пользовательский запрос (в дополнение к уже переданному в агент системному промпту). Получившаяся последовательность сообщений затем выводится с использованием метода pretty_print().

Общая структура агента выглядит так:

Она состоит из узлов:

• start и end — входной и конечный узел графа;

• agent — узел с обращением к GigaChat-2-Max, который принимает решение о вызове инструмента или формировании итогового ответа пользователю;

• tools — узел-исполнитель, который вызывает функцию, определённую в узле agent; после выполнения кода функции результат возвращается в agent в виде сообщения с ролью tool.

Помимо узлов граф содержит безусловные (например, между tools и agent) и условные (между agent и tools или end) переходы-рёбра. 

Запустим наш агент, чтобы продемонстрировать его работу.

В ходе обработки первого запроса модель вызвала инструмент поиска, получила контекст, после чего обратилась ко второму инструменту для создания файла с информацией. По итогу отработки второго инструмента агент решает, что можно дать окончательный ответ пользователю. После формирования ответа агент завершает свою работу, но для нашего кода завершилась лишь одна итерация бесконечного цикла while, поэтому работа продолжается. Если мы зададим новый пользовательский запрос, например, про содержание предыдущего запроса, то увидим, что контекст не сохраняется, поскольку каждый раз мы передаём в метод invoke() лишь отдельный пользовательский запрос. Можно было бы реализовать сохранение и передачу увеличивающейся истории сообщений самостоятельно, но у LangGraph есть для этого нативное решение. 

Для хранения состояний агента в LangGraph предусмотрен механизм хранения контрольных точек в виде объекта класса StateSnapshot. Такой объект создаётся на каждом шаге работы агента (в терминологии LangGraph это называется superstep). Под шагом понимается итерация работы графа, в ходе которой выполняются все узлы, готовые к запуску (это может быть как один узел, так и несколько параллельных сразу). Все контрольные точки в рамках одной сессии работы агента объединены в тред (thread) с общим идентификатором. Внутри StateSnapshot информация о состоянии агента хранится в следующих полях:

• values содержит структуру данных графа, его текущее состояние;

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

• config содержит информацию об идентификаторах треда и конкретной контрольной точки;

• metadata — метаданные, показывающие порядковый номер шага агента и стадию состояния (input после запуска графа, но перед первым супершагом, и loop после каждого последующего шага);

• tasks содержит информацию о выполненных узлах на текущем супершаге.

Использование StateSnapshot позволяет не только рассмотреть постфактум состояние агента на различных этапах выполнения задачи, но и отредактировать состояние и/или запустить работу графа повторно, начиная с любого из них. 

Чтобы реализовать механизм контрольных точек в коде, понадобится добавить и модифицировать лишь несколько строк в наш текущий вариант ReAct-агента.

Импортируем класс MemorySaver, чтобы добавить память состояний. Также добавим импорт модуля uuid для создания уникальных идентификаторов тредов.

import uuid
from langgraph.checkpoint.memory import MemorySaver

Создаём объект для хранения состояний и добавляем его к агенту. Для простоты будем хранить состояния в оперативной памяти, но есть реализации и на базах данных.

checkpointer = MemorySaver()
agent = create_react_agent(
    model=llm,
    tools=[search_web, append_to_file],
    prompt=system_prompt,
    checkpointer=checkpointer # Подключаем "память" к агенту
)

Модифицируем функцию run и тело выполнения основной программы. Для этого добавим в агента передачу thread_id через конфигурацию config.

def run(query: str, thread_id: str): # Принимаем ID диалога
   
    config = {"configurable": {"thread_id": thread_id}}
    
    resp = agent.invoke({"messages": [("user", query)]}, config=config)
    for message in resp["messages"]:
        message.pretty_print()


if name == "__main__":
    # Создаем уникальный ID для всей сессии нашего диалога
    conversation_id = str(uuid.uuid4())
    print(f"⚡ Мини-агент с памятью готов (ID диалога: {conversation_id}). Пустая строка -- выход.")
    
    try:
        while True:
            q = input("> ").strip()
            if not q:
                break
            run(q, conversation_id) # Передаем ID в функцию
    except (KeyboardInterrupt, EOFError):
        pass

После таких модификаций кода легко убедиться, что состояния агента становятся связаны друг с другом, поскольку относятся к одному thread_id. Агент ведёт связный диалог, опираясь на контекст прошлых сообщений, и вызывает инструменты, когда требуется выполнить действие.

Заключение

Мы рассмотрели работу ReAct-агента на LangGraph «из коробки». Для первого погружения этого вполне достаточно. Подведём итоги.

Мы прошли путь от исторической статьи ReAct (2022) до полностью рабочего ReAct‑агента на LangGraph + GigaChat‑2‑Max — с инструментами, графовой логикой и чекпоинтами.

Главное, что нужно вынести:

• Function/Tool calling в формате JSON. Сейчас модель сразу отдаёт готовый JSON‑объект с названием инструмента и его аргументами. Благодаря этому нам не нужно вырезать «Thought:» или «Action:» из сырого текста и разбирать его вручную.

• Агент работает как циклический граф, а StateSnapshot служит контрольной точкой. Вся логика агента оформлена в виде графа, по которому данные могут ходить по кругу, пока задача не решена. На каждом шаге LangGraph автоматически делает снимок состояния (StateSnapshot). По этому снимку можно откатиться назад, руками поправить данные или перезапустить агент с того места, где он остановился.

• Память реализуется через чекпоинтер. То, что мы называем «памятью» агента, технически — это тот же механизм контрольных точек. В примере использован временный MemorySaver, который хранит снимки в оперативной памяти. Если нужна долговременная память, достаточно заменить его на вариант с базой данных (SQLite, Postgres).

• Функция create_react_agent снимает почти всю рутину. Когда вы вызываете create_react_agent, под капотом автоматически собирается готовый конечный автомат со всей базовой логикой ReAct‑цикла. То есть вам не нужно вручную описывать узлы, переходы и правила их срабатывания — всё это уже настроено. При этом остаётся свобода: если хочется изменить поведение агента, вы всегда можете подменить конкретный узел, добавить новые инструменты или настроить собственные переходы между шагами.

Также заходите в репозиторий нашей команды на GitVerse и GitHub. Там вы найдете целый набор решений для разработки LLM-приложений и мультиагентых систем:

• библиотеки для интеграции GigaChat API c экосистемой LangChain/LangGraph

• утилиты и MCP-серверы

• кукбуки с примерами реализации агентов на Python, TS/JS и Java