Уроки, извлеченные из перехода на LangChain 1.0 в производственной среде

Что сработало, что сломалось и почему я это сделал.

Делиться

В конце октября 2025 года LangChain выпустил свою первую стабильную версию 1.0. После двух месяцев работы с их новыми API я искренне считаю, что это самая согласованная и продуманная версия LangChain на сегодняшний день.

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

Это не рекламный пост — мне бы очень хотелось узнать ваше мнение, пишите мне в личные сообщения!

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

Краткий обзор: LangChain, LangGraph и LangSmith.

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

LangGraph — это основанный на графах механизм выполнения, обеспечивающий надежные и управляемые рабочие процессы агентов с сохранением состояния. Наконец, LangSmith — это платформа для мониторинга и отслеживания, позволяющая осуществлять наблюдение.

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

Мой стек

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

Урок 1: Отказ от поддержки моделей Pydantic

Важным изменением при переходе на версию 1.0 стало введение нового метода create_agent. Он упрощает определение и вызов агентов, но также исключает поддержку моделей Pydantic и классов данных в состоянии агента. Теперь все должно быть выражено как TypedDicts, расширяющие AgentState.

Если вы используете FastAPI, Pydantic часто является рекомендуемым и используемым по умолчанию валидатором схемы. Я ценил согласованность схем во всей кодовой базе и считал, что смешивание TypedDicts и моделей Pydantic неизбежно вызовет путаницу — особенно у начинающих инженеров, которые могут не знать, какому формату схемы следовать.

Для решения этой проблемы я добавил небольшой вспомогательный класс, который преобразует модель Pydantic в TypedDict, расширяющий AgentState, непосредственно перед передачей его в create_agent. Важно отметить, что LangChain добавляет пользовательские метаданные к аннотациям типов, которые необходимо сохранять. Утилиты Python, такие как get_type_hints(), удаляют эти аннотации, а это значит, что простое преобразование не сработает.

Урок 2: Глубоко устроенные агенты изначально имеют собственное мнение.

Наряду с новым API create_agent в LangChain 1.0 появилось нечто, что привлекло мое внимание: библиотека deepagents. Вдохновленная такими инструментами, как Claude Code и Manus, библиотека deepagents позволяет планировать, разбивать задачи на этапы и даже создавать подагентов.

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

Библиотека deepagents довольно специфична и создана именно так. Каждый deep-агент поставляется с некоторыми встроенными промежуточными программами — такими как ToDoListMiddleware, FilesystemMiddleware, SummarizationMiddleware и т. д. Они определяют, как агент мыслит, планирует и управляет контекстом. Однако загвоздка в том, что вы не можете точно контролировать, когда именно запускаются эти промежуточные программы по умолчанию, и не можете отключить те, которые вам не нужны.

Изучив исходный код deepagents, можно увидеть, что параметр middleware — это дополнительное ПО, применяемое после стандартного. Любое ПО, переданное в middleware=[…], добавляется после значений по умолчанию.

Вся эта дополнительная оркестровка также внесла заметную задержку и может не принести существенной пользы. Поэтому, если вам нужен более детальный контроль, используйте более простой метод create_agent.

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

Моя любимая функция: структурированный вывод.

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

В LangChain 1.0 это значительно упрощено. Вы можете определить схему (например, модель Pydantic) и передать ее функции create_agent через параметр response_format. Затем агент выдает результат, соответствующий этой схеме , в рамках одного цикла работы агента без каких-либо дополнительных шагов.

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

Что я хочу изучить подробнее: промежуточное программное обеспечение (Middleware).

Одна из самых сложных задач при создании надежных агентов — это проектирование контекста , то есть обеспечение того, чтобы агент всегда имел нужную информацию в нужное время. Для предоставления разработчикам точного контроля над каждым этапом цикла работы агента было введено промежуточное ПО (middleware), и я думаю, что стоит подробнее изучить этот вопрос.

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

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

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

Этот список промежуточного ПО постоянно пополняется, и очень помогает то, что он остается независимым от провайдера. Если вы экспериментировали с промежуточным ПО в своей работе, мне было бы интересно узнать, что оказалось для вас наиболее полезным!

В заключение

На этом пока всё — четыре ключевых вывода из того, что я узнал о LangChain. И если кто-нибудь из команды LangChain это читает, я всегда рад поделиться отзывами пользователей или просто пообщаться 🙂

Удачи в строительстве!

Источник: towardsdatascience.com