Osmosis Python SDK Overview

The open source osmosis-ai SDK defines and runs agent behavior in Python; the bundled osmosis CLI submits and inspects runs; the Osmosis Platform manages datasets, evaluation, and training. They ship together, but each has a distinct role. A rollout definition explicitly wires an AgentWorkflow, an optional Grader, their configs, and an execution backend. A rollout execution runs that definition once for one dataset prompt. It produces at most one rollout sample: the agent’s framework-native message history plus an optional reward and metrics.

Training Loop

Training on Osmosis repeatedly runs the same four-part loop:

Select a dataset row

The training cluster selects one row from your dataset and sends its prompt fields to your AgentWorkflow. Common datasets contain system_prompt, user_prompt, and ground_truth.

Run the AgentWorkflow

Your workflow receives an AgentWorkflowContext, calls the current policy through an Osmosis-supported agent integration, uses any tools you provide, and records one rollout sample.

Grade the sample

Your Grader receives the sample plus the row’s reference answer (ground_truth, exposed as ctx.label) and assigns one numerical reward.

Update the model

The reward signal drives the training update, moving the policy toward behavior that receives higher rewards on your task.

This loop is why rollout code must route model calls through Osmosis integrations. The training cluster needs to serve the current policy through the rollout-scoped endpoint, collect traces, and connect the reward to the sample that produced it.

Files in a Rollout

Each rollout lives under rollouts/ and is referenced by evaluation and training configs:

repository/
├── rollouts/
│   └── my-rollout/
│       ├── main.py
│       └── pyproject.toml
├── configs/
│   ├── eval/
│   │   └── my-rollout.toml
│   └── training/
│       └── my-rollout.toml
└── data/
    └── test.jsonl

File	Purpose
`rollouts/my-rollout/main.py`	Defines workflow and grader classes, explicitly wires the selected ones into a backend, and exposes the server app
`rollouts/my-rollout/pyproject.toml`	Declares rollout-local Python dependencies
`configs/eval/my-rollout.toml`	Points the evaluation run at the rollout, entrypoint, evaluation policy model, and platform dataset
`configs/training/my-rollout.toml`	Points the training run at the rollout code version and training settings

Submit preflight validates the rollout path, then imports the configured entrypoint once so import-time wiring errors surface and fail the submit. The import is best effort: when the local environment does not satisfy the rollout’s declared dependencies, or the import raises ModuleNotFoundError, the CLI warns and submission continues, and the platform validates the entrypoint after installing them. Preflight does not scan the module namespace. Multiple workflow or grader classes may coexist; the backend constructor selects which classes and config objects run.

The import executes the rollout package and entrypoint in your local CLI process, with your filesystem, environment variables, and credentials. Submit only workspace code you trust.

Core Abstractions

Abstraction	What it does	Where to learn more
`AgentWorkflow`	Defines agent behavior: prompt handling, model calls, tool use, and sample creation	AgentWorkflow
`Grader`	Defines reward logic: exact matching, programmatic checks, LLM-as-judge, or custom scoring	Grader
Agent integration	Connects your agent framework to the active Osmosis rollout context	Strands Integration, OpenAI Agents Integration
Execution backend	Runs rollout code in-process or in a Harbor-managed environment	Execution Backends

Choose an Agent Framework

Most rollout authors start with one of the built-in agent integrations:

Strands Agents

Use OsmosisStrandsAgent when you want Strands tools, Strands message handling, and a direct migration path from an existing Strands Agent.

OpenAI Agents

Use OsmosisAgent when your workflow already uses the OpenAI Agents SDK, Runner.run, sessions, handoffs, or OpenAI-style tool orchestration.

Both integrations use an OsmosisRolloutModel placeholder. You do not hard-code the training model inside rollout code; Osmosis resolves the placeholder to the current policy at runtime.

Do not call provider SDKs directly from AgentWorkflow.run() with a fixed model such as openai/gpt-5.2. Direct calls bypass the active RolloutContext, so the platform cannot route policy requests, collect the sample, or connect its reward to the right rollout.

Choose an Execution Backend

If you use osmosis eval submit or osmosis train submit, you do not choose a backend from the CLI. The rollout entrypoint constructs it when the Platform starts the rollout server, and starter templates use LocalBackend unless you choose the Harbor template.

If you build on the Harbor template, run trials in SkyPilot Sandboxes. The Osmosis Platform does not support Docker-backed Harbor execution.

Choose the backend path in that entrypoint or in a self-hosted SDK harness:

Path	Use when
`LocalBackend`	One workflow should process changing dataset prompts in the current Python process
`HarborBackend` template mode	The same prompt-driven workflow needs one reusable, isolated task environment
`HarborBackend` dataset mode	Existing Harbor tasks should keep their own instructions, environments, and verifiers

See Execution Backends for the complete decision guide.

Upgrading an SDK harness from v0.2? LocalBackend keeps its constructor, while v0.3 replaces the pre-v0.3 HarborBackend with the implementation previously named HarborBackendV2. Follow the SDK v0.2 → v0.3 migration guide before changing dependencies.

Start from a Template

If you already have a task or dataset, start with the Custom Rollout Guide. Platform-created workspace repositories include project-local Agent Skills that guide an AI coding agent through dataset planning, rollout creation, evaluation runs, debugging, and training run readiness. Install the package first — see SDK Installation — and run osmosis template apply from inside your cloned workspace directory. List available starter templates:

osmosis template list

Apply a Strands starter:

osmosis template apply multiply-local-strands

Or apply an OpenAI Agents starter:

osmosis template apply multiply-local-openai

Templates are copied from the platform workspace template repository. They write rollout code under rollouts/ plus matching evaluation and training configs, and are the quickest way to see the expected file layout, dependency declaration, and end-to-end workflow.

Next Steps

Custom Rollout Guide

Use project-local Agent Skills to create a task-specific rollout with evaluation run gates.

AgentWorkflow

Learn the AgentWorkflow.run(ctx) contract and common implementation patterns.

Grader

Define reward signals that can drive training.

Strands Integration

Build tool-using rollouts with AWS Strands Agents.

OpenAI Agents Integration

Build rollouts with the OpenAI Agents SDK.

Get started

Core API

Integrations

Execution

Agent tools

Osmosis Python SDK Overview

Training Loop

Files in a Rollout

Core Abstractions

Choose an Agent Framework

Strands Agents

OpenAI Agents

Choose an Execution Backend

Start from a Template

Next Steps

Custom Rollout Guide

AgentWorkflow

Grader

Strands Integration

OpenAI Agents Integration

​Training Loop

​Files in a Rollout

​Core Abstractions

​Choose an Agent Framework

Strands Agents

OpenAI Agents

​Choose an Execution Backend

​Start from a Template

​Next Steps

Custom Rollout Guide

AgentWorkflow

Grader

Strands Integration

OpenAI Agents Integration

Training Loop

Files in a Rollout

Core Abstractions

Choose an Agent Framework

Choose an Execution Backend

Start from a Template

Next Steps