Доступ к GigaChat API

Обновлено 9 июня 2026

Для авторизации запросов в GigaChat API агенту нужен токен доступа, который можно получить с помощью частных или совместных авторизационных данных:

• Частные данные доступны одному агенту. Это может быть ключ доступа или логин и пароль, в зависимости от региона GigaChat API (Enablers или Advanced). Частные данные задаются в переменных окружения агента или передаются при инициализации модели.

• Совместные данные доступны заданы в конфигурации GigaLab и доступны всем агентам, которые работают в сервисе. Работа с совместными данными накладывает ограничения на частоту запросов и количество параллельных потоков.

  Вы можете добавить в конфигурацию GigaLab отдельные совместные авторизационные данные, которые будут доступны только вашим агентам.

В этом разделе вы найдете примеры получения токена доступа и авторизации запросов в GigaChat API с помощью SDK.ы

Получение токена доступа GigaChat API

В общем случае, получение и обновление токена происходит автоматически при вызове метода get_model(). Метод проверяет авториационные данные, указанные в переменных окружения, и использует подходящий менеджер токенов:

• GigaChatTokenManager — запрашивает токен в GigaChat API и кеширует его в файл. Используйте его при работе с частными данными для авторизации;
• AgsTokenManager — получает токен с помощью Agent Service вместе с лимитами модели и метаданными подключения. Используйте его при работе с совместными авторизационными данными, заданными в GigaLab;
• AgwTokenManager — получает токен с помощью Agent Gateway. Устаревший механизм. Используйте вместо него AgsTokenManager.

О том как работать с токенами GigaChat API в TypeScript-агенте — читайте ниже.

Работа с частными авторизационными данными

Для работы с частными авторизационными данными используется менеджер GigaChatTokenManager. Он вызывается по умолчанию при инициализации модели с помощью get_model():

from agent_lab_sdk.llm import get_model

llm = get_model(type="chat", throttled=True)
response = llm.invoke("Привет!")

Вы можете изменить менеджер токенов, заданный по умолчанию.

Полученный токен менеджер кеширует в JSON-файле. Файл сохраняется по адресу /tmp/gigachat_token_<hash>.json, где хеш создается автоматически на основе заданных авторизационных данных. Чтобы переопределить путь к файлу с токеном, задайте переменную окружения GIGACHAT_TOKEN_PATH.

При работе с менеджером GigaChatTokenManager доступны переменные окружения:

Переменная	Описание
GIGACHAT_CREDENTIALS	Ключ авторизации GigaChat API для авторизации в регионе Enablers
USE_GIGACHAT_ADVANCED	Включает работу в регионе Advanced. По умолчанию выключено
GIGACHAT_USER	Логин для авторизации в регионе Advanced
GIGACHAT_PASSWORD	Пароль для авторизации в регионе Advanced
GIGACHAT_SCOPE	Версия API при работе в регионе Enablers: GIGACHAT_API_PERS или GIGACHAT_API_CORP
GIGACHAT_AUTH_URL	Адрес для получения токена. По умолчанию — ngw.devices.sberbank.ru
GIGACHAT_TOKEN_PATH	Путь к файлу кеша токена. По умолчанию — /tmp/gigachat_token_<hash>.json
GIGACHAT_TOKEN_FETCH_RETRIES	Количество попыток при ошибке. По умолчанию — три

Самостоятельное управление токеном

Для самостоятельного управления получением и обновлением токена доступа:

1. Получите токен доступа с помощью метода get_token().
2. Инициализируйте модель с полученным токеном и аргументом manage_access_token=False, который отключает автоматическое обновление токена.

Пример:

from agent_lab_sdk.llm import GigaChatTokenManager

token = GigaChatTokenManager.get_token()

llm = get_model(type="chat", manage_access_token=False, access_token=token)

При получении токена вы также можете явно передать авторизационные данные и другие параметры — они переопределяют переменные окружения:

token = GigaChatTokenManager.get_token(
    credentials=os.getenv("GIGACHAT_CREDENTIALS"),
    scope="GIGACHAT_API_CORP",
    auth_url="https://ngw.devices.sberbank.ru:9443/api/v2/oauth",
)

Работа с совместными авторизационными данными

Агенты, опубликованные в GigaLab, могут получать токен GigaChat API с помощью авторизационных данных, заданных в сервисе. Для этого используется менеджер AgsTokenManager:

from agent_lab_sdk.llm.managers.ags_token_manager import AgsTokenManager
import os

token_info = AgsTokenManager.get_token(
    agent_id=os.getenv("AGENT_SERVICE_NAME"),
    credential_id=os.getenv("SDK_AGENT_LAB_GIGACHAT_CREDENTIAL_ID"),
)
print(token_info["token"])
print(token_info["metadata"]["baseUrl"])
print(token_info["limits"])

Помимо токена менеджер возвращает лимиты модели (частота запросов, параллельные потоки) и метаданные подключения (base_url, scope).

Вы можете задать AgsTokenManager в качестве менеджера по умолчанию, который будет использоваться при вызове get_model().

При работе с менеджером AgsTokenManager доступны переменные окружения:

Переменная	Описание
SDK_AGENT_LAB_USE_TOKEN_PROVIDER_AGS	После включения менеджер будет работать по умолчанию при вызове get_model(). Возможные значения: true/false или 1/0. По умолчанию выключен
AGENT_SERVICE_NAME	Имя агента заданное в langgraph.json
SDK_AGENT_LAB_GIGACHAT_CREDENTIAL_ID	Идентификатор авторизационных данных, доступных в GigaLab

Использование менеджера по умолчанию

Чтобы при вызове get_model() вместо менеджера GigaChatTokenManager использовать AgsTokenManager задайте переменные окружения:

SDK_AGENT_LAB_USE_TOKEN_PROVIDER_AGS=true
AGENT_SERVICE_NAME=имя-агента
SDK_AGENT_LAB_GIGACHAT_CREDENTIAL_ID=идентификатор-авторизационных-данных
GIGACHAT_MODEL=GigaChat-2-Max

Добавление совместных авторизационных данных

Ваши агенты могут использовать совместные авторизационные данными, заданные в конфигурации GigaLab под собственным идентификатором.

Чтобы добавить данные в конфигурацию GigaLab обратитесь в поддержку. В процессе настройки вам понадобится передать:

• идентификатор клиента (Client ID);
• ключ (Client Secret);
• адрес сервера GigaChat API;
• версию (scope) GigaChat API.

Передавайте идентификатор клиента и ключ только при личном общении, чтобы избежать компрометации учетных данных.

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

Для авторизации в GigaChat API используйте функцию SDK 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);

Смотрите также

Работа с секретами

Как хранить ключи и токены безопасно

Локальная разработка

Как запустить агента локально