A modern Python SDK for the AgentSandbox API - execute Python and Bash code in isolated sandbox environments.
pip install agentsandbox-sdkfrom agentsandbox import AgentSandbox
# Initialize the client
client = AgentSandbox(api_key="your-api-key")
# Or set AGENTSANDBOX_API_KEY environment variable
# Execute Python code
result = client.run("print('Hello, World!')")
print(result.stdout) # Hello, World!
print(result.exit_code) # 0- Sync and Async clients - Use
AgentSandboxorAsyncAgentSandbox - Session management - Persistent
/workspacedirectory across executions - File operations - Upload, download, and manage files
- Environment variables - Inject env vars into sandbox executions
- File injection - Pre-load files into
/workspacebefore execution - Context managers - Automatic resource cleanup
- Pydantic models - Full type hints and validation
from agentsandbox import AgentSandbox, Language
client = AgentSandbox(api_key="your-api-key")
# Python execution
result = client.run("print(1 + 1)")
print(result.stdout) # 2
# Bash execution
result = client.run("echo 'Hello' && ls -la", language=Language.BASH)
print(result.stdout)Inject environment variables into the sandbox:
result = client.run(
"""
import os
print(os.environ['API_KEY'])
print(os.environ['DEBUG'])
""",
env_vars={"API_KEY": "secret123", "DEBUG": "true"}
)Inject files into /workspace before execution:
# Upload a file first
uploaded = client.files.upload(b"name,value\nfoo,1\nbar,2", filename="data.csv")
# Inject file into execution
result = client.run(
"""
import pandas as pd
df = pd.read_csv('/workspace/data.csv')
print(df)
""",
file_ids=[uploaded.file_id]
)
# Clean up
client.files.delete(uploaded.file_id)Important: Each run() call executes in a fresh process. In-memory variables do NOT persist between executions. Sessions provide a persistent /workspace directory for sharing state via files.
with client.sessions.context() as session:
sid = session.session_id
# Write state to a file (persists in session)
client.run("""
import json
with open('/workspace/state.json', 'w') as f:
json.dump({'counter': 42}, f)
""", session_id=sid)
# Read state from file in next execution
result = client.run("""
import json
with open('/workspace/state.json') as f:
data = json.load(f)
print(data['counter'])
""", session_id=sid)
print(result.stdout) # 42
# Session is automatically deleted hereCreate sessions with files and environment variables pre-configured:
# Upload files
config = client.files.upload(b"db_host=localhost", filename="config.txt")
data = client.files.upload(b"id,name\n1,Alice", filename="users.csv")
# Create session with files and env vars pre-loaded
with client.sessions.context(
file_ids=[config.file_id, data.file_id],
env_vars={"APP_ENV": "production"}
) as session:
result = client.run(
"import os; print(os.listdir('/workspace'))",
session_id=session.session_id
)
print(result.stdout) # ['config.txt', 'users.csv']
# Clean up files
client.files.delete(config.file_id)
client.files.delete(data.file_id)# Create a session
session = client.sessions.create()
# Upload a file
uploaded = client.files.upload(b"data content", filename="data.txt")
# Inject file into the existing session
client.sessions.inject_files(session.session_id, [uploaded.file_id])
# Now the file is available in the session's /workspace
result = client.run(
"print(open('/workspace/data.txt').read())",
session_id=session.session_id
)
# Clean up
client.sessions.delete(session.session_id)
client.files.delete(uploaded.file_id)# Upload a file from path
uploaded = client.files.upload("/path/to/data.csv")
print(f"Uploaded: {uploaded.file_id}")
# Upload from bytes
uploaded = client.files.upload(
b"name,value\nfoo,1",
filename="data.csv",
content_type="text/csv"
)
# List files with pagination
files = client.files.list(limit=20, offset=0)
print(f"Total: {files.total}")
# Iterate all files (auto-pagination)
for file in client.files.list_all():
print(f" - {file.filename} ({file.size_bytes} bytes)")
# Download a file
content = client.files.download(file_id)
# Or download to disk
client.files.download_to(file_id, "/path/to/save.csv")
# Delete a file
client.files.delete(file_id)import asyncio
from agentsandbox import AsyncAgentSandbox
async def main():
async with AsyncAgentSandbox(api_key="your-api-key") as client:
# Basic execution with env vars
result = await client.run(
"import os; print(os.environ['MSG'])",
env_vars={"MSG": "Hello async!"}
)
print(result.stdout)
# Async session with pre-loaded files
uploaded = await client.files.upload(b"async data", filename="data.txt")
async with client.sessions.context(file_ids=[uploaded.file_id]) as session:
result = await client.run(
"print(open('/workspace/data.txt').read())",
session_id=session.session_id
)
await client.files.delete(uploaded.file_id)
# Async file iteration
async for file in client.files.list_all():
print(file.filename)
asyncio.run(main())from agentsandbox import (
AgentSandbox,
AgentSandboxError,
AuthenticationError,
NotFoundError,
ValidationError,
)
client = AgentSandbox(api_key="your-api-key")
try:
result = client.run("print('hello')")
except AuthenticationError:
print("Invalid API key")
except NotFoundError:
print("Resource not found")
except ValidationError as e:
print(f"Invalid request: {e.message}")
except AgentSandboxError as e:
print(f"API error [{e.status_code}]: {e.message}")result = client.run("print('hello')")
print(result.session_id) # Session ID (auto-generated if not provided)
print(result.stdout) # Standard output
print(result.stderr) # Standard error
print(result.return_code) # Return code (0 = success)
print(result.exit_code) # Alias for return_code
print(result.success) # True if return_code == 0
print(result.files) # List of files created in /workspacefrom agentsandbox import AgentSandbox
client = AgentSandbox(
api_key="your-api-key", # Or set AGENTSANDBOX_API_KEY env var
base_url="https://custom.api.com", # Or set AGENTSANDBOX_BASE_URL env var
timeout=120.0, # Request timeout in seconds
)AgentSandbox- Synchronous clientAsyncAgentSandbox- Asynchronous client
client.run(code, language, session_id, env_vars, file_ids)- Execute code (convenience method)client.execute.create(...)- Execute code (full method)client.sessions.create(env_vars, file_ids)- Create a sessionclient.sessions.list()- List sessionsclient.sessions.get(id)- Get session detailsclient.sessions.delete(id)- Delete a sessionclient.sessions.inject_files(id, file_ids)- Inject files into sessionclient.sessions.context(env_vars, file_ids)- Context manager for sessionclient.files.upload(file, filename, content_type)- Upload a fileclient.files.list(limit, offset)- List files (paginated)client.files.list_all()- Iterate all filesclient.files.download(id)- Download file contentclient.files.download_to(id, path)- Download to diskclient.files.delete(id)- Delete a fileclient.executions.get(id)- Get execution log
Language- Enum:PYTHON,BASHExecuteResponse- Execution resultSessionInfo- Session detailsFileInfo- File metadataExecutionLog- Detailed execution log
AgentSandboxError- Base exceptionAuthenticationError- Invalid API key (401)ForbiddenError- Access denied (403)NotFoundError- Resource not found (404)ValidationError- Invalid request (422)RateLimitError- Rate limit exceeded (429)ServerError- Server error (500)ServiceUnavailableError- Service unavailable (503)
MIT