Введение в экосистему LangChain

LangChain — это фреймворк для создания агентов на базе языковых моделей. Ключевая формула: Агент = Модель + Обвязка.

#Что такое агент и чем он отличается от чата

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

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

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

#Компоненты экосистемы

LangChain (основной фреймворк) — абстракции и интеграции для моделей, инструментов и циклов агентов. Содержит фабрику create_agent для создания агентов с минимальной конфигурацией и систему мидлварей для расширения поведения.

LangGraph (оркестрация) — низкоуровневый фреймворк для создания долгоживущих, состоятельных агентов. Позволяет смешивать детерминированные и агентивные шаги в одном графе. create_agent внутри строит именно граф LangGraph — это не два конкурирующих API, а два уровня одного стека.

Deep Agents — высокоуровневая обвязка с готовыми возможностями: планирование, файловая система, субагенты, управление контекстом. Построена поверх LangChain.

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

#Как устроены пакеты

Понимание раскладки пакетов экономит время при отладке импортов.

langchain-core содержит базовые абстракции: сообщения, инструменты, интерфейс моделей. Он не тянет за собой провайдеров. langchain — основной пакет с create_agent, мидлварями и удобными реэкспортами. langgraph — движок оркестрации: StateGraph, чекпоинтеры, прерывания. Пакеты интеграций (langchain-openai, langchain-anthropic, langchain-google-genai, langchain-ollama) добавляют конкретных провайдеров и устанавливаются отдельно — так основная установка остаётся лёгкой.

#Установка

Для начала работы достаточно установить основные пакеты. langgraph подтягивается как зависимость langchain, но явная установка делает намерение видимым:

pip install -U langchain langgraph

Для Deep Agents потребуется дополнительный пакет:

pip install -U langchain deepagents

Провайдеры ставятся отдельно, берите только тот, который реально используете:

pip install langchain-openai       # OpenAI
pip install langchain-anthropic    # Anthropic
pip install langchain-google-genai # Google
pip install langchain-ollama       # Ollama (локальные модели)

Если при вызове init_chat_model вы видите ImportError с упоминанием провайдера, почти всегда это забытый пакет интеграции, а не ошибка в коде.

#Единый интерфейс моделей

LangChain предоставляет единый интерфейс для всех провайдеров. Можно сменить модель, изменив одну строку. Модель создаётся через init_chat_model со строковым идентификатором в формате "провайдер:модель":

from langchain.chat_models import init_chat_model

# OpenAI
model = init_chat_model("openai:gpt-4o-mini")

# Anthropic
model = init_chat_model("anthropic:claude-sonnet-4-6")

# Google
model = init_chat_model("google_genai:gemini-2.5-flash-lite")

# Ollama (локально)
model = init_chat_model("ollama:llama3")

Строка до двоеточия — это идентификатор провайдера, он определяет, какой пакет интеграции будет загружен. Если провайдер не указан (init_chat_model("gpt-4o-mini")), LangChain пытается вывести его по имени модели. Так работает, но лучше писать явно: код становится читаемым, а ошибка при опечатке — понятной.

Можно указать дополнительные параметры — температуру, таймаут, максимальное количество токенов:

model = init_chat_model(
    "openai:gpt-4o-mini",
    temperature=0.5,
    timeout=300,
    max_tokens=4096,
)

При создании агента модель указывается напрямую в create_agent — строкой или уже созданным объектом. Строка удобна для прототипа, объект — когда нужны нестандартные параметры:

from langchain.agents import create_agent

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[],
    system_prompt="Ты помощник.",
)

#Как выбрать модель

Для быстрого прототипа подойдут openai:gpt-4o-mini или google_genai:gemini-2.5-flash-lite — они дешёвые и быстрые. Для сложных задач с длинными цепочками рассуждений — anthropic:claude-sonnet-4-6 или openai:gpt-5.5. Для работы без внешних API (обучение, чувствительные данные) — ollama:llama3 на локальной машине.

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

#Настройка ключей API

Перед работой нужно установить ключ API провайдера через переменную окружения. LangChain читает их автоматически, передавать ключ в код не нужно:

export OPENAI_API_KEY="ваш-ключ"
# или
export ANTHROPIC_API_KEY="ваш-ключ"
# или
export GOOGLE_API_KEY="ваш-ключ"

В проектах удобнее хранить ключи в файле .env и подгружать их до создания модели. Главное — .env должен быть в .gitignore:

from dotenv import load_dotenv

load_dotenv()  # до init_chat_model и create_agent

model = init_chat_model("openai:gpt-4o-mini")

#Проверка установки

Чтобы убедиться, что всё работает, создайте простого агента и отправьте ему запрос. Обратите внимание: обычная Python-функция с аннотациями типов и docstring уже годится как инструмент, оборачивать её декоратором не обязательно:

from langchain.agents import create_agent

def greet(name: str) -> str:
    """Поприветствовать пользователя."""
    return f"Привет, {name}!"

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[greet],
    system_prompt="Ты помощник. Используй инструменты, когда это уместно.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Поприветствуй меня, меня зовут Алексей"}]}
)
print(result["messages"][-1].content_blocks)

Агент вызовет инструмент greet и вернёт приветствие. Если это работает, установка прошла успешно.

Разберём, что вернулось. result — это состояние графа, а не строка. Ключ messages содержит всю историю: исходное сообщение пользователя, ответ модели с вызовом инструмента, ToolMessage с результатом и финальный ответ. Последнее сообщение — это ответ агента. Поле content_blocks даёт нормализованное представление содержимого (текст, рассуждения, изображения) в едином формате независимо от провайдера; если нужен просто текст, используйте .text.

#Когда агент не нужен

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

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

#Что использовать в каком случае

Если нужен агент с инструментами и понятным поведением — create_agent из LangChain. Для сложной оркестрации с условиями, параллелизмом и человеком в цикле — LangGraph напрямую. Если нужен агент «из коробки» с максимумом возможностей (планирование, файлы, субагенты) — Deep Agents. Для наблюдаемости, отладки и оценки — LangSmith, независимо от выбранного уровня.

Устранение неисправностей