GraphQL для ИИ-агента: как команда СберТеха превращает операции в MCP-инструменты

Данил, TypeScript-разработчик команды Platform V DataSpace в СберТехе, описал путь от постановки задачи до работающего генератора. DataSpace даёт визуальную (low-code) среду для бизнес-приложений и управления данными. API построен на GraphQL. Когда встал вопрос, как пустить к этому API ИИ-агента, команда прошла через четыре варианта адаптеров и остановилась на кодогенерации из фиксированных операций.

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

Что понадобится?

• GraphQL-схема вашего API и набор уже написанных GraphQL-операций (запросы и мутации)
• Node.js и TypeScript
• Библиотека Zod (инструмент валидации данных на TypeScript, работает как контракт: описывает, какой формы данные допустимы)
• Понимание, что такое MCP (Model Context Protocol, протокол, через который ИИ-агент обнаруживает доступные инструменты, узнаёт их параметры и вызывает внешние системы по единому стандарту)
• Примерно 2 часа на первый прототип, если GraphQL-операции уже есть

Четыре варианта адаптера и почему команда выбрала четвёртый

Прежде чем строить, полезно понять ландшафт. Команда DataSpace рассмотрела четыре подхода, каждый из которых даёт агенту разный уровень свободы.

1. Один универсальный инструмент для произвольных запросов. Агент сам пишет GraphQL-запрос и передаёт переменные. Пример такой реализации есть у Microsoft Fabric. Подход максимально гибкий: одного инструмента хватает, чтобы начать. Но модель берёт на себя ответственность за корректность запроса, а команда бэкенда анализирует только уже выполненные запросы. Годится для прототипов и локальной разработки.

2. Инструменты из корневых полей схемы. MCP-инструменты создаются автоматически из корневых полей типов Query и Mutation. Агент получает готовый набор с именами и аргументами. Быстро открывает API, но схема часто шире того контракта, который разумно отдать агенту.

3. Инструменты из фиксированных операций. Каждый MCP-инструмент соответствует заранее написанной операции. Агент выбирает инструмент и заполняет переменные, а текст запроса зафиксирован разработчиком. Операции хранятся в репозитории, проходят код-ревью, проверяются по схеме. Так команда бэкенда сохраняет полный контроль. Примеры: Apollo MCP Server, WunderGraph Cosmo MCP Gateway, GraphQL Hive MCP plugin.

4. Кодогенерация из фиксированных операций (выбор DataSpace). Развитие третьего подхода. Операции остаются источником истины, но из них генерируются TypeScript-типы, Zod-схемы (контракты валидации) и объявления MCP-инструментов. Похожую идею развивает Lab Digital в проекте graphql-codegen-mcp-tools.

Команда DataSpace выбрала четвёртый вариант, потому что GraphQL-разработчики продолжают описывать контракт привычными операциями, а агент получает ограниченный набор инструментов вместо всего API.

Пошаговая инструкция

1. Соберите GraphQL-операции, которые агент должен уметь вызывать. Каждая операция описывает одно действие: получить список заказов, создать клиента, обновить статус. Храните их в отдельных .graphql-файлах в репозитории.

2. Подготовьте GraphQL-схему. Она уже есть, если вы работаете с GraphQL-бэкендом. Схема нужна генератору для проверки операций.

3. Настройте генератор. На вход подаются:

4. GraphQL-схема
5. набор операций
6. конфигурация и список плагинов

7. описания и аннотации инструментов

8. Запустите кодогенерацию. Генератор создаёт:

9. TypeScript-типы для переменных и результатов
10. Zod-схемы для валидации входных данных
11. объявления MCP-инструментов с именами, описаниями и параметрами

12. вспомогательный код для регистрации инструментов на MCP-сервере

13. Зарегистрируйте сгенерированные инструменты на MCP-сервере. Агент подключается к серверу по протоколу MCP, обнаруживает доступные инструменты и вызывает их, передавая переменные.

14. Проверьте diff в CI. Любое изменение операции, новое обязательное поле, удалённый инструмент, изменённый enum, видно в сгенерированном коде до того, как агент попробует вызвать инструмент.

Что с этим делать прямо сейчас, по ролям?

Разработчику на GraphQL. Если у вас уже есть GraphQL API, попробуйте собрать пять-десять операций, которые покрывают основные сценарии, и прогнать через генератор. Вы увидите, насколько точно модель понимает ваши инструменты и где описания нужно уточнить.

Автору и маркетологу. Подход DataSpace показывает, как корпоративные API становятся доступны ИИ-агентам без потери контроля. Если вы пишете про автоматизацию бизнес-процессов, это конкретный кейс российской команды, а не пересказ западного блога.

Предпринимателю в РФ. Platform V DataSpace доступен через экосистему Сбера. Если ваш бизнес уже использует эту платформу, подключение ИИ-агента к API через MCP не требует смены стека. Для тех, кто работает с другими GraphQL-бэкендами, логика та же: фиксированные операции плюс кодогенерация работают с любым GraphQL.

Разбор DataSpace показывает ясную вещь: GraphQL для ИИ-агента подключается не «волшебным коннектором», а осознанным выбором границ. Операции фиксируются, код генерируется, агент работает в рамках, которые задал разработчик. Если у вас есть GraphQL API, начните с пяти операций и одного агента, результат покажет, стоит ли масштабировать.