LangChain и LangGraph: сборка агента в коде

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

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

LangChain подходит для типового агента: модель, инструкция, инструменты. Разработчики LangChain описывают агента как модель, которая вызывает инструменты в цикле, пока задача не решена. Все вокруг цикла (инструкцию, инструменты, промежуточные обработчики) они называют обвязкой.

Модель в LangChain задается одной строкой, а поставщиков библиотека поддерживает много: OpenAI, Anthropic, Google, открытые моделимодель с открытыми весами Модель с открытыми весами (open-weights model) это нейросеть, файлы параметров которой можно скачать и запустить на своем оборудовании. Подробнее в словаре через Ollama и другие. Для бизнеса это страховка: если поставщик модели станет недоступен или подорожает, программист меняет строку и пакет, а не переписывает агента.

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

LangGraph нужен, когда в одном процессе смешаны жесткие шаги и шаги, где решает модель, когда процесс идет долго и должен переживать сбои, когда на проверке нужен человек. Тем, кто только начинает, документация LangGraph советует сначала взять готовых агентов LangChain.

Anthropic в разборе от 19 декабря 2024 года советует начинать с простого решения и усложнять, только когда простое не справляется. Иногда это значит, что агент не нужен вовсе.

Для команды агентов с ролями есть отдельный фреймворк, CrewAI, мы разобрали его на соседней странице.

Первый агент на LangChain по документации собирается в четыре шага:

1. Проверьте, что установлен Python 3.10 или новее, и поставьте библиотеку: pip install -U langchain.

2. Поставьте пакет поставщика модели, они идут отдельно. Для открытых моделей на своем компьютере это пакет langchain-ollama: команда pip install -U langchain langchain-ollama. Сама Ollama запускает модель локально.

3. Опишите агента функцией create_agent: модель, список инструментов и системный промптсистемный промпт Системный промпт это постоянная инструкция для нейросети, которую разработчик задает до начала разговора: кто она, что ей можно, что нельзя и каким тоном отвечать. Подробнее в словаре, то есть постоянную инструкцию агенту. В примере документации локальная модель задается строкой «ollama:devstral-2».

4. Запустите агента методом invoke и передайте ему сообщение пользователя. Ответ лежит в последнем сообщении результата.

Когда готового цикла мало, процесс описывают графом в LangGraph. Граф строится из трех частей:

1. Состояние (State): общая структура данных, снимок текущей работы. Обычно в нем переписка и поля, которые нужны процессу.

2. Узлы (Nodes): функции, которые читают состояние, делают свою работу и возвращают обновление. Узлом может быть вызов модели, запрос в CRM или обычный расчет.

3. Ребра (Edges): правила перехода к следующему узлу. Они постоянные или условные, то есть зависят от того, что лежит в состоянии.

4. Соберите граф в классе StateGraph и скомпилируйте, после этого его можно запускать. Установка: pip install -U langgraph.

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

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

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

1. Напишите функцию на Python и поставьте над ней декоратор @tool. Декоратор это пометка над функцией, которая превращает ее в инструмент агента.

2. Укажите типы параметров. По документации они обязательны: из них строится описание входных данных.

3. Напишите строку документации функции коротко и по делу. По ней модель понимает, для чего инструмент и когда его звать.

4. Передайте функцию в список tools при создании агента.

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

1. Для краткосрочной памяти подключите checkpointer, хранителя снимков состояния. В примерах документации это InMemorySaver, он держит данные в памяти программы.

2. При каждом вызове передавайте thread_id, номер разговора. По нему агент продолжает тот же диалог.

3. Для долгосрочной памяти подключите store, хранилище, которое видно из всех разговоров. В примере документации это InMemoryStore.

Хранение в памяти программы годится для проверки: после перезапуска все пропадет. В рабочей системе снимки пишут в базу данных, документация описывает для этого PostgresSaver.

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

Опасные действия агента можно ставить на подтверждение человеком. В LangChain для этого есть промежуточный обработчик HumanInTheLoopMiddleware:

1. Добавьте HumanInTheLoopMiddleware в список middleware при создании агента.

2. В параметре interrupt_on перечислите инструменты, которые требуют решения человека: например запись файла или запрос к базе данных. Безопасные инструменты, такие как чтение, отметьте False.

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

4. Когда агент остановится, человек выбирает одно из решений: approve (выполнить как есть), edit (исправить параметры), reject (отклонить с объяснением) или respond (ответить вместо инструмента).

Библиотека не обязательна. Anthropic в статье о построении агентов советует разработчикам начинать с прямых вызовов API модели: многие схемы укладываются в несколько строк кода. API здесь значит способ, которым программа обращается к модели по сети.

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

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

Пример. Агенту нужно прочитать письмо клиента, найти заказ и предложить ответ менеджеру. Это один вызов модели с двумя инструментами и проверкой человеком, такой код короче, чем настройка библиотеки. Граф и память понадобятся, когда процесс растянется на дни и несколько систем.

Если разработчик предлагает библиотеку, спросите, как он будет видеть запросы к модели и ответы на них. Без этого любой странный ответ агента превращается в долгий поиск причины.

Типовой агент собирается из открытых блоков, и LangChain один из них. Если за такого агента просят как за уникальную разработку, спросите, из чего цена, и предложите оплату за результат по метрике, а не за часы.