trelent-agents 0.2.1

Python SDK for the Agent Orchestration API.

trelent-agents

Python SDK for the Trelent Agent Orchestration API.

Installation

pip install trelent-agents

Quick Start

Without authentication

from trelent_agents import Client

client = Client(api_url="http://localhost:8000")

images = client.images.list()
print(images)

run = client.runs.create(
    sandbox="example-agent:latest",
    prompt="Create hello.txt with a greeting",
)
print(run.run_id, run.status)

With authentication

When the API has authentication enabled, provide your OAuth2 client credentials:

from trelent_agents import Client

client = Client(
    api_url="https://agents.trelent.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
)

images = client.images.list()
run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Do something useful",
)

The SDK handles token acquisition automatically — it exchanges your client credentials for a JWT via the API's /token endpoint before making authenticated requests.

The client also supports context manager usage:

with Client(api_url="https://agents.trelent.com", client_id="...", client_secret="...") as client:
    runs = client.runs.list()

Client Options

client = Client(
    api_url="https://agents.trelent.com",  # API base URL (default: https://agents.trelent.com)
    client_id="...",                        # OAuth2 client ID (optional)
    client_secret="...",                    # OAuth2 client secret (optional)
    scope="...",                            # Override default OAuth2 scope (optional)
)

Both client_id and client_secret must be provided together, or both omitted.

Resources

client.images

images = client.images.list()
# => list[RegistryImage] — [RegistryImage(name="my-image", tags=["latest", "v1"])]

When auth is enabled, images are automatically filtered to your namespace. Image names are returned without the namespace prefix.

client.sandboxes

sandboxes = client.sandboxes.list()
# => list[str] — registered sandbox image names

client.sandboxes.register("my-image:latest")

client.runs

from trelent_agents import LocalImporter, S3Exporter

# Create a run
run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Build a web server",
    model="gpt-5.4",              # optional, default: "gpt-5.4"
    timeout_seconds=3600,          # optional, default: 3600
    imports=[LocalImporter(path="./data")],  # optional
    exports=[S3Exporter()],                  # optional
)

# List runs (optionally filter by sandbox)
runs = client.runs.list()
filtered = client.runs.list(sandbox="my-image:latest")

# Get a specific run
run = client.runs.get("run-id")

# Check status
status = client.runs.get_status("run-id")

# Get checkpoints
chain = client.runs.get_checkpoint_chain("run-id")
checkpoint = client.runs.get_checkpoint("run-id", "checkpoint-id")

Run operations

# Fork (resume from checkpoint)
forked = run.fork(
    "Continue from where you left off",
    model="gpt-5.4",
)

# Refresh run state
run.refresh()
print(run.status)  # updated status

client.health()

health = client.health()
# => HealthResponse(status="ok")

Connectors

Importing local files

from trelent_agents import LocalImporter

run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Process the data",
    imports=[LocalImporter(path="./my-data-dir")],
)

The LocalImporter tarballs and base64-encodes the local path, sending it inline with the request.

Exporting to S3

from trelent_agents import S3Exporter

run = client.runs.create(
    sandbox="my-image:latest",
    prompt="Generate a report",
    exports=[S3Exporter(bucket="my-bucket", path="reports/")],
)

Docker Registry Setup

When auth is enabled, push images to your user namespace on the registry:

# Login with your OAuth2 credentials
docker login registry.example.com -u <client_id> -p <client_secret>

# Push to your namespace
docker tag my-image:latest registry.example.com/<client_id>/my-image:latest
docker push registry.example.com/<client_id>/my-image:latest

When creating runs via the SDK, just use the image name without the namespace prefix:

run = client.runs.create(
    sandbox="my-image:latest",  # not "<client_id>/my-image:latest"
    prompt="...",
)

The API resolves the full registry path automatically based on your authenticated identity.

Types

The SDK exports the following types:

from trelent_agents import (
    Client,
    Run,
    RunStatus,
    RunResult,
    RunStatusResponse,
    RegistryImage,
    CheckpointResponse,
    ChatHistoryEntry,
    FileOutput,
    OutputFile,
    HealthResponse,
    WorkflowIds,
    LocalImporter,
    S3Exporter,
    APIError,
    NotFoundError,
    ValidationError,
)