Running Code in a Sandbox

A sandbox is a temporary, isolated environment where an AI agent can execute code. The agent runs a script, gets back the result, and uses it to answer the user or continue with the task. The environment exists only for the duration of that task and is destroyed afterward; users never interact with it directly, only with the agent that decides when and what to run.

Agents are good at understanding requests and figuring out an approach, but not at producing exact, repeatable results—a calculation done "in the model's head" can look right without actually being correct. The sandbox covers that gap: instead of estimating an answer, the agent writes a short script, runs it on the real input, and uses the returned value.

The sandbox is available when working through the external chat, widget, native API, and OpenAI-compatible API.

Running code in the sandbox is free. It's enabled by default—no separate setup is needed.

Ways to Run Code

Copy link

To complete a task in the sandbox, the agent can:

• Use a ready-made script from an attached skill
• Run code the user sent in a message
• Write its own code based on the task description

Scripts attached to skills work well for repetitive tasks, like validating data against fixed rules or converting text into a specific format.

If the agent tries to perform calculations or process data without running code, add an explicit instruction to the system prompt. This is especially useful for less capable models:

Perform all calculations and data processing using the code execution tool. Always compute the result with code instead of estimating it.

How a Script Runs

Copy link

Each run gets its own environment with a 30-second lifespan. Files aren't preserved between runs.

The agent passes arguments to the script as JSON over standard input (stdin). In Python, for example, arguments are read with json.load(sys.stdin).

The script's output must be written to standard output (stdout). In Python, use print(); in Node.js, use console.log().

The agent receives up to 8,000 characters of stdout output and uses it to generate a response. On failure, it receives up to 2,000 characters of stderr.

Chat attachments aren't passed directly to the script. If a script needs external files, it has to fetch them itself—for example, by downloading them from a URL.

Limits

Copy link

When writing scripts, keep these runtime limits in mind: available resources, supported file types, and how much output the agent receives.

Available Libraries

Copy link

The sandbox includes the standard Python and Node.js libraries and modules, plus the following packages:

• 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

Installing additional libraries isn't supported.

Usage Example

Copy link

In this example, you'll calculate the SHA-256 hash of a text string using a script attached to a skill. SHA-256 is a hash computed from a text's content—every character affects the result, including spaces, line breaks, and letter case.

You'll write a Python script, attach it to a skill, and connect the skill to an agent, then test the calculation on the string hello world.

Prepare the Script

Copy link

Create a file named sha256_text.py on your computer with the following content:

import hashlib
import json
import sys

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

The script reads a JSON object containing a text field from stdin, computes the UTF-8 SHA-256 hash of that text, and prints the hash to stdout. It relies only on Python's standard library.

Create the Skill

Copy link

1. Go to AI Services → Skills and click Add.
2. Fill in the skill's fields: 

   • Skill name:

     Calculate SHA-256 of text

   • When to use:

     Use this skill when the user asks to calculate the SHA-256 hash of a piece of text.

   • Instructions:

     To calculate SHA-256, use the sha256_text.py script.
     Pass the user's text in the text field. Preserve letter case, spaces, and line breaks. Don't add characters or otherwise modify the text.
     If it's unclear which piece of text to process, ask the user to clarify. Return the hash from the script unchanged.

3. Click Upload script.
4. Upload sha256_text.py and fill in the fields:

   • Description:

     Calculates the UTF-8 SHA-256 hash of the given text and returns it in hexadecimal form.

   • Arguments: 

     The script accepts a JSON object with a required text field—the string to hash. Pass the text unchanged, preserving letter case, spaces, and line breaks.

     Example: {"text": "hello"}

5. Click Add.
6. In the Add skill window, select the agent that will use the skill in the Agents (optional) field.
7. Click Add.

Test It

Copy link

Open the agent's playground and send a request:

Calculate the SHA-256 hash of the string "hello world". Don't include the quotation marks, and don't add extra spaces or a line break.

Following the skill's instructions, the agent should run sha256_text.py with the arguments:

{"text": "hello world"}

The script computes the hash and prints it to stdout:

b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9

The agent returns this value in its response. Compare it to the hash above—for the exact string hello world, with no extra characters, the values should match.