SDK v0.2 → v0.3 Migration Guide

Osmosis SDK v0.3 changes the rollout contract, optional-feature imports and extras, workflow return values, Harbor execution, dataset schemas, and run-secret submission. Upgrade across these areas together even if your rollout uses only a subset of them.

Upgrade the package requirement, workflow, grader, integrations, and backend entrypoint together. Mixing v0.2 rollout code with a v0.3 backend usually fails at runtime.

Use the section that matches your backend:

Current backend	Migration path
`LocalBackend`	Keep its constructor, then update the shared sample, reward, integration, and routing APIs
Pre-v0.3 `HarborBackend`	Apply the shared API changes, then replace the backend constructor and container execution model
`HarborBackendV2`	Apply the shared API changes and rename it to `HarborBackend`; its v2 constructor is the v0.3 constructor

Before changing code:

Keep the last successful v0.2 evaluation run for comparison.
Use Python 3.12 or later.
Recreate the rollout environment and lockfile after changing the SDK requirement.
Search for removed APIs before and after the migration.

Upgrading to 0.3.3

If you already use 0.3.0–0.3.2, apply this section before the backend-specific guidance below. Version 0.3.3 changes the rollout protocol and custom backend contract even though it remains in the 0.3 release line.

Upgrade the CLI/caller environment and every rollout server environment together to osmosis-ai>=0.3.3,<0.4, keeping the extras your project needs, then refresh their lockfiles. Built-in AgentWorkflow, Grader, and backend constructors keep their existing interfaces.
Replace HttpRolloutDriver and callback request/response models with RolloutClient. Completion now uses leased long polling; remove completion callback URLs. Supply a unique rollout_id for each attempt and llm_api_key when the chat endpoint requires authentication. await run_rollout_async() returns an awaitable RolloutHandle with status and phase-wait methods.
Update custom backends to async execute(request) -> ExecutionOutcome. Return ExecutionOutcome(workflow=workflow_result, grader=grader_result) instead of invoking completion callbacks, and publish progress through await rollout_ctx.set_status(RolloutStatus.GRADING) on the active RolloutContext. Respect request.grade; use grade=False for ungraded runs.
Move local LLM bridge imports from osmosis_ai.rollout.controller to osmosis_ai.eval.local. The latter requires the eval extra; RolloutClient needs only the base package.
Start local eval with a new run name if an existing run was recorded with the older protocol. The local eval protocol fingerprint is now 0.4; those older runs cannot resume under 0.3.3. Use the previous SDK to resume them.
Replace managed SkyPilot placement with EnvironmentConfig(type=EnvironmentType.DAYTONA) and configure DAYTONA_API_KEY. HARBOR_SKYPILOT_CONTEXT is no longer read. See managed and self-hosted environments for credentials and Daytona inactivity cleanup.

LocalBackend Users

LocalBackend keeps the same keyword-only constructor in v0.3:

from osmosis_ai.rollout import LocalBackend

backend = LocalBackend(
    workflow=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
)

The migration work is in the workflow, grader, integrations, and any custom protocol code around the backend.

1. Upgrade the Package and Select Features

The base distribution contains the CLI and framework-neutral rollout core. Add only the extras your rollout imports:

pip install --upgrade "osmosis-ai[strands]>=0.3.3,<0.4"

pip install --upgrade "osmosis-ai[openai-agents]>=0.3.3,<0.4"

pip install --upgrade "osmosis-ai[server]>=0.3.3,<0.4"

pip install --upgrade "osmosis-ai[full]>=0.3.3,<0.4"

Combine extras when needed. For example, a server entrypoint using Strands should declare:

[project]
dependencies = [
    "osmosis-ai[server,strands]>=0.3.3,<0.4",
]

Other extras include openai-agents, harbor, rubric, and parquet. Replace the former platform extra with parquet when validating Parquet datasets. For a source checkout, use the repository’s dev dependency group instead of a published dev extra.

2. Update Public Imports and Workflow Returns

The rollout package root now exposes only framework-neutral core types. Import each optional feature from its public submodule:

from osmosis_ai.rollout.integrations.agents.strands import (
    OsmosisRolloutModel,
    OsmosisStrandsAgent,
)

from osmosis_ai.rollout.integrations.agents.openai_agents import (
    OsmosisAgent,
    OsmosisMemorySession,
    OsmosisRolloutModel,
)

from osmosis_ai.rollout.server import create_rollout_server

from osmosis_ai.eval.rubric import evaluate_rubric

Import HarborBackend from osmosis_ai.rollout.backend.harbor as shown in HarborBackend Users. Do not rely on from osmosis_ai import * or optional names formerly re-exported by osmosis_ai.rollout. AgentWorkflow.run() now returns one message history, not a mapping of samples. Return an AgentWorkflowOutput, return a bare message list that the SDK wraps as messages, or return None to use the sample collected from the active RolloutContext:

from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext, AgentWorkflowOutput


class MyWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> AgentWorkflowOutput:
        messages = await run_agent(ctx.prompt)
        return AgentWorkflowOutput(
            messages=messages,
            metrics={"latency_seconds": 1.25},
        )

Every value in metrics must be finite; NaN and positive or negative infinity are rejected. Use None only when an integration or custom source registered the ambient sample for that execution.

3. Move from Many Samples to One Sample

Each workflow execution now produces at most one RolloutSample, and its grader assigns one scalar reward.

v0.2	v0.3	Action
`GraderContext.samples`	`GraderContext.sample`	Read and score the single sample
`ctx.set_sample_reward(sample_id, reward)`	`ctx.set_reward(reward)`	Remove the sample ID argument
`register_sample_source(name, source)`	`set_sample_source(source)`	Register exactly one source
`get_samples()`	`get_sample()`	Return one `RolloutSample` or `None`
`RolloutSample.id`	Removed	Use the rollout identity supplied by the execution URLs
`MultiTurnMode`	Removed	Keep the conversation history inside the single sample
Multiple registered agents or sessions	One registered agent or session	Run independent candidates as separate workflow executions

Update graders from a loop over samples to one explicit sample check:

class ExactMatchGrader(Grader):
    async def grade(self, ctx: GraderContext) -> None:
        for sample_id, sample in ctx.samples.items():
            answer = last_text(sample)
            reward = 1.0 if answer == ctx.label else 0.0
            ctx.set_sample_reward(sample_id, reward)

class ExactMatchGrader(Grader):
    async def grade(self, ctx: GraderContext) -> None:
        if ctx.sample is None:
            raise ValueError("workflow produced no sample")
        answer = last_text(ctx.sample)
        reward = 1.0 if answer == ctx.label else 0.0
        ctx.set_reward(reward)

set_reward() raises ValueError when the workflow produced no sample. Raising an explicit error before scoring generally gives a clearer evaluation failure.

4. Register One Agent or Session per Execution

Construct exactly one registered OsmosisStrandsAgent or OsmosisMemorySession inside AgentWorkflow.run(). A second registration raises ValueError. For OpenAI Agents, the v0.3 session has no name or sample-ID argument:

class OpenAIWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisAgent(
            name="assistant",
            instructions="Answer the user's request clearly.",
            model=OsmosisRolloutModel(),
        )
        session = OsmosisMemorySession()
        await Runner.run(agent, ctx.prompt, session=session)

Handoffs and tool calls can remain inside that one agent run. If you need several candidate answers for one prompt, configure evaluation or training to execute the workflow several times.

5. Update Custom Sample Sources

Built-in integrations already use the v0.3 API. A custom integration must implement the singular source contract:

from typing import Any

from osmosis_ai.rollout import RolloutSample, SampleSource


class MySampleSource(SampleSource):
    def __init__(self, messages: list[dict[str, Any]]) -> None:
        self.messages = messages

    async def get_sample(self) -> RolloutSample:
        return RolloutSample(messages=self.messages)


rollout_ctx.set_sample_source(MySampleSource(messages))
sample = await rollout_ctx.get_sample()

Do not set an id on RolloutSample. To control the normalized ATIF transcript, set trajectory_messages; setting it to None disables trajectory persistence for that sample.

6. Update Custom Routing and Backend Adapters

Skip this step if you only use the built-in integrations and LocalBackend. Treat the chat-completions URL supplied for an execution as an opaque, rollout-scoped endpoint. Completion callback URLs were removed in 0.3.3. Do not append a rollout ID or attach the removed x-sample-id and x-rollout-id routing headers. Custom backends return an ExecutionOutcome containing workflow and optional grader ExecutionResult values, each with at most one sample. If you read the container exchange files directly, update readers to the singular file names and payloads:

sample.json

{
  "messages": [],
  "reward": null,
  "remove_sample": false,
  "metrics": {},
  "extra_fields": {}
}

reward.json

{
  "reward": 1.0
}

7. Migrate Dataset Schemas

Starting with 0.3.0rc3, the presence of a metadata column selects one uniform schema mode for the entire dataset:

Mode	Required on every row	Optional
Prompt mode	`user_prompt` and `ground_truth` (`label` is accepted as an alias)	`system_prompt` and other consistent fields
Metadata mode	A non-empty `metadata` JSON object	`system_prompt` and other consistent fields

Do not mix prompt-mode and metadata-mode rows. JSONL rows must use a consistent field set, and metadata values must remain valid and type-consistent across the file. Validate JSONL, CSV, or Parquet locally before upload or submission:

osmosis dataset validate data/train.jsonl

The validator scans every JSONL and CSV row and every Parquet metadata value, so fix every reported row rather than only the first example.

8. Migrate Per-Run Secrets

Declare secret names, never values, in the run config:

[secrets]
required = ["OPENAI_API_KEY"]

Stored secret names are sent to the platform and resolved server-side. To provide a value only for the current run, use --secrets-file, the process environment, or the hidden interactive prompt:

osmosis eval submit configs/eval/my-rollout.toml --secrets-file .env.run

Locally provided values are sent in the TLS-protected submit request but are not added to the platform secret store or persistent run config, and the CLI and platform response do not echo them. Supply them again for each run. The same behavior applies to osmosis train submit and osmosis benchmark submit. For benchmark runs, only names in [secrets].required can receive per-run values; model, harness, judge, and verifier secret references must already exist in the platform secret store.

9. Verify a LocalBackend Migration

Confirm that removed APIs no longer appear in the rollout:

rg "ctx\.samples|set_sample_reward|register_sample_source|get_samples|MultiTurnMode|x-sample-id|x-rollout-id" rollouts

Recreate the rollout environment so its lockfile contains osmosis-ai>=0.3.3,<0.4 and the selected extras.
Run the workflow locally and confirm that each successful execution produces one sample.
Submit an evaluation run and confirm that each graded sample has one scalar reward.
Compare rewards and final messages with the last successful v0.2 evaluation before submitting training.

Common LocalBackend Problems

A second agent or session raises a registration error

The workflow execution already registered its sample source. Reuse one agent or session for the conversation, or move independent candidates into separate workflow executions.

The grader has no sample

Construct the supported agent or session inside AgentWorkflow.run(). Objects created at module import time cannot register with the active rollout context.

An optional integration cannot be imported

Install the matching extra in the rollout-local environment and regenerate its lockfile.

Model calls reach the wrong rollout

Pass the supplied chat-completions URL directly to the integration. Remove code that reconstructs the URL, adds a rollout path segment, or attaches legacy routing headers.

HarborBackend Users

Harbor users must first apply the shared dependency, import, workflow, grader, sample-source, routing, dataset, and secret changes in LocalBackend Users. Then migrate the Harbor class and constructor.

The name HarborBackend still imports in v0.3, but it now refers to the implementation previously called HarborBackendV2. A pre-v0.3 call using task_dir, user_code_dir, or workflow raises TypeError; there is no legacy compatibility mode.

1. Upgrade the Package and Import

Install the v0.3 Harbor and server features:

pip install --upgrade "osmosis-ai[server,harbor]>=0.3.3,<0.4"

The harbor extra includes Daytona dependencies. For managed rollouts, explicitly select EnvironmentType.DAYTONA and configure DAYTONA_API_KEY as described in Managed and Self-Hosted Environments.

Use the Harbor submodule import:

from osmosis_ai.rollout.backend.harbor import HarborBackend

If you already use HarborBackendV2, change only the class name and keep its v2 constructor arguments:

# v0.2 preview API
from osmosis_ai.rollout.backend.harbor import HarborBackendV2

# v0.3
from osmosis_ai.rollout.backend.harbor import HarborBackend

HarborBackendV2 is not retained as an alias.

2. Replace the Pre-v0.3 Constructor

The old backend mounted your source tree and SDK into a task environment. The v0.3 backend packages the workflow project into a wheel and installs it inside the task container.

from pathlib import Path

from osmosis_ai.rollout.backend.harbor import HarborBackend

backend = HarborBackend(
    orchestrator=trial_queue,
    task_dir=Path("tasks/my-task"),
    user_code_dir=Path("."),
    workflow=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
    cleanup_successful_trials=True,
)

from pathlib import Path

from osmosis_ai.rollout.backend.harbor import HarborBackend

backend = HarborBackend(
    orchestrator=trial_queue,
    tasks_dir=Path("tasks/my-task"),
    task_mode="template",
    agent=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
    code_dir=Path("."),
    cleanup_successful_trials=True,
)

Migrate every old constructor parameter with this table:

Pre-v0.3 parameter	v0.3 replacement	Migration notes
`orchestrator=`	`orchestrator=`	Carries over unchanged
`task_dir=`	`tasks_dir=` and `task_mode=`	Use `"template"` for one reusable task or `"dataset"` for a directory of tasks
`user_code_dir=`	`code_dir=` or `bundle=`	Point `code_dir` at a package project with `pyproject.toml`, or provide a prebuilt bundle wheel
`workflow=`	`agent=`	Pass an `AgentWorkflow` class/import path or a registered native Harbor agent name
`workflow_config=`	`workflow_config=`	Carries over; it is packaged with a workflow agent
`grader=`	`grader=`	Carries over; the grader is packaged and runs as the Harbor verifier
`grader_config=`	`grader_config=`	Carries over unchanged
`trials_dir=`	`trials_dir=`	Carries over, but omitting it now uses a backend-specific temporary root instead of `Path("trials")`
`custom_tests_dir=`	Removed	Put tests under each task’s `tests/`, or pass an Osmosis `grader=`
`environment_config=`	`environment_config=`	Carries over unchanged
`prebuild_local_image=`	Removed	Harbor handles image caching; call `prewarm()` or `prewarm_lifespan()` before serving
`symlink_environment=`	Removed	Each rollout materializes a task copy and relies on Harbor image caching
`cleanup_successful_trials=`	`cleanup_successful_trials=`	Carries over unchanged

Remove the private _sdk_source_dir argument if your harness used it. The v0.3 constructor also adds these controls:

New parameter	Use
`native_agent_kwargs`	Configure a registered native Harbor agent
`model_name`	Select the native agent model; defaults to `openai/osmosis-rollout`
`bundle`	Reuse a prebuilt Osmosis bundle wheel instead of building from `code_dir`
`patch_dockerfile_with_sdk`	Control preinstallation of bundle dependencies in the task image
`agent_setup_timeout_sec`	Limit Harbor agent setup time
`max_queue_depth`	Bound queued rollouts and enable `429` admission control

3. Choose a Task Mode

For the closest replacement of the old single task_dir, use template mode:

backend = HarborBackend(
    orchestrator=trial_queue,
    tasks_dir=Path("tasks/my-task"),
    task_mode="template",
    agent=MyWorkflow,
)

The request prompt replaces instruction.md in a per-rollout copy of that task. This keeps the same prompt ownership as LocalBackend while adding a Harbor trial environment. Use dataset mode when tasks_dir contains one directory per task:

backend = HarborBackend(
    orchestrator=trial_queue,
    tasks_dir=Path("tasks"),
    task_mode="dataset",
    agent=MyWorkflow,
)

Each request must set metadata["harbor_task_id"]; the selected task keeps its own instruction.md. Use this mode to preserve authored Harbor tasks or a local Harbor dataset that already runs task-by-task. For either mode, metadata["harbor_task"] can select a per-rollout local path, Harbor registry package such as "org/name@ref", or Git task. Git tasks also set metadata["git_url"] and should pin metadata["git_commit_id"]. If the old backend used custom_tests_dir, move those tests into each task:

tasks/my-task/
├── instruction.md
├── task.toml
├── environment/
│   └── Dockerfile
└── tests/
    └── test.sh

The task-native verifier remains authoritative even if grader= is also configured; the backend generates an Osmosis grader verifier only when tests/test.sh is absent. Pass grader=None to make the task-native reward path explicit.

4. Package Workflow Code Instead of Mounting It

For an AgentWorkflow, the backend builds a wheel from code_dir and installs it in the container at trial start. The directory must contain pyproject.toml and one importable top-level Python package. When code_dir is omitted, the backend tries to locate the project containing the workflow class. Use bundle= when your build system creates the Osmosis bundle wheel ahead of time. Do not pass both paths expecting them to be merged; a supplied bundle is used directly. The old HarborAgentWorkflowContext.environment adapter is gone. The workflow itself now runs inside the task container, receives a standard AgentWorkflowContext, and accesses files or processes through normal Python APIs:

import asyncio

from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext


class HarborWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        result = await asyncio.create_subprocess_exec(
            "python",
            "/workspace/run_task.py",
        )
        await result.wait()

OsmosisInstalledAgent is also removed. Do not instantiate or subclass it; pass an AgentWorkflow through agent=, or select a registered native Harbor agent name.

5. Choose an Agent and Reward Source

agent= accepts an AgentWorkflow class/import path or one of the registered native names: "terminus-2", "mini-swe-agent", and "oracle".

"oracle" runs a reference solution to validate a dataset or verifier. It does not emit a model trajectory and must not be used for training.

Choose one reward path:

Configuration	Reward source
`grader=MyGrader`	The bundled Osmosis grader runs as the Harbor verifier
`grader=None`	The task’s own `tests/` produce the reward

6. Add Prewarming and Lifecycle Controls

Prewarm the selected task images and agent setup before the rollout server accepts traffic:

from osmosis_ai.rollout.server import create_rollout_server

app = create_rollout_server(
    backend=backend,
    lifespan=backend.prewarm_lifespan(),
)

Dataset mode requires explicit task IDs:

app = create_rollout_server(
    backend=backend,
    lifespan=backend.prewarm_lifespan(["task-a", "task-b"]),
)

If you set max_queue_depth, POST /rollout returns 429 with Retry-After: 5 when the queue is full. v0.3 also exposes:

GET /rollout/{rollout_id}/status
POST /rollout/cancel
HarborBackend.rollout_status()
HarborBackend.cancel_rollouts()

7. Verify a HarborBackend Migration

Confirm that the old class and constructor keywords no longer appear:

rg "HarborBackendV2|HarborAgentWorkflowContext|OsmosisInstalledAgent|task_dir=|user_code_dir=|workflow=|custom_tests_dir=|prebuild_local_image=|symlink_environment=" rollouts

Confirm that tasks_dir points to a valid template task or dataset root.
Build the workflow bundle and fix any package-layout or missing-dependency errors.
Run await backend.prewarm() for template mode, or pass task IDs in dataset mode.
Submit one rollout and check the workflow sample, reward source, Harbor logs, and archived artifacts.
Exercise status and cancellation if the calling controller depends on them.
Run an evaluation and compare rewards and final messages with the last successful v0.2 run before training.

Common HarborBackend Problems

HarborBackend rejects task_dir, user_code_dir, or workflow

The import resolves to the v0.3 backend, but the call still uses the removed constructor. Replace all stale parameters with the table above.

The workflow project cannot be bundled

Point code_dir at the directory containing pyproject.toml and one importable package. Ensure the workflow and grader can be addressed as import paths from that package.

A dataset-mode request cannot find its task

Set metadata["harbor_task_id"] to a directory beneath tasks_dir, or set metadata["harbor_task"] to a supported local, package, or Git reference.

The trial finishes without a reward

If the task contains tests/test.sh, fix that verifier and make sure it emits Harbor’s reward channel; an Osmosis grader does not override it. If the task has no verifier, pass an Osmosis grader instead.

Rollout code expects ctx.environment

Remove the legacy adapter calls. The workflow now runs inside the container, so use normal filesystem, subprocess, and network APIs.

Release notes

Migration guides

SDK v0.2 → v0.3 Migration Guide

Upgrading to 0.3.3

LocalBackend Users

1. Upgrade the Package and Select Features

2. Update Public Imports and Workflow Returns

3. Move from Many Samples to One Sample

4. Register One Agent or Session per Execution

5. Update Custom Sample Sources

6. Update Custom Routing and Backend Adapters

7. Migrate Dataset Schemas

8. Migrate Per-Run Secrets

9. Verify a LocalBackend Migration

Common LocalBackend Problems

HarborBackend Users

1. Upgrade the Package and Import

2. Replace the Pre-v0.3 Constructor

3. Choose a Task Mode

4. Package Workflow Code Instead of Mounting It

5. Choose an Agent and Reward Source

6. Add Prewarming and Lifecycle Controls

7. Verify a HarborBackend Migration

Common HarborBackend Problems

​Upgrading to 0.3.3

​LocalBackend Users

​1. Upgrade the Package and Select Features

​2. Update Public Imports and Workflow Returns

​3. Move from Many Samples to One Sample

​4. Register One Agent or Session per Execution

​5. Update Custom Sample Sources

​6. Update Custom Routing and Backend Adapters

​7. Migrate Dataset Schemas

​8. Migrate Per-Run Secrets

​9. Verify a LocalBackend Migration

​Common LocalBackend Problems

​HarborBackend Users

​1. Upgrade the Package and Import

​2. Replace the Pre-v0.3 Constructor

​3. Choose a Task Mode

​4. Package Workflow Code Instead of Mounting It

​5. Choose an Agent and Reward Source

​6. Add Prewarming and Lifecycle Controls

​7. Verify a HarborBackend Migration

​Common HarborBackend Problems

​Related Resources

Upgrading to 0.3.3

LocalBackend Users

1. Upgrade the Package and Select Features

2. Update Public Imports and Workflow Returns

3. Move from Many Samples to One Sample

4. Register One Agent or Session per Execution

5. Update Custom Sample Sources

6. Update Custom Routing and Backend Adapters

7. Migrate Dataset Schemas

8. Migrate Per-Run Secrets

9. Verify a LocalBackend Migration

Common LocalBackend Problems

HarborBackend Users

1. Upgrade the Package and Import

2. Replace the Pre-v0.3 Constructor

3. Choose a Task Mode

4. Package Workflow Code Instead of Mounting It

5. Choose an Agent and Reward Source

6. Add Prewarming and Lifecycle Controls

7. Verify a HarborBackend Migration

Common HarborBackend Problems

Related Resources