Агент на LangChain за час: от установки до первого запуска

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

Важная оговорка про версии. LangChain активно меняет API: подход через initialize_agent считается устаревшим, современный способ — LangGraph и функция create_react_agent. Точные имена импортов и сигнатуры сверяйте с актуальной документацией на python.langchain.com, потому что между минорными версиями они смещаются.

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

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

Разница на примере. Спросите обычную модель «сколько будет 4839 умножить на 2917» — она может ошибиться в арифметике. Агент с калькулятором вызовет функцию, получит точный результат и вернёт его. То же с актуальными данными: без инструмента поиска модель отвечает по состоянию на дату обучения, с инструментом — идёт в интернет.

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

Подготовка окружения

Понадобится Python 3.9 или новее и ключ доступа к какой-нибудь модели — например, OpenAI. Ключ храните в переменной окружения, а не в коде.

1. Создайте виртуальное окружение: python -m venv venv и активируйте его.
2. Установите пакеты: pip install langchain langchain-openai langgraph.
3. Положите ключ в переменную окружения OPENAI_API_KEY.
4. Проверьте, что импорт проходит без ошибок, прежде чем писать логику.

Набор пакетов зависит от того, чью модель вы берёте. Для Anthropic это langchain-anthropic, для локальных моделей через Ollama — langchain-ollama. Точные имена пакетов смотрите в разделе интеграций документации.

Собираем агента

Логика простая: описываем инструменты обычными функциями, помечаем их декоратором @tool, передаём модель и список инструментов в конструктор агента.

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent


@tool
def multiply(a: float, b: float) -> float:
    """Перемножает два числа и возвращает результат."""
    return a * b


@tool
def word_length(text: str) -> int:
    """Возвращает количество символов в строке."""
    return len(text)


model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = [multiply, word_length]

agent = create_react_agent(model, tools)

result = agent.invoke(
    {"messages": [("user", "Сколько будет 4839 умножить на 2917?")]}
)
print(result["messages"][-1].content)

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

Как проследить, что делает агент

Чёрный ящик — главная боль отладки агентов. Чтобы увидеть каждый шаг рассуждения и каждый вызов инструмента, включите потоковый вывод через agent.stream(...) вместо invoke или подключите трейсинг LangSmith. Без этого вы будете гадать, почему агент вызвал не тот инструмент.

Чем LangChain отличается от альтернатив

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

Ключевой вопрос при выборе: сколько инструментов и насколько сложна логика их вызова. Для одного инструмента прямой вызов function calling из SDK провайдера часто проще и прозрачнее фреймворка.

Кому это пригодится и кому нет

Пригодится, если:

• вы собираете внутренний ассистент, который дёргает несколько API и БД, и хотите не писать цикл вызовов вручную;
• нужно быстро подключить много готовых интеграций — векторные хранилища, загрузчики документов, разные провайдеры моделей;
• вы прототипируете и цените скорость сборки выше контроля над каждой деталью.

Скорее помешает, если:

• задача решается одним запросом к модели без инструментов — фреймворк добавит зависимости и задержку без пользы;
• вам критична стабильность API на годы вперёд — тут частые изменения LangChain станут головной болью;
• нужен максимальный контроль и минимум зависимостей в проде — прямой вызов SDK предсказуемее.

Про стоимость

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

Отдельно стоит LangSmith — сервис трейсинга и оценки от той же команды. У него есть бесплатный тариф и платные планы; актуальные лимиты и цены смотрите на странице тарифов, они меняются.

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