SDK v0.2 → v0.3 Migration Guide

• 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

1. Upgrade the CLI/caller environment and every rollout server environment together to osmosis-ai>=0.3.10,<0.4, keeping the extras your project needs, then refresh their lockfiles. Built-in AgentWorkflow, Grader, and backend constructors keep their existing interfaces.
2. 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.
3. 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.
4. 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.
5. 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.
6. Replace managed SkyPilot placement with a supported Harbor environment. Select OpenSandbox for prebuilt task images or Daytona for Dockerfile-based tasks. HARBOR_SKYPILOT_CONTEXT is no longer read. See managed and self-hosted environments for configuration and credentials.

​

Upgrading from 0.3.3–0.3.6 to 0.3.7

1. Upgrade the CLI, rollout callers, and each rollout’s pyproject.toml dependency to osmosis-ai>=0.3.7,<0.4 with the same extras. Refresh their lockfiles and rebuild affected runtime images to pick up the dependency security fixes. Updating the CLI alone does not update rollout or sandbox packages. Rollouts scaffolded by osmosis rollout init declare osmosis-ai[server]>=0.3.0,<0.4, so raise that floor as well.
2. Remove RolloutClient.drain(), POST /drain, and the drain request/response models introduced in 0.3.5 and removed in 0.3.6. Use health() and wait_idle(process_id=...) to observe work, and SIGTERM for shutdown. wait_idle() does not prevent new admissions or verify external uploads.
3. Give the host enough time for backend shutdown and Harbor sandbox cleanup; see Harbor server shutdown. Custom backends that own resources can implement ExecutionBackend.shutdown().
4. Add timeout_keep_alive=2160 to existing Uvicorn entrypoints, as in the installation example. New 0.3.7 scaffolds already include it; upgrading the package does not rewrite existing entrypoints.
5. For Harbor, review version compatibility and OpenSandbox setup. Existing subclasses keep their build_trial_config, build_agent_config, and harness_agent_config signatures; do not add a preview_path argument to those hooks. Bundled workflows need an updated SDK inside the sandbox to support live previews. Since 0.3.5, Harbor rollout IDs cannot contain colons or control characters; send portable IDs.
6. Remove scripts that invoke the public osmosis dev server or osmosis images commands, or their dedicated OsmosisClient methods; these were removed in 0.3.5. See the changelog for release details.

​

Upgrading from 0.3.7 to 0.3.8

1. Raise the CLI, rollout, and sandbox dependencies to osmosis-ai>=0.3.8,<0.4, keeping the same extras. Update conflicting pins, refresh every lockfile, and rebuild affected runtime images. Upgrading the CLI alone does not update packages or CA bundles inside existing images.
2. Remove reads of RolloutInfo.is_active, the is_active constructor argument, and the is_active key in osmosis rollout list --json. This always-true field was removed. The newly exposed description and last_synced_at fields are metadata, not activity indicators.
3. Add --overwrite when osmosis train info --output <path> should replace an existing file. Without it, the command keeps the file and reports a save warning. See train info.
4. Review Harbor prewarm modes. Dataset mode can discover tasks without explicit IDs, isolated prewarm failures can leave individual tasks unavailable, and the Harbor extra now accepts Harbor >=0.20.0,<0.25.

​

Upgrading from 0.3.8 to 0.3.9

1. Finish interrupted named local eval runs with the SDK version that created them before upgrading. The new source digest changes even when rollout files are unchanged. As a result, 0.3.9 refuses resume and --retry-failed for runs created with 0.3.8 or earlier and reports Changed: rollout.
2. Upgrade the CLI, callers, and rollout dependencies to osmosis-ai>=0.3.9,<0.4 with the same extras. Resolve conflicting pins, refresh lockfiles, and rebuild affected runtime images. The applicable extras now require LiteLLM >=1.103.1,<2.0.0 excluding 1.104.0rc1, filelock >=4.2.1, Strands Agents >=1.48.0,<2.0.0, and OpenTelemetry API >=1.45.1,<2.0.0; see the changelog for which extras own each requirement.
3. After upgrading, use a new run name or --fresh to archive the previous directory and start over. A rejected resume preserves the old manifest and results, and completed old results can still be uploaded. Do not manually change the digest in manifest.json; it also binds the platform import identity. See Source Digest Upgrades.

​

Upgrading from 0.3.9 to 0.3.10

1. Confirm that your Osmosis platform supports archive imports before you upgrade the CLI. In 0.3.10, osmosis eval upload and osmosis eval run --upload send a completed run as a single streamed archive. There is no per-file upload fallback.
2. Upgrade the CLI, callers, and rollout dependencies to osmosis-ai>=0.3.10,<0.4 with the same extras, then refresh lockfiles. Strands rollouts need the update in rollouts/<name>/pyproject.toml to keep earlier assistant reasoning in follow-up requests and trajectories.
3. If you call OsmosisClient.start_eval_run_import() directly instead of using the CLI, pass archive= instead of files=. Upload files.jsonl and run.zip to the returned slots. Then call start_eval_run_import_extraction() and poll get_eval_run_import_extraction() until extraction reaches ready before finalizing the import.
4. Update code that constructs or reads eval-import results. upload_mode is now required, archive imports list their upload slots in files, and a slot’s sha256 can be None.

​

LocalBackend Users

from osmosis_ai.rollout import LocalBackend

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

​

1. Upgrade the Package and Select Features

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

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

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

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

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

​

2. Update Public Imports and Workflow Returns

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

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},
        )

​

3. Move from Many Samples to One Sample

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)

​

4. Register One Agent or Session per Execution

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)

​

5. Update Custom Sample Sources

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()

​

6. Update Custom Routing and Backend Adapters

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

{
  "reward": 1.0
}

​

7. Migrate Dataset Schemas

osmosis dataset validate data/train.jsonl

​

8. Migrate Per-Run Secrets

[secrets]
required = ["OPENAI_API_KEY"]

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

​

9. Verify a LocalBackend Migration

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

​

Common LocalBackend Problems

​

HarborBackend Users

​

1. Upgrade the Package and Import

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

from osmosis_ai.rollout.backend.harbor import HarborBackend

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

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

​

2. Replace the Pre-v0.3 Constructor

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,
)

​

3. Choose a Task Mode

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

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

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

​

4. Package Workflow Code Instead of Mounting It

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()

​

5. Choose an Agent and Reward Source

​

6. Add Prewarming and Lifecycle Controls

from osmosis_ai.rollout.server import create_rollout_server

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

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

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

​

7. Verify a HarborBackend Migration

1. 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
   
2. Confirm that tasks_dir points to a valid template task or dataset root.
3. Build the workflow bundle and fix any package-layout or missing-dependency errors.
4. Run await backend.prewarm() to prewarm the template or discover dataset tasks. Pass task IDs to prewarm a dataset subset, or when using SDK versions before 0.3.8.
5. Submit one rollout and check the workflow sample, reward source, Harbor logs, and archived artifacts.
6. Exercise status and cancellation if the calling controller depends on them.
7. Run an evaluation and compare rewards and final messages with the last successful v0.2 run before training.

​

Common HarborBackend Problems

​

Related Resources

• Execution Backend Overview
• LocalBackend
• HarborBackend
• AgentWorkflow
• Grader
• Changelog