AI agents in Yandex DataLens

In DataLens, AI agents act as a robust automation tool. They can create and modify connections, datasets, charts, and dashboards, analyze dependencies between objects, and also clone and move content between workbooks.

To this end, DataLens delivers three levels of integration:

All three layers are built on top of the Public API and complement each other: skills teach your AI agent how to work with DataLens, while the MCP server and SDK provide the capabilities to do so.

How it worksHow it works

AI agent
  │
  ├── datalens-skills ──── knowledge: object model, installations, practices
  │
  ├── @datalens-tech/mcp MCP server ──┐
  │                                   ├──► Public API (api.datalens.tech)
  └── Python SDK datalens-sdk ────────┘

The DataLens Public API is available at api.datalens.tech. Described by an OpenAPI specification, it uses the RPC style: you run named commands with JSON parameters. The OpenAPI specification is available at https://api.datalens.tech/json/. For authentication, you need to provide a Yandex Cloud IAM token and the organization ID in the x-dl-org-id header. For more information, see Working with the Public API.

Here is the DataLens data model the AI agent operates:

Objects, i.e., connections, datasets, charts, and dashboards, are stored in workbooks, while workbooks reside in parent collections. Because objects reference each other by IDs, it is critical for the AI agent to build them from left to right: the agent derives this knowledge from skills.

MCP serverMCP server

The @datalens-tech/mcp MCP server exposes the Public API to AI agents via the Model Context Protocol. Upon startup, the server loads the OpenAPI specification and converts each command into a callable operation. To avoid registering hundreds of individual tools and preclude the model's context overflow, the server provides a compact gateway consisting of three tools:

Here is a standard AI agent workflow:

This flow is well suited for interactive tasks, such as navigation, object inspection, or granular edits. However, if you need to create complex objects, e.g., wizard charts, the Python SDK is a more reliable option: via MCP, the AI agent compiles the object configuration as raw JSON, without client-side validation.

Python SDKPython SDK

datalens-sdk is a typed Python SDK for the DataLens API. It works well for any task you want saved as code: migration scripts, dashboard generation, object export and cloning, and CI automation.

The SDK is the recommended tool for creating Wizard charts or any quality-centric automated visualizations. A wizard chart configuration uses a complex nested structure. The SDK gives an AI agent two advantages that direct API calls do not have: typed builders validate the configuration before it is sent to the API, and the datalens-sdk skill provides the AI agent with instructions for building visualizations compatible with the installed package version. As a result, the AI agent builds predictably valid charts and dashboards, instead of guessing the JSON structure through trial and error.

SDK and AI agentsSDK and AI agents

To install the SDK for an AI agent, use the datalens-sdk skill from the datalens-skills collection.

What the skill does:

• Selects a secure Python environment for the project (venv, uv, or Poetry) and installs or updates the package with user confirmation.
• Loads the SDK usage instructions from the installed package, so they always match the actual API version rather than an outdated snapshot.
• Connects layers with details of the specific DataLens installation, if they are available in the environment.

After installing the skill, you just need to describe the task: the AI agent will set up the environment and write the correct code. Here is a task example:

In workbook <workbook_ID>, create a line chart
based on dataset <dataset_ID>:
sales by month broken down by regions.

What to choose: MCP, SDK, or APIWhat to choose: MCP, SDK, or API

Authorization and environment variablesAuthorization and environment variables

By default, the server automatically obtains an IAM token by running the yc iam create-token command: the token is requested upon the first API call and automatically renewed before its TTL expires. This requires the DATALENS_ORG_ID variable.

The MCP server and SDK support static authentication with a pre-generated IAM token. This enables you to use AI agents when the Yandex Cloud CLI is unavailable, e.g., in an isolated environment. The IAM token lifetime is 12 hours, so you must refresh it manually in this mode.

Here is an example of static authentication without the Yandex Cloud CLI:

"env": {
  "DATALENS_ORG_ID": "<organization_ID>",
  "DATALENS_YC_STATIC_AUTH": "1",
  "DATALENS_API_AUTH_HEADER": "Bearer <IAM_token>"
}

Agent skillsAgent skills

The MCP server and SDK provide your AI agent with API access but not domain knowledge, such as the specific DataLens installation being used, how objects relate to one another, what order to create them in, and which mistakes to avoid. This knowledge is supplied by the datalens-tech/datalens-skills repository, an official collection of skills based on the open Agent Skills standard. Each skill consists of a folder containing a SKILL.md file, optional scripts, and reference assets. Skills are portable across compatible AI agents.

Collection contentsCollection contents

Specifics and limitationsSpecifics and limitations

• Requests to the Public API are subject to limits.
• The IAM token lifetime is 12 hours. When authenticating via the Yandex Cloud CLI, the MCP server and SDK update it automatically. With static authentication, updating the token and restarting the MCP server is the user’s responsibility.
• The AI agent works with DataLens objects but does not interpret the business context of metrics or interact with the web UI. For example, an AI agent cannot take a screenshot or click a button.

Useful linksUseful links

• Using Yandex DataLens with AI agents
• Working with the Public API in Yandex DataLens
• @datalens-tech/mcp MCP server
• npm
• datalens-skills collection
• Python SDK datalens-sdk
• Agent Skills standard
• Model Context Protocol