Skip to main content
Language models approximate exact arithmetic and data manipulation rather than computing them. The sandbox tool gives the agent an isolated Linux container to run real code and use the output in its answer — for results that must be exact, like a computed number, a transformed dataset, or a generated report. From inside the container the agent can also call Perplexity’s Web Search, Fetch URL Content, and People Search without adding them to the request, then compute on what they return — each billed at its standard rate. The Sandbox tool reference has the full settings, response shape, and pricing.

​
Enable the sandbox

Add {"type": "sandbox"} to the tools array. The model decides when to run code based on your prompt. 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.5",
    input="Compute the compound annual growth rate from 4.2M in 2019 to 11.8M in 2025.",
    tools=[{"type": "sandbox"}],
    instructions="Use the sandbox to compute the exact figure before answering.",
)

print(response.output_text)

​
When to reach for it

  • Numeric calculations and statistical analysis where an estimate won’t do
  • Data cleaning, parsing, and transformation
  • Executing code to check logic or reproduce an error
  • Generating files and artifacts — CSV, JSON, HTML, reports, or any other file the code writes
  • Multi-step workflows that need intermediate files or computed state
Combine sandbox with web_search and the agent can gather evidence, then compute on it inside the container. See the Sandbox reference for how the sandbox interacts with other tools.

​
Read the computed result

When the agent runs code, the response output array includes one or more sandbox_results items alongside the message. Each carries the executed code, the language, and a results array with stdout, stderr, exit_code, and status. That’s how you verify the agent computed the answer rather than guessing it. See the response shape reference for every field. Read that item back off the response (response here is from the Enable the sandbox example above):
Python
for item in response.output:
    if item.type == "sandbox_results":
        print(item.code)
        print(item.results[0].stdout)
For that request, the agent wrote and ran this Python in the sandbox, then used the printed value in its answer: 
from decimal import Decimal, getcontext

getcontext().prec = 50
start = Decimal('4.2')
end = Decimal('11.8')
years = Decimal(2025 - 2019)
log_growth = (end / start).ln() / years
cagr = log_growth.exp() - Decimal(1)
print(cagr)
print(cagr * 100)
Output
0.1878787669330553776746033271110368937629924939521
18.787876693305537767460332711103689376299249395210

​
Return files

When code in the sandbox writes a file and shares it, the response output includes a share_file item. The bytes aren’t inline — list and download them with the response files endpoints, keyed by the response id: 
files = client.responses.files.list(response.id)
for f in files.data:
    print(f.id, f.filename, f.bytes)

content = client.responses.files.content(
    file_id=files.data[0].id,
    response_id=response.id,
)
content.write_to_file(files.data[0].filename)
Long-running sandbox work pairs well with background runs: submit with background: true and poll by ID. See Shape the output → Streaming and the Sandbox reference.

​
Next steps

Sandbox reference

Full sandbox settings, response shape, file retrieval, and pricing.

Shape the output

Stream output as it arrives and enforce structured JSON.