AI-агенты в Yandex DataLens

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

Для этого DataLens предоставляет три уровня интеграции:

Все три уровня построены поверх Public API и дополняют друг друга: навыки учат AI-агента, как работать с DataLens, а MCP-сервер и SDK дают ему возможность это делать.

Как это устроеноКак это устроено

AI-агент
  │
  ├── навыки datalens-skills ──── знания: модель объектов, установки, приемы
  │
  ├── MCP-сервер @datalens-tech/mcp ──┐
  │                                   ├──► Public API (api.datalens.tech)
  └── Python SDK datalens-sdk ────────┘

Public API DataLens доступно по адресу api.datalens.tech, описывается спецификацией OpenAPI и построено в RPC-стиле: вы вызываете именованные команды с JSON-параметрами. Спецификация OpenAPI доступна по адресу https://api.datalens.tech/json/. Для аутентификации используются IAM-токен Yandex Cloud и идентификатор организации в заголовке x-dl-org-id. Подробнее в разделе Работа с Public API.

Модель данных DataLens, с которой работает AI-агент:

Объекты — подключения, датасеты, чарты и дашборды — хранятся в воркбуках, а воркбуки — в коллекциях. Объекты ссылаются друг на друга по идентификаторам, поэтому AI-агенту важно строить их слева направо — ему это знание поставляют навыки.

MCP-серверMCP-сервер

MCP-сервер @datalens-tech/mcp открывает AI-агентам доступ к Public API по протоколу Model Context Protocol. При запуске сервер загружает OpenAPI-спецификацию API и превращает каждую команду в вызываемую операцию. Чтобы не регистрировать сотни отдельных инструментов и не переполнять контекст модели, сервер предоставляет компактный шлюз из трех инструментов:

Типичный сценарий работы AI-агента:

Этот путь хорошо подходит для интерактивных задач — навигации, инспекции объектов, точечных правок. Для создания сложных объектов, например Wizard-чартов, надежнее использовать Python SDK: через MCP AI-агент собирает конфигурацию объекта как сырой JSON без валидации на стороне клиента.

Python SDKPython SDK

datalens-sdk — типизированный Python SDK для API DataLens. Он подходит для всего, что нужно сохранить в виде кода: скрипты миграции, генерация дашбордов, экспорт и клонирование объектов, CI-автоматизация.

SDK — рекомендуемый инструмент для создания Wizard-чартов и в целом там, где важно качество автоматизированной визуализации. Конфигурация Wizard-чарта — сложная вложенная структура. SDK дает AI-агенту два преимущества, которых нет у прямых вызовов API: типизированные билдеры проверяют конфигурацию еще до отправки в API, а навык datalens-sdk снабжает AI-агента инструкциями по построению визуализаций, соответствующими установленной версии пакета. В результате AI-агент собирает чарты и дашборды предсказуемо валидными, а не подбирает структуру JSON методом проб и ошибок.

SDK и AI-агентыSDK и AI-агенты

Чтобы установить SDK для AI-агента, используйте навык datalens-sdk из коллекции datalens-skills.

Действия навыка:

• Подбирает безопасное Python-окружение проекта (venv, uv или Poetry) и устанавливает или обновляет пакет с подтверждением пользователя;
• Загружает инструкции по работе с SDK из установленного пакета, поэтому они всегда соответствуют фактической версии API, а не устаревшему снимку;
• Подключает слои с деталями конкретной установки DataLens, если они доступны в окружении.

После установки навыка достаточно сформулировать задачу — AI-агент сам выполнит подготовку окружения и напишет корректный код. Пример задачи:

Создай в воркбуке <идентификатор_воркбука> чарт-линию
по датасету <идентификатор_датасета>:
продажи по месяцам с разбивкой по регионам.

Что выбрать: MCP, SDK или APIЧто выбрать: MCP, SDK или API

Авторизация и переменные окруженияАвторизация и переменные окружения

По умолчанию сервер сам получает IAM-токен с помощью команды yc iam create-token: токен запрашивается при первом обращении к API и автоматически обновляется до истечения срока действия. Для этого обязательна переменная DATALENS_ORG_ID.

MCP-сервер и SDK поддерживают статическую авторизацию готовым IAM-токеном. Это позволяет использовать AI-агенты, когда Yandex Cloud CLI недоступен, например в изолированном окружении. Срок жизни IAM-токена — 12 часов, и обновлять его в этом режиме нужно самостоятельно.

Пример статической авторизации без Yandex Cloud CLI:

"env": {
  "DATALENS_ORG_ID": "<идентификатор_организации>",
  "DATALENS_YC_STATIC_AUTH": "1",
  "DATALENS_API_AUTH_HEADER": "Bearer <IAM-токен>"
}

Навыки (Agent Skills)Навыки (Agent Skills)

MCP-сервер и SDK дают AI-агенту доступ к API, но не знание предметной области: с какой установкой DataLens идет работа, как связаны объекты, в каком порядке их создавать, каких ошибок избегать. Эти знания поставляет репозиторий datalens-tech/datalens-skills — официальная коллекция навыков по открытому стандарту Agent Skills. Каждый навык — папка с файлом SKILL.md, опциональными скриптами и справочными материалами. Навыки переносимы между совместимыми AI-агентами.

Состав коллекцииСостав коллекции

Особенности и ограниченияОсобенности и ограничения

• На запросы к Public API действуют лимиты.
• Срок жизни IAM-токена — 12 часов. При авторизации через Yandex Cloud CLI MCP-сервер и SDK обновляют его автоматически. При статической авторизации обновление токена и перезапуск MCP-сервера — на стороне пользователя.
• AI-агент работает с объектами DataLens, но не интерпретирует бизнес-значения метрик и не взаимодействует с веб-интерфейсом. Например, AI-агент не может сделать скриншот или нажать кнопку.

Полезные ссылкиПолезные ссылки

• Использование Yandex DataLens с AI-агентами
• Работа с Public API в Yandex DataLens
• MCP-сервер @datalens-tech/mcp
• npm
• Коллекция навыков datalens-skills
• Python SDK datalens-sdk
• Стандарт Agent Skills
• Model Context Protocol