GigaChat изнутри
Сверено с выпуском 0.36.0, 14.11.2026.
Статус: реализовано (Pulse 0.15.4+). Документ изначально писался до появления
встроенного ApiAgentSession (агент «Локальная модель»), поэтому вместо отдельного
цикла агента GigaChat переиспользует его — см. «Архитектура» ниже.
GigaChat в Pulse теперь две разные вещи, и путать их не стоит:
- агент — ведёт задачу, правит файлы, запускает команды (весь документ, кроме одноимённого раздела ниже);
- провайдер AI-действий — пишет сообщение коммита, имя stash, объяснение изменений и тексты PR (раздел «GigaChat как провайдер AI-действий»).
Ключ авторизации у них один — тот, что задан на карточке агента.
Цель: подключить GigaChat (Сбер) по ключу авторизации как ещё одного агента —
рядом с Claude Code, Kimi Code и Codex. У GigaChat нет ACP-адаптера и CLI с агентным
циклом, поэтому агент встроенный: main-процесс сам ведёт цикл
«модель → вызов инструмента → результат → модель» поверх HTTP API и превращает его в
те же SessionEvent, что и ACP-адаптеры. Для renderer разницы нет.
API (что известно)
| Что | Как |
|---|---|
| Авторизация | POST https://ngw.devices.sberbank.ru:9443/api/v2/oauth, заголовки Authorization: Basic <ключ>, RqUID: <uuid>, тело scope=GIGACHAT_API_PERS (или _B2B / _CORP) → access_token на 30 минут; обновляем за 3 мин до истечения (expires_at, нормализуем секунды → ms) |
| Модели | GET https://gigachat.devices.sberbank.ru/api/v1/models → список (GigaChat-2, GigaChat-2-Pro, GigaChat-2-Max, …) — это и есть config option «model» |
| Диалог | POST /api/v1/chat/completions с messages, functions (JSON-схемы инструментов), function_call: "auto", stream: true (SSE) |
| Вызов функции | ответ с finish_reason: "function_call" и delta.function_call {name, arguments} (целиком одним чанком, id нет); результат возвращается сообщением role: "function" со связью по имени |
| TLS | цепочка сертификатов НУЦ Минцифры; PEM корня лежит в resources/certs/russian_trusted_root_ca.pem (extraResources → <Resources>/certs/), подключается через https.Agent({ ca }). rejectUnauthorized: false не используем. Транспорт — node:https (пакет undici — транзитивная зависимость, в сборку не попадает) |
Ключ — секрет: хранить в userData/secrets.json с правами 0600 (значения зашифрованы
safeStorage), никогда не писать в транскрипт, логи и agent-config.json; в UI только
«задан / не задан» и хвост. access_token в логи не пишется (и так маскируется
net.redactForLog по ключам authorization/access_token).
Архитектура (как реализовано)
src/main/agents/
apiAgentSession.ts общий цикл «запрос → вызовы инструментов → результаты → запрос»:
flavor 'openai' | 'gigachat', hooks getAuthToken/fetchImpl
apiAgentStream.ts SSE-разбор: content, tool_calls (openai), function_call (gigachat), usage
apiAgentTools.ts инструменты read_file/write_file/edit_file/list_dir/search/bash (общие)
gigachat/
client.ts OAuth с кэшем токена (−3 мин до expires_at), models(),
createGigaChatFetch() — https.Agent с CA НУЦ
registry.ts gigachat: available = ключ задан; checkGigaChat() — кнопка «Проверить»
- Интеграция с ApiAgentSession — без прослойки-клиента чата: сессия получает
flavor: 'gigachat',fetchImpl: client.fetch(CA) иgetAuthToken: () => client.getToken()(токен спрашивается перед каждым запросом, кэш внутри клиента). Различия формата инкапсулированы в сессии и apiAgentStream:- запрос:
functions(=TOOL_SPECS.map(t => t.function)без обёрткиtype) +function_call: 'auto'вместоtools;stream_optionsне шлём (не поддерживается); - стрим:
delta.function_callкопится в apiAgentStream наравне сtool_calls; - история:
assistant { content, function_call { name, arguments } }→{ role: 'function', name, content }вместоtool_calls+role: 'tool'.
- запрос:
- Инструменты, разрешения (режим и доверие сессии: «Спросить · План · Агент» и «Спрашивать ·
Правки сами · Полный доступ» с матрицей типов действий), лимит 30 кругов, отмена через
AbortController, события
message/tool_call/tool_call_update/usage/compaction/turn_complete— общие с «Локальной моделью». Под границей чтения агента файловые инструменты закрыты, работа идёт черезbashв песочнице. - Config options:
model(из/modelsпосле «Проверить» или старта сессии; до этого — fallback GigaChat-2 / Pro / Max) — тот же чип композера; режим сессии — общие для всех агентов оси Pulse (см. Агенты и модели). - Usage:
usage.{prompt_tokens,completion_tokens}из финального SSE-чанка → событиеusage(окно по умолчанию 32k, как у локальной модели). Цены хода GigaChat не отдаёт: в истории сессий стоимость — «нет цены», денежный лимит на нём не срабатывает (см. Лимиты). - Scope из настроек карточки (
GIGACHAT_API_PERS/_B2B/_CORP, мусор → PERS) уходит в OAuth.
Настройки
Настройки → Модели → карточка GigaChat (раньше была в «Агентах»; тексты ошибок и
кнопка на странице «AI-функции» пока называют и открывают «Агенты»): поле «Ключ
авторизации» (пароль), выбор scope,
кнопка «Проверить» (IPC pulse:check-gigachat: OAuth + /models, показывает модели и
срок токена, модели кэшируются в agent-config.json как config option). Агент
available: true, когда ключ задан и агент включён.
GigaChat как провайдер AI-действий
AI-движок Pulse — это тексты, которые пишет не агент, а приложение по вашей кнопке: сообщение коммита, имя stash, объяснение изменений, заголовок и тело PR; через тот же движок идут план атомарных коммитов и AI-разрешение конфликтов. Провайдеров для них было четыре — CLI-агент, Anthropic, OpenAI и любой OpenAI-совместимый сервер; теперь в списке Настройки → AI-функции есть пятый, GigaChat (Сбер), сразу за CLI-агентом.
Ключ второй раз не вводится. Ключ авторизации Сбера один на приложение, лежит в
secrets.json под gigachatAuthKey и задаётся на карточке агента. Поэтому у провайдера
needsApiKey: false, а правду про доступ отдаёт отдельный метод hasCredentials — иначе
страница AI показала бы второе поле ключа, которое никто не читает. На месте поля стоит
строка «Ключ авторизации»: значок «ключ задан / не задан», кнопка перехода на карточку
агента и кнопка «Проверить».
«Проверить» — настоящий обмен ключа на токен, мимо живого клиента (fresh). Ответ
«работает» из кэша означал бы только «у нас ещё есть токен», а токен живёт полчаса: за это
время ключ могли отозвать, и Pulse объявил бы рабочим то, чего не знает.
Тип доступа (scope) и список моделей берутся оттуда же, откуда их берёт агент: scope — из карточки, модели — из её кэша после «Проверить», а до первой проверки — известный набор GigaChat-2 / Pro / Max. Подобранный клиентом scope запоминается в карточке.
Один клиент на время работы приложения. Провайдер собирается заново на каждое действие
(AIService.providerFor), поэтому транспорт живёт отдельно (cacheGigaChatTransport): без
этого каждое сообщение коммита заново меняло бы ключ на токен по OAuth, заново читало с
диска PEM корня НУЦ Минцифры и поднимало новый https.Agent, а трёхминутный кэш токена
внутри клиента не срабатывал бы ни разу. Клиент переживает вызовы, пока не сменились ключ
и scope.
Отказы названы по-разному, потому что лечатся по-разному:
| Что пришло | Что говорит Pulse |
|---|---|
| OAuth 401/403, «не подходит ни к одному типу доступа» | ключ отклонён — и сразу адрес: «Настройки → Модели → карточка GigaChat» |
| OAuth не дозвонился | сеть недоступна (менять рабочий ключ из-за обрыва связи человек не должен) |
| chat/completions 402 | у аккаунта нет доступных токенов для этой модели — пополнить пакет или выбрать модель из тарифа |
| 404 | модель аккаунту недоступна |
| 429 | слишком много запросов, повторите через минуту |
| пустой ответ | так и сказано; за текст не выдаётся |
Адрес карточки в тексте ошибки обязателен: окно (renderer/src/ai.ts) показывает слова
провайдера, только если он сам назвал раздел настроек. Без адреса человек получил бы общий
совет «проверьте ключ в Настройки → AI-функции», где у GigaChat поля ключа нет вовсе.
Границы
- Расшифровки речи через GigaChat нет. Микрофон в композере работает через провайдера AI, и у GigaChat эта дорога не сделана: кнопка не исчезает и ничего не обещает — в подсказке написано, что Pulse не расшифровывает речь через GigaChat, и предложен выход (OpenAI или свой сервер).
- Потоковой выдачи у AI-действий нет ни у одного провайдера. Ответ ждут целиком,
stream: false; у агента GigaChat поток есть, здесь его нет. - Остаток пакета токенов в AI-действиях не показывается. Клиент умеет спрашивать
/balance, и у агента остаток виден — чипом «лимит» в чате после каждого хода и в ответе кнопки «Проверить» на карточке. AI-действия его не запрашивают: про исчерпанный пакет там говорит только отказ 402, то есть задним числом. - На живом ключе Сбера эта дорога не проверялась. Все проверки — на фейковом сервере;
живой прогон (OAuth,
/chat/completions, ответ модели) остаётся ручным.
Тесты
ai/providers/gigachat.test.ts— провайдер AI-действий: форма запроса, модель по умолчанию из карточки, отказ без ключа и без моделей с адресом карточки, разбор 401 / 402 / 500, отмена во время OAuth, отсутствие PEM корня,verifyKeyкак настоящий OAuth, один клиент на два действия подряд, «Проверить» мимо кэша, смена ключа.renderer/src/aiErrors.test.ts— куда ведёт совет: слова провайдера с адресом раздела важнее общего текста про «Настройки → AI-функции».gigachat/client.test.ts— OAuth-кэш (без сети до истечения, обновление за 3 мин, секунды→ms, один in-flight на параллельные вызовы), форма OAuth-запроса, models(),/balance.apiAgentStream.test.ts— splitSse, tool_calls по индексу, function_call целиком и фрагментами, usage.apiAgentSession.test.ts— полный цикл обоих flavor на фейковом сервере: формат запроса (functions vs tools), история (function vs tool), события, пермиссия.registry.test.ts— available при ключе / без, модели из кэша, scope.
Живой прогон к API ключом владельца — вручную (кнопка «Проверить», затем задача с агентом GigaChat).