Osmosis Python SDK Installation

The open source SDK and the osmosis CLI ship in the same osmosis-ai Python package. The SDK requires Python 3.12 or later and supports Python 3.12, 3.13, and 3.14.

Install v0.3

Install the stable v0.3 line without crossing the next minor-version boundary:

python -m pip install "osmosis-ai>=0.3.10,<0.4"

Verify both the package and bundled CLI:

python -c "import osmosis_ai; print(osmosis_ai.__version__)"
osmosis --version

These instructions use stable 0.3.10 as the baseline; <0.4 keeps installs on the current minor-version line. Upgrade the CLI, rollout callers, and rollout dependencies in rollouts/<name>/pyproject.toml, then regenerate their lockfiles and rebuild affected runtime images. Updating the CLI alone does not update an existing rollout environment. If you are upgrading from 0.3.2 or earlier, update callers and servers together because the old callback protocol does not interoperate with long polling. See the v0.3 migration guide.

Optional Extras

Install only the features your project imports:

Extra	Adds	Install command
`server`	FastAPI and Uvicorn for `create_rollout_server()`	`python -m pip install "osmosis-ai[server]>=0.3.10,<0.4"`
`strands`	Strands Agents adapter and its LiteLLM runtime	`python -m pip install "osmosis-ai[strands]>=0.3.10,<0.4"`
`openai-agents`	OpenAI Agents SDK adapter and its LiteLLM runtime	`python -m pip install "osmosis-ai[openai-agents]>=0.3.10,<0.4"`
`harbor`	Harbor execution backend, including Harbor’s Daytona and OpenSandbox dependencies	`python -m pip install "osmosis-ai[harbor]>=0.3.10,<0.4"`
`rubric`	LLM-as-judge rubric evaluation	`python -m pip install "osmosis-ai[rubric]>=0.3.10,<0.4"`
`parquet`	Parquet dataset validation	`python -m pip install "osmosis-ai[parquet]>=0.3.10,<0.4"`
`eval`	Local evaluation runner; includes the LiteLLM bridge, uv, Parquet readers, and `server`	`python -m pip install "osmosis-ai[eval]>=0.3.10,<0.4"`
`full`	All optional features above	`python -m pip install "osmosis-ai[full]>=0.3.10,<0.4"`

Extras can be combined. A Strands rollout served over HTTP, for example, uses:

python -m pip install "osmosis-ai[server,strands]>=0.3.10,<0.4"

The strands, openai-agents, harbor, rubric, and eval extras (including full) require fsspec>=2026.6.0. Version 0.3.6 also raised the applicable LiteLLM, urllib3, and PyJWT minimums for security fixes. Version 0.3.8 updates the certifi and uv CA trust stores and raises the applicable aiohttp, multidict, and MCP requirements. Resolve conflicting application pins when refreshing lockfiles; see the changelog for the exact ranges. Version 0.3.9 raises the applicable LiteLLM, filelock, Strands Agents, and OpenTelemetry API security requirements. It also changes the source digest used by named local eval runs: finish interrupted runs with their original SDK before upgrading, or use a new name or --fresh afterward. See the 0.3.9 migration steps. Version 0.3.10 uploads local eval results as a single streamed archive and requires a platform with archive import support. See the 0.3.10 migration steps.

Minimal SDK Example

This entrypoint explicitly wires a workflow and grader into LocalBackend, then exposes that backend as a rollout server:

import os

import uvicorn
from osmosis_ai.rollout import (
    AgentWorkflow,
    AgentWorkflowContext,
    AgentWorkflowOutput,
    Grader,
    GraderContext,
    LocalBackend,
)
from osmosis_ai.rollout.server import create_rollout_server


class EchoWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> AgentWorkflowOutput:
        return AgentWorkflowOutput(
            messages=[*ctx.prompt, {"role": "assistant", "content": "ready"}]
        )


class ReadyGrader(Grader):
    async def grade(self, ctx: GraderContext) -> None:
        if ctx.sample is None:
            raise ValueError("workflow produced no sample")
        ctx.set_reward(1.0)


def main() -> None:
    backend = LocalBackend(workflow=EchoWorkflow, grader=ReadyGrader)
    app = create_rollout_server(backend=backend)
    port = os.environ.get("_OSMOSIS_ROLLOUT_PORT")
    uvicorn.run(
        app,
        host="0.0.0.0" if port else "127.0.0.1",
        port=int(port or "8000"),
        timeout_keep_alive=2160,
    )


if __name__ == "__main__":
    main()

Install the server extra, save the example as main.py, and run the entrypoint:

python main.py

Set timeout_keep_alive=2160 in existing server entrypoints as well. New SDK 0.3.7 scaffolds use this value to keep idle connections alive beyond the managed load balancer’s idle timeout. The Platform sets _OSMOSIS_ROLLOUT_PORT and the server then binds every interface in the managed container; local runs default to 127.0.0.1:8000.

This example leaves rollout server authentication disabled. Keep it on loopback locally; for self-hosted access, configure rollout server authentication and HTTPS.

This example demonstrates wiring, not a trainable policy call. For training, use the Strands integration or OpenAI Agents integration so model requests route through the active rollout context.

Platform Authentication and Upgrades

SDK-only local code does not need a Platform login. Commands that submit evaluations or training runs do; follow CLI Installation & Authentication to run osmosis auth login or configure OSMOSIS_TOKEN. If you are upgrading an existing v0.2 harness, read the SDK v0.2 → v0.3 migration guide before changing the dependency, especially if it constructs HarborBackend.

Get started

Core API

Integrations

Execution

Agent tools

Osmosis Python SDK Installation

Install v0.3

Optional Extras

Minimal SDK Example

Platform Authentication and Upgrades

Next Steps

AgentWorkflow

Execution Backends

​Install v0.3

​Optional Extras

​Minimal SDK Example

​Platform Authentication and Upgrades

​Next Steps

AgentWorkflow

Execution Backends

Install v0.3

Optional Extras

Minimal SDK Example

Platform Authentication and Upgrades

Next Steps