LangChain остаётся одним из самых популярных фреймворков для создания AI-агентов, работающих с большими языковыми моделями. Он позволяет соединять LLM с внешними инструментами, базами данных и API, давая возможность автоматизировать сложные рабочие процессы. В этом руководстве мы разберём, как настроить AI-агента с нуля, выбрать подходящие инструменты и избежать типичных ошибок – с учётом специфики российских моделей и сервисов.
Что такое AI-агент в LangChain
В терминах LangChain агент — это сущность, которая получает задачу, выбирает последовательность действий (инструментов) и выполняет их, возвращая результат. В отличие от простой цепочки (chain), агент может динамически решать, какие инструменты вызвать, и перебирать варианты, если что-то пошло не так.
Основные компоненты:
– LLM — модель, которая принимает решение. Для российских разработчиков доступны YandexGPT, GigaChat (Сбер) и другие, работающие через API.
– Инструменты — функции, которые агент может вызывать: поиск в интернете, чтение файлов, выполнение кода, запросы к государственным или корпоративным API.
– Память — хранит контекст диалога или историю вызовов. Для российских проектов особенно важно учитывать требования к хранению данных (ФЗ-152).
– Исполнитель (executor) — цикл, который управляет вызовами и обработкой ошибок.
Установка и первый агент с YandexGPT
Установка LangChain выполняется через pip:
bash
pip install langchain langchain-openai langchain-yandex
Для работы с YandexGPT потребуется API-ключ из Yandex Cloud. Его можно передать через переменную окружения `YANDEX_API_KEY` или указать в коде.
Простой агент, который может отвечать на вопросы и выполнять арифметику:
python
from langchain_yandex import YandexLLM
from langchain.agents import create_react_agent, AgentExecutor
from langchain.tools import tool
llm = YandexLLM(model=”yandexgpt/latest”, temperature=0)
@tool
def calculator(expression: str) -> str:
“””Выполняет математическое выражение.”””
return str(eval(expression))
tools = [calculator]
agent = create_react_agent(llm, tools)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
result = agent_executor.invoke({“input”: “Сколько будет 25 * 4 + 10?”})
print(result[“output”])
Этот код создаёт агента с одним инструментом — калькулятором. При запросе агент решает, нужно ли использовать калькулятор, и если да, вызывает его. Для GigaChat используйте аналогичный класс из `langchain_gigachat`.
Выбор инструментов: пример с курсом ЦБ РФ
Ключевая задача при настройке AI-агента — правильно подобрать инструменты. В LangChain есть встроенные наборы: для поиска в интернете (DuckDuckGo), работы с файлами, выполнения Python-кода (PythonREPL) и доступа к базам данных. Но для российских проектов часто нужны инструменты, работающие с локальными данными.
При создании собственного инструмента важно:
– Дать понятное описание на русском языке — LLM использует его для выбора правильного инструмента.
– Обрабатывать ошибки внутри инструмента, чтобы агент не «зависал».
– Не передавать конфиденциальные данные в открытом виде.
Пример инструмента для получения курса валют от Центрального банка России:
python
import requests
import xml.etree.ElementTree as ET
@tool
def get_cbr_rate(currency: str) -> str:
“””Возвращает курс валюты по данным ЦБ РФ. currency — трёхбуквенный код, например USD, EUR, CNY.”””
url = “http://www.cbr.ru/scripts/XML_daily.asp”
try:
response = requests.get(url, timeout=5)
root = ET.fromstring(response.content)
for valute in root.findall(“Valute”):
char_code = valute.find(“CharCode”).text
if char_code.upper() == currency.upper():
value = valute.find(“Value”).text
name = valute.find(“Name”).text
return f”{name}: {value} руб.”
return “Валюта не найдена”
except Exception as e:
return f”Ошибка при получении курса: {str(e)}”
Этот инструмент можно добавить в список tools агента. Описание на русском помогает YandexGPT корректно выбирать его при запросе «Какой сегодня курс доллара?».
Сравнение LangChain с другими фреймворками
| Фреймворк | Язык | Тип агентов | Популярность (GitHub stars) | Гибкость | Поддержка российских LLM |
|---|---|---|---|---|---|
| LangChain | Python | react, plan-and-execute, custom | 95k+ | Высокая | Есть (YandexGPT, GigaChat) |
| CrewAI | Python | ролевые агенты с очередями задач | 25k+ | Средняя | Требуется доработка |
| AutoGen | Python | диалоговые агенты, multi-agent | 35k+ | Высокая | Через OpenAI API (не для YandexGPT) |
| Semantic Kernel | C#, Python | плагинная архитектура | 22k+ | Средняя | Только через OpenAI |
LangChain выигрывает в количестве встроенных интеграций и документации, но требует больше кода для настройки сложных сценариев. CrewAI удобен для типовых задач с ролями, AutoGen — для симуляции диалогов между агентами. Для российских моделей LangChain остаётся лучшим выбором благодаря официальным интеграциям.
Типичные ошибки и их решение
Агент зацикливается. Если модель не может найти правильный инструмент, она может повторять один и тот же вызов. Решение: ограничить максимальное количество итераций (`max_iterations=5`) и добавить fallback-инструмент, например возврат сообщения «Не удалось выполнить запрос».
2. Некорректное описание инструмента. LLM может вызвать не тот инструмент, если описание нечёткое. Используйте конкретные глаголы и примеры в описании. Для YandexGPT лучше писать описания на русском.
3. Утечка контекста. Память агента не должна содержать чувствительные данные. Используйте отдельные сессии или очищайте историю после каждого запроса.
4. Ошибки в коде инструмента. Если инструмент выбрасывает исключение, агент может остановиться. Обёртывайте вызовы в try-except и возвращайте понятное сообщение об ошибке, как в примере с ЦБ РФ.
Что проверить перед развёртыванием
Перед тем как запускать агента в продуктивной среде, протестируйте его на наборе сценариев. Убедитесь, что:
– агент корректно обрабатывает неполные или противоречивые запросы (например, «привет» или «что-то про валюту»);
– инструменты не вызывают внешние сервисы без лимитов – для API ЦБ РФ установите таймаут и кэширование;
– стоимость вызовов LLM укладывается в бюджет (YandexGPT тарифицируется по токенам, можно ограничить количество шагов);
– данные не хранятся дольше необходимого – особенно если агент работает с персональными данными.
LangChain — это активный проект с частыми обновлениями. При появлении новых версий проверяйте changelog: в версии 0.3 изменили API для агентов, и старый код может потребовать адаптации. Официальная документация и примеры на GitHub остаются лучшим источником для актуальной информации. Для российских разработчиков также полезен канал LangChain в Telegram и сообщество в Habr.