LangChain.js: ИИ-агенты, инструменты и память на TypeScript

LangChain.js, JavaScript- и TypeScript-библиотека LangChain, связывает языковую модель с инструментами и данными приложения. createAgent задаёт модель, функции и поведение агента. Модель предлагает вызовы, ваш код выполняет их, агент использует результаты в следующем шаге.

Агенты LangChain работают поверх LangGraph. Этот слой организует выполнение, состояние и остановки с продолжением. Для явного процесса с несколькими ветками можно использовать LangGraph напрямую; для обычного агента удобнее начать с createAgent.

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

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

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

Текущая инструкция установки рекомендует Node.js 22+. В package.json основного пакета ещё указан порог >=20; для нового проекта разумно следовать документации и требованиям выбранных интеграций. Устанавливайте пакет провайдера отдельно от ядра.

npm init -y
npm install langchain @langchain/core @langchain/openai zod
npm install -D tsx typescript

OPENAI_API_KEY=your-provider-key

import { createAgent, tool } from 'langchain';
import { z } from 'zod';

const total = tool(async ({ unitPrice, quantity }) => ({
  total: unitPrice * quantity,
}), {
  name: 'calculate_total',
  description: 'Calculate total in minor currency units.',
  schema: z.object({
    unitPrice: z.number().int().nonnegative(),
    quantity: z.number().int().positive(),
  }),
});

const agent = createAgent({
  model: 'openai:gpt-5.5',
  tools: [total],
});

async function main() {
  const result = await agent.invoke({
    messages: [{ role: 'user', content: 'Посчитай 3 товара по 12900 копеек.' }],
  });
  console.log(result.messages.at(-1)?.content);
}
main().catch(console.error);

npx tsx --env-file=.env agent.ts

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

tool() принимает функцию и описание. Поле schema задаёт вход через Zod; description объясняет модели, когда функцию следует использовать. Возвращаемое значение становится результатом инструмента. Для закрытых данных проверяйте пользователя внутри серверного пути выполнения.

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

Данные сессии и прочий контекст можно передавать отдельно от текста модели. Не рассчитывайте, что модель правильно восстановит пользователя из разговора: идентификатор и права определяются приложением.

responseFormat задаёт формат конечного ответа агента. LangChain проверяет данные и возвращает их в structuredResponse. Можно передать Zod, схему Standard Schema или JSON Schema.

import { createAgent } from 'langchain';
import { z } from 'zod';

const classifier = createAgent({
  model: 'openai:gpt-5.5',
  tools: [],
  responseFormat: z.object({
    topic: z.enum(['delivery', 'payment', 'other']),
    summary: z.string(),
  }),
});

async function main() {
  const result = await classifier.invoke({
    messages: [{ role: 'user', content: 'Заказ не доставили. Нужно узнать статус.' }],
  });
  console.log(result.structuredResponse);
}
main().catch(console.error);

Агент выбирает поддерживаемую стратегию: нативный ответ провайдера либо дополнительный вызов инструмента для выдачи объекта. При необходимости поведение задают явно через providerStrategy или toolStrategy. Если одновременно нужны обычные инструменты и JSON-ответ, модель должна поддерживать такое сочетание.

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

Checkpointer сохраняет состояние агента между обращениями. thread_id объединяет запросы в одну беседу. Для прототипа подходит MemorySaver из @langchain/langgraph, который держит состояние в оперативной памяти процесса.

npm install @langchain/langgraph

import { createAgent } from 'langchain';
import { MemorySaver } from '@langchain/langgraph';

const assistant = createAgent({
  model: 'openai:gpt-5.5',
  tools: [],
  checkpointer: new MemorySaver(),
});

async function main() {
  const config = { configurable: { thread_id: 'demo-conversation' } };
  await assistant.invoke({ messages: [{ role: 'user', content: 'Меня зовут Анна.' }] }, config);
  const result = await assistant.invoke({
    messages: [{ role: 'user', content: 'Как меня зовут?' }],
  }, config);
  console.log(result.messages.at(-1)?.content);
}
main().catch(console.error);

После остановки процесса MemorySaver теряет историю. Для рабочего сервиса выбирают постоянный checkpointer, например PostgreSQL или MongoDB. Идентификатор беседы сверяют с правами пользователя на сервере; фиксированное demo-conversation годится только для примера.

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

humanInTheLoopMiddleware проверяет инструменты по заданной политике и может остановить запуск. Пользователь одобряет действие, меняет аргументы либо отклоняет его с объяснением. Чтобы потом продолжить выполнение, нужен checkpointer и идентификатор беседы.

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

LangChain передаёт текст модели, обновления состояния и пользовательские события. Для новых приложений документация рекомендует event streaming: у отдельных проекций есть собственные итераторы. Это позволяет читать текст и вызовы инструментов независимо.

import { createAgent } from 'langchain';

const assistant = createAgent({ model: 'openai:gpt-5.5', tools: [] });

async function main() {
  const events = await assistant.streamEvents({
    messages: [{ role: 'user', content: 'Объясни, как работает память диалога.' }],
  }, { version: 'v3' });
  for await (const message of events.messages) {
    for await (const token of message.text) process.stdout.write(token);
  }
  await events.output;
}
main().catch(console.error);

Для веб-чата сервер преобразует эти события в выбранный транспорт, а UI отображает их. Если уже используете клиент другого SDK, проверьте совместимость формата. Поток LangChain сам по себе не станет корректным потоком useChat из TanStack AI или Vercel AI SDK.

RAG, ответ модели с поиском по внешним знаниям, начинается с подготовки источников. Документы разбирают, делят на фрагменты и делают доступными для поиска. Retriever, компонент извлечения фрагментов, или инструмент поиска возвращает материалы модели.

Docling и MinerU полезны на этапе разбора сложных файлов. LangChain.js может занять следующий этап: подключить поиск и использовать найденные данные в агенте. Ни один общий фреймворк не гарантирует качество ответа, если нужный фрагмент не попал в контекст.

Для локальной генерации есть @langchain/ollama и ChatOllama. Модель должна быть заранее загружена и доступна приложению. Для агента отдельно проверяйте поддержку tool calling и structured output выбранной моделью. Локальный сервер модели не отменяет внешние обращения ваших инструментов.

Библиотеку запускают в Node.js и других совместимых JavaScript-средах. Реальная переносимость зависит от конкретных интеграций и их зависимостей: код, который подходит Node.js, может требовать изменений для edge-среды.

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

Расходы складываются из вызовов модели, хранилища, внешних API и выбранных сервисов. История и повторные шаги увеличивают объём запросов. Для рабочего процесса задайте понятные пределы, а сбои функций обрабатывайте так, чтобы повторное выполнение не создавало дубликаты.

LangChain.js распространяется по MIT: разрешены коммерческое использование, изменения и распространение при сохранении уведомления об авторских правах и текста лицензии. Код предоставляется без гарантий. У моделей и сервисов отдельные условия.

Основной пакет langchain в исходниках имеет версию 1.5.16. GitHub-релиз @langchain/google@0.2.10 относится к интеграции Google, а не к версии langchain. При обновлении проверяйте совместимость langchain, @langchain/core, провайдера и слоя LangGraph.

LangChain.js стоит выбрать, когда нужен агент с инструментами, сохранением состояния и работой с данными. Для чата, тесно связанного с React-интерфейсом, сравните TanStack AI и Vercel AI SDK: у них свои UI-пакеты и способы передачи сообщений. Полные обзоры связаны в таблице ниже.

• LangChain.js на GitHub
• Официальный сайт LangChain
• Документация LangChain.js