---
title: "Выполнение кода в песочнице"
---

# Выполнение кода в песочнице

> Полный индекс документации для ИИ-агентов: [llms.txt](https://timeweb.cloud/llms.txt).

Песочница — изолированная среда, в которой ИИ-агент может выполнять код. Агент запускает в ней скрипт, получает результат и использует его в ответе пользователю или на следующих этапах работы. Такая среда создается на время выполнения задачи и затем удаляется. Пользователь при этом взаимодействует не с песочницей напрямую, а с агентом, который решает, когда и какой код выполнить.

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

Так LLM отвечает за понимание задачи и выбор способа ее решения, а код — за операции, для которых важны точность и воспроизводимость.

Песочница доступна при работе через [внешний чат](https://timeweb.cloud/docs/ai-agents/manage-agents/external-chat), [виджет](https://timeweb.cloud/docs/ai-agents/manage-agents/embed-chatbots), [нативный API](https://timeweb.cloud/docs/ai-agents/api-usage/native-api) и [OpenAI-совместимый API](https://timeweb.cloud/docs/ai-agents/api-usage/openai-compatible-api).

Запуск кода в песочнице бесплатный. Песочница включена по умолчанию, отдельно включать ее не нужно.

## Способы использования

Для выполнения задачи в песочнице агент может:

-   взять готовый скрипт из подключенного [навыка](https://timeweb.cloud/docs/ai-agents/manage-agents/skills);
    
-   использовать код, который пользователь отправил в сообщении;
    
-   самостоятельно написать код по описанию задачи.
    

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

Если агент пытается выполнять расчеты или обрабатывать данные без запуска кода, добавьте явное указание в [системный промпт](https://timeweb.cloud/docs/ai-agents/manage-agents/instructions). Такая подсказка особенно полезна для менее мощных моделей:

```shell
Любые расчеты и обработку данных выполняй через инструмент запуска кода, не считай в уме.
```

## Как выполняется скрипт

Для каждого запуска создается отдельная среда со сроком жизни 30 секунд. Файлы в ней не сохраняются между запусками.

Агент передает аргументы скрипту в формате JSON через стандартный поток ввода — `stdin`. Например, в Python аргументы передаются так: `json.load(sys.stdin)`.

Результат выполнения скрипта должен выводится в стандартный поток вывода — `stdout`. В Python для этого можно использовать `print()`, а в Node.js — `console.log()`.  

В качестве результата выполнения скрипта агент получает до 8 000 символов из `stdout` и использует их при подготовке ответа. 

При ошибке агенту передается до 2 000 символов из стандартного потока ошибок — `stderr`.

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

## Ограничения

При подготовке скриптов учитывайте ограничения среды выполнения: доступные ресурсы, допустимые расширения файлов и объем вывода, который передается агенту.

| **Параметр** | **Ограничение** |
| --- | --- |
| Среды выполнения | Python 3.13 и Node.js 24 |
| Время выполнения скрипта | До 30 секунд |
| Оперативная память | 256 МБ |
| Процессор | 1 ядро |
| Форматы файлов кода | `.py`, `.js`, `.mjs`, `.cjs` |
| Количество файлов за один запуск | До 20 |
| Общий размер файлов | До 10 МБ |
| Вывод stdout, передаваемый агенту | До 8 000 символов |
| Вывод stderr, передаваемый агенту при ошибке | До 2 000 символов |

## Доступные библиотеки

В песочнице доступны стандартные библиотеки и модули Python и Node.js, а также дополнительные пакеты:

-   Python: `openpyxl`, `XlsxWriter`, `xlrd`, `python-docx`, `python-pptx`, `pypdf`, `pdfplumber`, `reportlab`, `Pillow`, `numpy`, `sympy`, `python-dateutil`, `pytz`, `orjson`, `tqdm`.
    
-   Node.js: `exceljs`, `xlsx`, `csv-parse`, `csv-stringify`, `docx`, `pdf-lib`, `jszip`, `mathjs`, `dayjs`, `lodash`.
    

Установка дополнительных библиотек не предусмотрена.

## Пример

В качестве примера рассмотрим, как рассчитать SHA-256 текста с помощью скрипта, добавленного в навык. SHA-256 — это хеш, который вычисляется по содержимому текста. На результат влияют все символы, включая пробелы, переносы строк и регистр букв.

Подготовим скрипт на Python, добавим его в навык и подключим навык к агенту. После этого проверим расчет на примере строки hello world.

### Подготовка скрипта

Создайте на компьютере файл `sha256_text.py` со следующим содержимым:

```py
import hashlib
import json
import sys

args = json.load(sys.stdin)
text = args["text"]
digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
print(digest)
```

Скрипт читает из `stdin` JSON с полем `text`, вычисляет SHA-256 текста в кодировке UTF-8 и выводит хеш в `stdout`. Для работы используются только стандартные библиотеки Python.

### Создание навыка

Перейдите в раздел «ИИ-сервисы» → «Навыки» и нажмите «Добавить». Заполните поля навыка.

**Название навыка**:

```bash
Расчет SHA-256 текста
```

**Когда применять**:

```bash
Используй этот навык, когда пользователь просит вычислить SHA-256 текста.
```

**Инструкция**:

```bash
Для расчета SHA-256 используй скрипт sha256_text.py.

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

Если непонятно, какой фрагмент нужно обработать, уточни его у пользователя. Верни хеш, полученный от скрипта, без изменений.
```

Нажмите на «Загрузить скрипт». В открывшемся окне загрузите файл `sha256_text.py` и заполните поля.

**Описание**:

```bash
Вычисляет SHA-256 переданного текста в кодировке UTF-8 и возвращает хеш в шестнадцатеричном виде.
```

**Аргументы**:

```bash
Скрипт принимает JSON с обязательным полем text — строкой, для которой нужно вычислить SHA-256. Передавай текст без изменений, сохраняя регистр букв, пробелы и переносы строк.

Пример: {"text": "hello"}.
```

Нажмите «Добавить» в окне загрузки скрипта. Затем в поле «Агенты» выберите агента, который будет использовать навык, и нажмите «Добавить» в форме создания навыка.

### Проверка работы

Откройте плейграунд агента, к которому подключен навык, и отправьте запрос:

```bash
Вычисли SHA-256 строки «hello world». Кавычки не включай, пробелы и перенос строки не добавляй.
```

По инструкции навыка агент должен запустить `sha256_text.py` и передать ему аргументы:

```bash
{"text": "hello world"}
```

Скрипт вычислит хеш и выведет результат в `stdout`:

```bash
b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
```

Агент получит это значение и вернет его в ответе. Сравните хеш в ответе с приведенным выше: для строки `hello world` без кавычек, пробелов и переноса строки значения должны совпасть.