Python SDK quickstart

The valkyrie-sdk package provides an async Python client for run management and hosted resource inspection. It requires Python 3.12 or newer and does not install the CLI or tracker service.

Install

pip install valkyrie-sdk

Configure

The SDK reads the same configuration as the CLI. Run valkyrie config init first, or pass a tracker URL directly.

import asyncio

from valkyrie.sdk import ValkyrieClient

async def main() -> None:
    async with ValkyrieClient.from_config() as client:
        runs = await client.runs.list()
        print(runs)

asyncio.run(main())

Pass base_url to ValkyrieClient for a self-hosted tracker. Otherwise, the SDK uses TRACKER_SERVICE_URL or the hosted tracker URL. The ValkyrieClient reference lists every constructor parameter and default. When both AWS access-key fields are configured, the SDK sends those credentials and AWS resources to the tracker for the run. When both are absent, start requests omit AWS credentials and request managed execution. See AWS execution mode.

In access-key execution, the SDK sends AWS credentials through X-Harness-* headers. Connect only to a trusted tracker and use HTTPS outside local development.

Examples

The repository includes complete scripts for common workflows:

run_lifecycle.py starts, streams, and retrieves a run.
manage_run.py stops, resumes, or retries a run.

From a Valkyrie checkout:

python docs/sdk/examples/run_lifecycle.py --help
python docs/sdk/examples/manage_run.py --help

Next steps

Manage runs with Python for the run lifecycle
Inspect resources with Python for tasks, agents, and services
Python SDK reference for every method, model, and field

Get started

Agents

Runs

Benchmarks

Integrations

Python SDK

CLI reference

Python SDK reference

Self-hosting

Python SDK quickstart

Install

Configure

Examples

Next steps

​Install

​Configure

​Examples

​Next steps

Install

Configure

Examples

Next steps