GMI AgentBox SDK for Python

Thin Python client for AgentBox.

Public names are Agent (registered template) and Sandbox (launched container). Registering an Agent does not start anything.

• Usage — install, auth, register, launch, wait, cleanup
• Reference — client, methods, models, errors

Install

python -m pip install -e ".[dev]"

Requires Python 3.9+.

Auth

export GMI_AGENTBOX_API_KEY="your-api-key"

GMI_AGENTBOX_API_KEY is required (or pass api_key=). GMI_AGENTBOX_BASE_URL is optional and defaults to production https://console.gmicloud.ai.

Quickstart

from agentbox_sdk import AgentBoxClient

client = AgentBoxClient()

# Discover available IDCs and SKUs, then pass explicit values.
# The SDK does not pick IDC or instance_type for you.
idc_id = "us-central-iowa1"
instance_type = "gmi.container.intel.x4660.large"

agent = client.agents.create(
    title="agentbox-demo",
    image_url="docker.io/library/alpine:3.20",
    idc=idc_id,
)
# generated_api_key is plaintext only on this response

sandbox = agent.launch(instance_type=instance_type)
sandbox.wait_until_running()  # default timeout 300s
print(sandbox.endpoint_url)

print(sandbox.logs())
sandbox.delete()
agent.delete()  # does not stop remaining sandboxes

GET /products?idc_name= takes an idcId from GET /idcs, not a region label. Launch cannot change the Agent's IDC.

sandboxes.list() omits stopped and deleted unless you pass status.

Against production (bills the account):

set -a && source ./ie-pro-env && set +a
PYTHONPATH=src python examples/live_smoke.py

For the runtime E2E (build, command execution, file round trip, and asynchronous cancellation), select a matching runtime/IDC/SKU and run:

export GMI_AGENTBOX_RUNTIME="sandbox"  # or "container"
PYTHONPATH=src python examples/sandbox_e2e.py

GMI_AGENTBOX_BASE_URL is optional. The E2E defaults GMI_AGENTBOX_RUNTIME to sandbox; GMI_AGENTBOX_IDC and GMI_AGENTBOX_INSTANCE_TYPE must always be set to values for the selected runtime.

Set GMI_AGENTBOX_TEST_SHELL=1 to include a WebSocket shell-connect check. The E2E asserts its data-plane operations for either runtime; it does not skip them according to Sandbox capabilities. Set GMI_AGENTBOX_VALIDATE_CATALOGUE=1 to enable the optional runtime eligibility/IDC/SKU preflight.

Sandbox runtimes also support command execution, file upload/download, and an interactive WebSocket shell. See the reference for sandbox.execute(), sandbox.upload_file(), sandbox.download_file(), and sandbox.shell().