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

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

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

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

Песочница доступна при работе через внешний чат, виджет, нативный API и OpenAI-совместимый API.

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

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

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

• взять готовый скрипт из подключенного навыка;

• использовать код, который пользователь отправил в сообщении;

• самостоятельно написать код по описанию задачи.

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

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

    

      

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

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

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

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

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

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

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

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

Ограничения

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

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

В песочнице доступны стандартные библиотеки и модули 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 со следующим содержимым:

    

      

    
    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.

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

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

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

    

      

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

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

    

      

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

Инструкция:

    

      

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

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

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

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

Описание:

    

      

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

Аргументы:

    

      

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

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

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

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

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

    

      

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

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

    

      

    
    {"text": "hello world"}
  

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

    

      

    
    b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
  

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