Интеграция с GigaChat

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

В этом разделе вы найдете информацию об авторизации в GigaChat API, потоковой передаче токенов и работе с инструментами (tools).

Управление токенами доступа

Для авторизации в GigaChat API используйте функцию SDK ensureFreshToken. Вызывайте ensureFreshToken() перед каждым обращением к invoke() или stream(). Менеджер токенов самостоятельно вернет кэшированный токен или запросит новый.

import { ensureFreshToken, type TokenManagerOptions } from "@sberdevices/agent-lab-sdk-ts";
import { GigaChat } from "langchain-gigachat";

const TOKEN_MANAGER_OPTS: TokenManagerOptions = {
  credentials: process.env.GIGACHAT_CREDENTIALS,
  scope: process.env.GIGACHAT_SCOPE,
  baseUrl: process.env.GIGACHAT_BASE_URL,
  authUrl: process.env.GIGACHAT_AUTH_URL,
  useGigachatAdvanced: true,
};

const llm = new GigaChat({
  model: "GigaChat-2-Max",
  credentials: process.env.GIGACHAT_CREDENTIALS,
  scope: process.env.GIGACHAT_SCOPE,
  baseUrl: process.env.GIGACHAT_BASE_URL,
  streaming: true,
});

// Перед каждым вызовом модели:
await ensureFreshToken(llm, TOKEN_MANAGER_OPTS);
const response = await llm.invoke(messages, config);

Описание менеджера токенов:

• токен хранится в /tmp/gigachat_token_{hash}.json и переиспользуется между перезапусками;
• токен не дожидается истечения срока и автоматически обновляется в диапазоне от 0 до 300 с;
• до трех попыток обновления со случайной задержкой от 1 до 5 с;
• обновление токена за 60 секунд до истечения срока expires_at;
• если задана переменная USE_TOKEN_PROVIDER_AGW=true, токен запрашивается через Agent Gateway.

Адрес авторизации

Адрес авторизации определяется автоматически:

Режим	Переменные	Адрес авторизации
Advanced	USE_GIGACHAT_ADVANCED=true	${GIGACHAT_BASE_URL}/token
Standard	USE_GIGACHAT_ADVANCED=false	GIGACHAT_AUTH_URL или https://ngw.devices.sberbank.ru:9443/api/v2/oauth
AGW	USE_TOKEN_PROVIDER_AGW=true	Через Agent Gateway

Пример:

function asBool(s?: string): boolean {
  return (s || "").toLowerCase().match(/^(1|true|yes|on)$/) !== null;
}

const USE_GIGACHAT_ADVANCED = asBool(process.env.USE_GIGACHAT_ADVANCED);

const GIGACHAT_AUTH_URL =
  process.env.GIGACHAT_AUTH_URL ||
  (USE_GIGACHAT_ADVANCED && GIGACHAT_BASE_URL
    ? `${GIGACHAT_BASE_URL.replace(/\/+$/, "")}/token`
    : undefined);

Работа с потоковой передачей токенов

Отключайте потоковую передачу токенов при работе со структурированными данными и подсказками.

Используйте потоковую передачу токенов в зависимости от сценария работы агента:

Сценарий	streaming	Причина
Диалоговый агент	true	Пользователь видит ответ по мере генерации
Генерация подсказок	false	JSON-ответ, не должен передаваться потоком в интерфейс
Structured output (JSON)	false	Парсер langchain-gigachat может сломаться на экранированных кавычках в потоке

Работа с инструментами (tools)

Ниже приводится пример описания инструмента и его привязки к объекту модели.

Создание инструментов

Инструменты описываются с помощью tool() из @langchain/core/tools и zod для схемы:

import { tool } from "@langchain/core/tools";
import { z } from "zod/v3";

const calculator = tool(
  async ({ expr }: { expr: string }) => {
    // Вычисление выражения
    return String(evaluate(expr));
  },
  {
    name: "calculator",
    description: "Вычисляет математические выражения",
    schema: z.object({
      expr: z.string().describe("Математическое выражение"),
    }),
  },
);

Привязка инструментов

Перед тем как привязать описанные инструменты с помощью метода bind() удаляйте поля $schema, format, default, additionalProperties:

const GIGACHAT_FUNCTIONS = (llm as any).formatStructuredToolToGigaChat(TOOLS);

function sanitizeSchema(obj: Record<string, any>): void {
  if (!obj || typeof obj !== "object") return;
  delete obj.$schema;
  delete obj.format;
  delete obj.default;
  delete obj.additionalProperties;
  for (const val of Object.values(obj)) {
    if (val && typeof val === "object") sanitizeSchema(val);
  }
}

for (const fn of GIGACHAT_FUNCTIONS ?? []) {
  if (fn.parameters) sanitizeSchema(fn.parameters);
}

// Привязка инструментов
const llmWithTools = llm.bind({
  tools: GIGACHAT_FUNCTIONS,
  tool_choice: "auto",
} as any);