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 (
withstatement) 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 ...
# File system state persists within session
client.write_file("42", "value.txt")
client.run_code("python", "print(open('value.txt').read())")
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 |
|---|---|
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 URLROUTER_URL: Data Plane URL
Advanced: Session Reuse
For workflows requiring file system state persistence across multiple client instances:
Note: Each
run_codecall spawns a new process. Python variables do NOT persist. Only file system state is preserved.
# Step 1: Create session and save state to file
client1 = CodeInterpreterClient()
session_id = client1.session_id # Save for reuse
client1.write_file("42", "value.txt")
# 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(open('value.txt').read())") # File persists
client2.stop() # Cleanup when done
Development
make build-python-sdk
python3 -m pytest sdk-python/tests/
Metadata
Release files for agentcube-sdk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentcube_sdk-0.1.0.tar.gz | 19.6 kB | With provenance | Details for agentcube_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentcube_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentcube_sdk-0.1.0-py3-none-any.whl |
Total release size: 42.7 kB
Release files / agentcube_sdk-0.1.0.tar.gz
| Download URL | agentcube_sdk-0.1.0.tar.gz |
|---|---|
| Size | 19.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
be98f3a8020afe90fa0d1502f502af7cbf107c364fc88421f3b9f1f76bf07461
|
|
BLAKE2b-256 checksum How to use checksums |
410321d548591d8ae03bfda6d7bdbf6bb88490e2630ea55b905cc83c4cb5d222
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 31, 2026.
Transparency logRelease files / agentcube_sdk-0.1.0-py3-none-any.whl
| Download URL | agentcube_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 23.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cfc3bcc61004a17391a710b509e7017d0a958780312227d1ab72e06f95e2a10b
|
|
BLAKE2b-256 checksum How to use checksums |
cf54bc395c0c12c731d39966e23b5e1a79043577b34b4db32b6c9851aa3f3465
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 31, 2026.
Transparency logSecurity for agentcube-sdk 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agentcube_sdk-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.