Требования и рекомендации (TypeScript)

Обновлено 24 апреля 2026

В этом разделе вы найдете требования к агенту и рекомендации по организации проекта.

Требования

Для разработки публикации TypeScript-агента в GigaLab вам понадобится:

• Node.js версии 20 и выше;
• фреймворк LangGraph JS (npm-модуль @langchain/langgraph).
• файл .env с переменными окружения, в которых заданы основные параметры работы агента;
• Основные параметры работы агента определяются в переменных окружения.
• файл package.json с зависимостями агента;
• файл langgraph.json с описанием графа;
• локальный запуск агента с помощью команды langgraph dev.

Структура проекта

Общая структура репозитория с кодом агента:

my-agent/
├── langgraph.json              # Конфигурация графа
├── package.json                # Зависимости
├── .npmrc                      # Настройка npm-реестров
├── .env                        # Переменные окружения
└── agents/
    └── test_graph_js/
        └── graph.ts            # Основной файл агента (экспортирует graph)

Не сохраняйте файл с переменными окружения в remote-репозитории.

Пример langgraph.json

Файл указывает путь к графу агента:

{
    "dependencies": ["."],
    "graphs": {
        "test-graph-js": "./agents/test_graph_js/graph.ts:graph"
    }
}

Где:

• Ключ test-graph-js — идентификатор графа агента, который отображается в веб-интерфейсе GigaLab.
• Значение — путь к файлу и имя экспортируемой переменной (graph).

Пример package.json

Версии пакетов @langchain/core и @langchain/langgraph должны быть совместимы с версией в среде исполнения. Используйте диапазоны версий из примера ниже.

Пример минимального набора зависимостей:

{
  "name": "my-agent",
  "private": true,
  "dependencies": {
    "@langchain/core": ">=0.3.40 <0.4.0",
    "@langchain/langgraph": "^0.2.74",
    "@sberdevices/agent-lab-sdk-ts": "^0.1.1",
    "langchain-gigachat": "^0.0.14",
    "zod": "^4.3.6"
  }
}

Где:

Пакет	Описание
@langchain/core	Базовые типы сообщений, инструменты
@langchain/langgraph	Классы StateGraph, MessagesAnnotation, ToolNode
@sberdevices/agent-lab-sdk-ts	TS-версия GigaLab SDK
langchain-gigachat	Пакет для интеграции GigaChat и Langchain
zod	Валидация схем инструментов

Пример .npmrc

Файл .npmrc нужен для Docker-сборки. Без него npm install не найдет пакет @sberdevices/agent-lab-sdk-ts.

Создайте файл .npmrc:

registry=https://nexus.sberdevices.ru/repository/Npm/
@sberdevices:registry=https://nexus.sberdevices.ru/repository/npm-proxy/
legacy-peer-deps=true

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

Основные переменные (задаются в values-dev.yaml при публикации):

Переменная	Обязательность	Описание
GIGACHAT_MODEL	Нет	Модель GigaChat (по умолчанию GigaChat-Max)
GIGACHAT_CREDENTIALS	Да*	Ключ авторизации для получения токена доступа GigaChat API. Не указывайте, если токен доступа получается с помощью Agent Gateway (USE_TOKEN_PROVIDER_AGW=true)
GIGACHAT_SCOPE	Нет	OAuth scope (по умолчанию GIGACHAT_API_PERS)
GIGACHAT_BASE_URL	Да**	Базовый адрес GigaChat API. Обязательно указывайте при работе в регионе Advsnced (USE_GIGACHAT_ADVANCED=true)
USE_GIGACHAT_ADVANCED	Нет	Режим Advanced (true/false)
USE_TOKEN_PROVIDER_AGW	Нет	Использовать AGW для токенов (true/false)
GIGACHAT_VERIFY_SSL_CERTS	Нет	Проверка SSL (по умолчанию true)

Полный список переменных — в разделе Работа с секретами агента.

Рекомендации

При разработке агента следуйте рекомендациям:

• Используйте @sberdevices/agent-lab-sdk-ts для управления токенами — не реализуйте авторизацию вручную.
• Для обмена сообщениями с моделью используйте langchain-gigachat.
• Для передачи данных на фронтенд используйте поле additional_kwargs класса BaseMessage.
• Изолируйте код агента в отдельном репозитории в группе agents .