> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valkyrie.vals.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK quickstart

> Configure the async Valkyrie client and list runs from Python.

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

```bash theme={null}
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.

```python theme={null}
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](/reference/sdk/client) 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](/get-started/hosting#aws-execution-mode).

<Warning>
  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.
</Warning>

## Examples

The repository includes complete scripts for common workflows:

* [`run_lifecycle.py`](https://github.com/vals-ai/Valkyrie/blob/prod/docs/sdk/examples/run_lifecycle.py) starts, streams, and retrieves a run.
* [`manage_run.py`](https://github.com/vals-ai/Valkyrie/blob/prod/docs/sdk/examples/manage_run.py) stops, resumes, or retries a run.

From a Valkyrie checkout:

```bash theme={null}
python docs/sdk/examples/run_lifecycle.py --help
python docs/sdk/examples/manage_run.py --help
```

## Next steps

* [Manage runs with Python](/sdk/runs) for the run lifecycle
* [Inspect resources with Python](/sdk/resources) for tasks, agents, and services
* [Python SDK reference](/reference/sdk) for every method, model, and field