kanyun-sandbox 0.1.1

Python SDK for Kanyun Sandbox Platform - Control Plane client with integrated Agent access

Kanyun Sandbox Python SDK

Kanyun Sandbox 平台的 Python SDK，提供 Control Plane 客户端和集成的 Agent 访问能力。

安装

pip install kanyun-sandbox

快速开始

from kanyun_sandbox import Client

client = Client(
    control_plane_url="https://sandbox.example.com",
    api_key="your-api-key",
)

# 使用 run_session 自动管理 Sandbox 生命周期
with client.run_session(template_name="python", ttl_seconds=300) as session:
    # 执行 Shell 命令
    result = session.agent.shell.exec_command(command="echo hello")
    print(result.data.output)

    # 写入文件
    session.agent.file.write_file(file="/tmp/test.txt", content="Hello!")

    # 读取文件
    read_result = session.agent.file.read_file(file="/tmp/test.txt")
    print(read_result.data.content)
# Sandbox 在 with 块结束时自动销毁

客户端配置

client = Client(
    control_plane_url="https://sandbox.example.com",  # 必填
    api_key="your-api-key",          # API 认证密钥
    user_id="user-123",              # 用户 ID（X-User-ID header）
    agent_port=8080,                 # Agent 端口（默认 8080）
    use_agent_endpoint=False,        # 优先使用 agent_endpoint 而非 pod_ip
    timeout=60.0,                    # HTTP 请求超时（秒）
)

API

Sandbox 管理

from kanyun_sandbox import CreateSandboxRequest

# 创建 Sandbox
handle = client.create_sandbox(CreateSandboxRequest(
    template_name="python",
    ttl_seconds=600,
    labels={"env": "test"},
))

# 通过 handle 执行命令
result = handle.agent.shell.exec_command(command="ls -la")

# 延长 TTL
handle.extend(ttl_seconds=300)

# 销毁
handle.destroy()

# 获取 Sandbox 信息
info = client.get_sandbox("sandbox-id")

# 列出 Sandbox
response = client.list_sandboxes(label_selector="env=test")
for sb in response.sandboxes:
    print(f"{sb.id}: {sb.phase}")

# 连接已有 Sandbox
handle = client.connect_sandbox("sandbox-id")

# 删除 Sandbox
client.delete_sandbox("sandbox-id")

Template 管理

# 列出所有模板
templates = client.list_templates()
for t in templates.templates:
    print(f"{t.name}: {t.description}")

# 获取指定模板
tmpl = client.get_template("python")

Session（推荐）

# 方式 1: context manager（推荐）
with client.run_session(template_name="python", ttl_seconds=300) as session:
    session.agent.shell.exec_command(command="echo hello")

# 方式 2: 手动管理
session = client.new_session(CreateSandboxRequest(template_name="python"))
try:
    session.agent.shell.exec_command(command="echo hello")
finally:
    session.close()

Agent 能力

通过 session.agent 或 handle.agent 访问 agent-sandbox 提供的全部能力：

• Shell: agent.shell.exec_command(...) - 执行 Shell 命令
• File: agent.file.read_file(...), agent.file.write_file(...), agent.file.list_path(...) - 文件操作
• Jupyter: agent.jupyter - Jupyter notebook 执行
• Node.js: agent.nodejs - Node.js 代码执行
• Browser: agent.browser - 浏览器自动化
• Code: agent.code - 统一代码执行

与 Go SDK 对照

Go SDK	Python SDK
kanyun.NewClient(opts...)	Client(control_plane_url=..., api_key=...)
client.CreateSandbox(ctx, req)	client.create_sandbox(req)
client.RunSession(ctx, req, fn)	with client.run_session(...) as session:
handle.Agent().Shell.ExecCommand(...)	handle.agent.shell.exec_command(...)
handle.Extend(ctx, ttl)	handle.extend(ttl)
handle.Destroy(ctx)	handle.destroy()
session.Close(ctx)	session.close()

依赖

• Python 3.9+
• httpx - HTTP 客户端
• agent-sandbox - Agent 端 SDK