agentcube-sdk 0.0.10

Python SDK for AgentCube Code Interpreter

AgentCube Python SDK

The official Python SDK for AgentCube, enabling programmatic interaction with secure, isolated Code Interpreter environments.

This SDK creates a seamless bridge between your application and the AgentCube runtime, handling the complexity of:

• Session Management: Automatically creating and destroying isolated environments.
• Execution: Running shell commands and code (Python, Bash) remotely.
• File Management: Uploading and downloading files to/from the sandbox.

Features

• Simple API: Pythonic context managers (with statement) for automatic resource cleanup.
• Flexible: Supports both short-lived (ephemeral) and long-running sessions.
• Kubernetes Native: Automatically authenticates using Service Account tokens when running in-cluster.

Installation

git clone https://github.com/volcano-sh/agentcube.git
cd agentcube/sdk-python
pip install .

Quick Start

from agentcube import CodeInterpreterClient

with CodeInterpreterClient() as client:
    output = client.run_code("python", "print('Hello, AgentCube!')")
    print(output)
# Session automatically deleted on exit

Manual Lifecycle Management

For long-running applications, you can manually control the lifecycle:

# Create a session with a 1-hour timeout
client = CodeInterpreterClient(ttl=3600)

try:
    client.run_code("python", "print('Session started')")
    # ... perform operations ...
    # You can continue using the same client for multiple operations
    client.run_code("python", "x = 42")
    client.run_code("python", "print(f'x = {x}')")  # x persists within session
finally:
    client.stop()  # CRITICAL: Ensure resources are released

File Operations

with CodeInterpreterClient() as client:
    client.upload_file("./data.csv", "/workspace/data.csv")
    client.run_code("python", """
import pandas as pd
df = pd.read_csv('/workspace/data.csv')
df.describe().to_csv('/workspace/summary.csv')
""")
    client.download_file("/workspace/summary.csv", "./summary.csv")

API Reference

Method	Description
start()	Explicitly start the session (optional, auto-starts on first API call)
execute_command(cmd)	Execute shell command
run_code(language, code)	Execute code (python/bash)
upload_file(local, remote)	Upload file to sandbox
download_file(remote, local)	Download file from sandbox
write_file(content, path)	Write string to file
list_files(path)	List directory contents
stop()	Delete session and release resources

Configuration

CodeInterpreterClient(
    name="custom-template",        # CodeInterpreter CRD template name
    namespace="agentcube",         # Kubernetes namespace
    ttl=7200,                      # Session TTL (seconds)
    session_id="existing-id",      # Optional: reuse existing session
    verbose=True                   # Enable debug logging
)

Environment Variables:

• WORKLOAD_MANAGER_URL: Control Plane URL
• ROUTER_URL: Data Plane URL
• API_TOKEN: Authentication token

Advanced: Session Reuse

For workflows requiring state persistence across multiple client instances:

# Step 1: Create session
client1 = CodeInterpreterClient()
client1.run_code("python", "x = 42")
session_id = client1.session_id  # Save for reuse
# Don't call stop() - let session persist

# Step 2: Reuse session with new client
client2 = CodeInterpreterClient(session_id=session_id)
client2.run_code("python", "print(x)")  # x still exists
client2.stop()  # Cleanup when done

Development

make build-python-sdk
python3 -m pytest sdk-python/tests/