Сбер ИИ-агенты: как создать агента на GigaChat

Под ИИ-агентами Сбера обычно понимают приложения на базе GigaChat, которые могут выбрать действие, вызвать подключённую функцию и использовать её результат в ответе. Для первого прототипа достаточно проекта GigaChat API, одной безопасной функции и набора тестов. Если нужен только разговор или поиск по справке, обычный чат проще агентной схемы.

Что у Сбера называется агентом

Это не одно отдельное приложение с названием «Сбер ИИ-агент». В официальной документации есть GigaChat API для работы с моделью и GigaChain для сборки приложений. Руководство GigaChain определяет агента как систему, где языковая модель рассуждает, выбирает действие и определяет входные данные для инструмента.

Граница проста: чат формирует текст, агент может запросить функцию. Саму функцию выполняет ваш код, а не модель. Например, модель подготавливает аргументы для поиска заказа, сервер проверяет права и обращается к тестовой базе, затем результат возвращается модели. Если эта граница пока не ясна, сначала полезно прочитать объяснение ИИ-агента простыми словами.

Правило выбора: если задачу можно решить одним ответом без внешнего действия, оставьте чат. Агент нужен, когда результат зависит от инструмента, состояния и контролируемого следующего шага.

Карта результата первого прототипа

Хороший первый результат не продаёт, не удаляет и не меняет реальные данные. Он принимает понятный вопрос, вызывает одну функцию чтения, показывает источник и корректно останавливается при ошибке.

• Исходная ситуация: есть проект GigaChat API, тестовые данные и одна задача с назначенным владельцем.
• Ожидаемый результат: агент находит запись по безопасному идентификатору и возвращает проверяемый ответ.
• Обязательные шаги: авторизация, описание функции, вызов модели, проверка аргументов, выполнение инструмента и финальный ответ.
• Способ проверки: фиксированные удачные, ошибочные и опасные входы с ожидаемым результатом.
• Частые сбои: неверная схема функции, нет прав, модель не вызывает инструмент или вызывает его повторно.
• Ограничения: модель не должна напрямую владеть ключами, обходить серверную проверку и выполнять опасное действие без подтверждения.
• Когда способ не подходит: справочный FAQ без действий, юридически значимое решение или процесс без безопасной тестовой среды.

Что подготовить до кода

Сначала создайте проект в личном кабинете GigaChat API и храните данные авторизации вне текста промпта и репозитория. Официальная документация авторизации указывает единый целевой адрес API для новых подключений. Старые примеры могут содержать прежний адрес, поэтому сверяйте код с текущей справкой.

Для функции выберите действие только для чтения: получить тестовый статус заказа, найти статью в демонстрационной базе или вернуть расписание из заранее подготовленного файла. Не начинайте с оплаты, отправки сообщения клиенту, изменения CRM или удаления записи.

1. Запишите один вопрос пользователя и точный ожидаемый ответ.
2. Опишите функцию: имя, назначение, обязательные поля и формат результата.
3. Создайте тестовые данные без персональной информации.
4. Ограничьте инструмент чтением и разрешите только нужные записи.
5. Задайте тайм-аут, обработку ошибки и предел повторных вызовов.
6. Подготовьте журнал без ключей и лишних данных пользователя.

По теме: Комментарии в MAX: как настроить бота для канала

Подключите одну функцию

GigaChat поддерживает режимы работы с функциями. В [официальном описании function_call](https://developers.sber.ru/docs/ru/gigachat/guides/functions/function-calling-modes) есть none, auto и принудительный выбор функции по имени. Для обычного агента подходит auto, но ваш сервер всё равно обязан проверить название функции и каждый аргумент перед исполнением.

Безопасный контракт можно сформулировать без привязки к библиотеке. Модель получает только описание доступного действия. Ключ базы и реальный запрос остаются в серверной части.

function: get_demo_order_status
input: { order_id: string }
allowed: only IDs from the demo dataset
result: { status: string, updated_at: string }
on_error: return a structured error, do not retry more than once

После ответа модели извлеките аргументы, проверьте тип и допустимое значение order_id, затем вызовите функцию отдельно. Результат инструмента передайте модели как новый шаг. Не позволяйте модели подставлять произвольный адрес, SQL или имя файла вместо ограниченного идентификатора.

Когда использовать GigaChain и MCP

Для одного вызова можно работать напрямую с API и собственным кодом. GigaChain полезен, когда нужны готовая агентная петля, память диалога и несколько инструментов. Сначала доведите один сценарий до стабильности, затем добавляйте второй.

Если инструменты уже предоставляются через MCP, официальный пример агента GigaChat с MCP-сервером показывает два варианта клиента и использует GigaChat вместе с LangChain, LangGraph и адаптером MCP. MCP упрощает подключение, но не выдаёт права автоматически. Разрешения, сетевые границы и подтверждение опасных действий остаются вашей ответственностью.

По теме: Уязвимости ИИ-агентов OpenClaw: как проверить и защитить

Проверьте агента по тестовой матрице

Один успешный пример не доказывает готовность. Прогоните одинаковые тесты после каждой правки промпта, схемы или модели.

• Нормальный вход: существующий тестовый идентификатор, функция вызывается один раз, ответ совпадает с данными.
• Неизвестный идентификатор: агент сообщает, что запись не найдена, и не придумывает статус.
• Пустой ввод: агент просит идентификатор, а не вызывает функцию с пустым значением.
• Запрещённый ввод: попытка передать команду или чужой адрес отклоняется валидатором.
• Ошибка инструмента: агент показывает понятный сбой и не заявляет об успешном действии.
• Повтор сообщения: внешний вызов не дублируется без необходимости.
• Опасная просьба: агент объясняет границу и не меняет данные.

Фиксируйте вход, выбранную функцию, очищенные аргументы, код результата и итоговый ответ. Не записывайте ключ авторизации и полное содержимое чувствительных данных. Отдельный подход к приёмке описан в чек-листе проверки ИИ-агента.

Диагностика по симптому

Модель отвечает текстом и не вызывает функцию.

Проверьте, что функция передана в запросе, её описание соответствует задаче, а режим не установлен в none. Затем упростите тест до одного однозначного действия.

Функция получает пустые или неверные аргументы.

Сделайте обязательные поля явными и добавьте серверную валидацию. Ошибка схемы должна останавливать вызов, а не исправляться догадкой модели.

Агент повторяет действие после тайм-аута.

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

Локальный пример работает, серверный нет.

Сравните адрес API, сертификаты, переменные окружения, сетевой доступ и версии библиотек. Не отключайте проверку сертификатов как постоянное решение только потому, что так сделано в старом учебном примере.

По теме: Как сделать бота для Instagram: автоответы по правилам Meta

Ограничения, тарифы и коммерческое использование

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

Не поручайте агенту самостоятельное кредитное, медицинское, кадровое или другое значимое решение. Если результат нельзя объяснить и воспроизвести, оставьте его подсказкой человеку.

Частые вопросы

Можно ли сделать агента без GigaChain?

Да. Для одной функции достаточно GigaChat API и собственного серверного цикла. Фреймворк полезен, когда растёт число инструментов и состояний.

Нужен ли MCP?

Нет. MCP удобен для стандартного подключения инструментов, но простой внутренний метод можно вызвать напрямую. Выбирайте вариант с меньшим числом неподконтрольных слоёв.

Может ли агент менять данные?

Технически да, если вы дадите такой инструмент. Для первого проекта оставьте только чтение, затем добавляйте изменения по одному с подтверждением и защитой от повтора.

Как понять, что прототип готов?

Он проходит всю тестовую матрицу, не скрывает ошибки, не выходит за права и позволяет связать ответ с конкретным вызовом инструмента.