LangChain / LangGraph Tutorial

Учебный репозиторий по разработке AI-агентов с использованием GigaChat, LangChain и LangGraph на Node.js.

---

Структура репозитория

langchain-tutorial/
├── gigachat_api_server/      # Express-сервер: прямая работа с GigaChat API
├── gigachat_rag_example/     # RAG-пример: обучение LLM на своих документах
└── langchain/
    └── node/                 # Основные примеры LangChain и LangGraph
        ├── src/
        │   ├── langchian/    # Примеры инструментов LangChain
        │   └── langraph/     # Примеры графов LangGraph
        └── docker-compose.yml

---

Встречи

Встреча 1

Подключение к GigaChat API и работа с LLM.

Папка	Что внутри
gigachat_api_server/	Express-сервер с прямыми вызовами GigaChat API, авторизация, история диалога, подсчёт токенов
gigachat_rag_example/	RAG: загрузка документов, эмбеддинги, ответы на вопросы по базе знаний

---

Встреча 2 — LangChain: инструменты

Папка: langchain/node/src/langchian/

Файл	Что демонстрирует
one_tool.js	Привязка одного инструмента к LLM, ручной вызов tool-call
multiple_local_tools.js	Несколько локальных инструментов без внешних API
multiple_tools.js	Несколько инструментов + Tavily поиск + PGVector (векторное хранилище)
message_formatter.js	Вспомогательная утилита для вывода истории сообщений

---

Встреча 3 — LangGraph: графы агентов

Папка: langchain/node/src/langraph/

Файл	Что демонстрирует
simple_graph.js	Базовый граф: состояние, узлы, рёбра, цикл
conditional_graph.js	Условные переходы, классификация запросов, обработка ошибок и fallback
hitl_review_node.js	Human-in-the-Loop (HITL): прерывание графа для ревью tool-call, три сценария — одобрить / изменить аргументы / отклонить с комментарием. Состояние сохраняется в PostgreSQL
render_graph.js	Отрисовка графа в Mermaid-формате
deep_agent/deep_agent.js	Deep Agents: планирование, инструменты, HITL через библиотеку deepagents

---

Быстрый старт

1. Клонировать репозиторий

git clone <repo-url>
cd langchain-tutorial

2. Настроить окружение

gigachat_api_server

cd gigachat_api_server
cp .env.example .env
# Заполни GIGACHAT_API_KEY
npm install
npm start

gigachat_rag_example

Смотри gigachat_rag_example/README.md.

langchain/node (LangChain + LangGraph примеры)

cd langchain/node
cp .env.example .env
# Заполни переменные (см. раздел «Переменные окружения»)
npm install

Запуск примеров:

# LangChain — инструменты
node src/langchian/one_tool.js
node src/langchian/multiple_local_tools.js
node src/langchian/multiple_tools.js

# LangGraph — графы
node src/langraph/simple_graph.js
node src/langraph/conditional_graph.js

# HITL — Human-in-the-Loop
node src/langraph/hitl_review_node.js "Найди последние новости по AI"
# Возобновить сессию по ID:
node src/langraph/hitl_review_node.js hitl-<thread-id>

# Deep Agents
node src/langraph/deep_agent/deep_agent.js "Твой запрос"
# Автоподтверждение без интерактива:
DEEP_AGENTS_AUTO_APPROVE=1 node src/langraph/deep_agent/deep_agent.js "Запрос"

---

Переменные окружения

gigachat_api_server .env

AUTH_URL=https://ngw.devices.sberbank.ru:9443/api/v2/oauth
AI_URL=https://gigachat.devices.sberbank.ru/api/v1/chat/completions
TOKENS_COUNT_URL=https://gigachat.devices.sberbank.ru/api/v1/tokens/count
GIGACHAT_API_KEY=ваш_ключ_из_Гига_чата

langchain/node .env

NODE_TLS_REJECT_UNAUTHORIZED=0

# GigaChat
GIGACHAT_API_PERS=<your_api_key>
GIGACHAT_CREDENTIALS=<your_api_key>

# PostgreSQL (для HITL и pgvector)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=langchain

# Внешние API
TAVILY_API_KEY=<your_api_key>
VSE_GPT_API_KEY=<your_api_key>

# Langfuse (трассировка, self-hosted)
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=http://localhost:3000

---

Docker: базы данных и Langfuse

Для примеров с PostgreSQL (HITL, pgvector) и трассировкой через Langfuse запусти:

cd langchain/node
docker-compose up -d

Что поднимается:

Контейнер	Порт	Назначение
langchain_pgvector	5432	PostgreSQL + pgvector (векторные эмбеддинги)
graph_agent_postgres	5433	PostgreSQL для сохранения состояния HITL-графа
langfuse_server	3000	UI трассировки запросов (http://localhost:3000)

После запуска Langfuse: зарегистрируйся на http://localhost:3000, создай проект и скопируй ключи в .env.

---

Стек технологий

Технология	Версия	Для чего
Node.js	≥ 18	Среда выполнения
LangChain	^0.3	Цепочки, инструменты, промпты
LangGraph	^0.2	Графы агентов, HITL, состояние
GigaChat SDK	^0.0.14	Модель: GigaChat-2
Tavily	—	Поиск в интернете (tool)
pgvector	—	Векторное хранилище для RAG
Langfuse	v2	Трассировка и наблюдаемость
Docker Compose	—	Локальная инфраструктура
deepagents	^1.8	Deep Agents с планированием