SDK v0.2 → v0.3 迁移指南

Osmosis SDK v0.3 变更了 rollout contract、optional-feature imports 与 extras、workflow return value、Harbor execution、dataset schema 和 run-secret submission。即使 rollout 只使用其中一部分，也应同时完成这些方面的升级。

请同时升级 package requirement、workflow、grader、integrations 和 backend entrypoint。混用 v0.2 rollout 代码与 v0.3 backend 通常会在 runtime 失败。

请选择与当前 backend 对应的迁移路径：

当前 backend	迁移路径
`LocalBackend`	保留 constructor，然后更新共享的 sample、reward、integration 和 routing API
Pre-v0.3 `HarborBackend`	先完成共享 API 变更，再替换 backend constructor 和 container execution model
`HarborBackendV2`	完成共享 API 变更并改名为 `HarborBackend`；它的 v2 constructor 就是 v0.3 constructor

修改代码前：

保留最近一次成功的 v0.2 evaluation run，以便对比。
使用 Python 3.12 或更高版本。
修改 SDK requirement 后，重新创建 rollout environment 和 lockfile。
迁移前后都搜索一次已移除的 API。

升级到 0.3.3

如果已在使用 0.3.0–0.3.2，请先完成本节，再参考后面的 backend 迁移指南。虽然 0.3.3 仍属于 0.3 发布线，它仍变更了 rollout protocol 和自定义 backend contract。

将 CLI/调用方环境与所有 rollout server 环境同时升级到 osmosis-ai>=0.3.10,<0.4，保留项目需要的 extras，并更新各自的 lockfile。内置 AgentWorkflow、Grader 和 backend constructor 的接口保持不变。
用 RolloutClient 替换 HttpRolloutDriver 和 callback request/response models。Completion 改用带 lease 的长轮询；请移除 completion callback URL。每次尝试提供唯一 rollout_id，chat endpoint 要求认证时提供 llm_api_key。await run_rollout_async() 返回可等待的 RolloutHandle，提供状态和阶段等待方法。
将自定义 backend 更新为 async execute(request) -> ExecutionOutcome。返回 ExecutionOutcome(workflow=workflow_result, grader=grader_result)，不再调用 completion callback；通过 active RolloutContext 上的 await rollout_ctx.set_status(RolloutStatus.GRADING) 发布进度。遵循 request.grade；不需要 grading 的运行使用 grade=False。
将本地 LLM bridge 的 import 从 osmosis_ai.rollout.controller 移到 osmosis_ai.eval.local。后者需要 eval extra；RolloutClient 只需要基础 package。
如果已有 local eval run 使用旧 protocol 记录，请用新的 run name 启动运行。Local eval protocol fingerprint 现为 0.4；这些旧 run 无法在 0.3.3 下 resume。需要 resume 时使用之前的 SDK。
将 managed SkyPilot placement 替换为受支持的 Harbor 环境。预构建任务镜像请选择 OpenSandbox，基于 Dockerfile 的任务请选择 Daytona。HARBOR_SKYPILOT_CONTEXT 不再读取。配置与凭据说明见托管与自托管环境。

从 0.3.3–0.3.6 升级到 0.3.7

将 CLI、rollout 调用方以及每个 rollout 的 pyproject.toml 依赖升级到 osmosis-ai>=0.3.7,<0.4，保留原有 extras。更新各自的 lockfile 并重新构建受影响的运行时镜像，以包含依赖安全修复。仅升级 CLI 不会更新 rollout 或 sandbox 中的包。osmosis rollout init 生成的 rollout scaffold 声明的是 osmosis-ai[server]>=0.3.0,<0.4，请一并提高该下限。
移除 0.3.5 引入、0.3.6 删除的 RolloutClient.drain()、POST /drain 以及 drain 请求和响应模型。使用 health() 和 wait_idle(process_id=...)观察任务，通过 SIGTERM 停机。wait_idle() 不阻止新的 admission，也不验证外部上传是否完成。
为 host 预留足够的时间，让 backend 完成停机和 Harbor sandbox 清理；参见 Harbor server 停机。拥有资源的自定义 backend 可以实现 ExecutionBackend.shutdown()。
在已有 Uvicorn entrypoint 中添加 timeout_keep_alive=2160，参见安装示例。0.3.7 新生成的 scaffold 已包含此设置；升级包不会改写已有 entrypoint。
Harbor 用户请查看版本兼容性与 OpenSandbox 配置。已有子类保留 build_trial_config、build_agent_config 和 harness_agent_config 的原有签名；请勿向这些 hook 添加 preview_path 参数。打包的 workflow 需要更新 sandbox 内的 SDK 才能支持实时轨迹预览。自 0.3.5 起，Harbor rollout ID 不能包含冒号或控制字符，请使用可移植的 ID。
移除调用公开 osmosis dev server、osmosis images 命令或其专用 OsmosisClient 方法的脚本；这些功能已在 0.3.5 中删除。各版本详情见更新日志。

从 0.3.7 升级到 0.3.8

将 CLI、rollout 和 sandbox 的依赖下限提高到 osmosis-ai>=0.3.8,<0.4，保留原有 extras。调整冲突的版本限制，更新每份 lockfile，并重新构建受影响的运行时镜像。仅升级 CLI 不会更新已有镜像中的包或 CA bundle。
移除对 RolloutInfo.is_active 的读取、is_active constructor 参数，以及对 osmosis rollout list --json 中 is_active 字段的依赖。这个始终为 true 的字段已被删除。新增的 description 和 last_synced_at 是元数据，不代表活动状态。
如果 osmosis train info --output <path> 需要替换已有文件，请加上 --overwrite。否则命令会保留该文件并报告保存警告。参见 train info。
查看 Harbor prewarm 模式。Dataset mode 可以自动发现 task，无需显式 ID；个别 prewarm 失败可能导致相应 task 不可用；Harbor extra 现支持 Harbor >=0.20.0,<0.25。

以下安装方式适用新的依赖版本下限：

安装方式	依赖要求
基础 package	`certifi>=2026.10.19`
`strands`、`openai-agents`、`harbor`、`rubric` 或 `eval`	`aiohttp>=3.14.4`、`multidict>=6.9.1`
`strands` 或 `openai-agents`	`mcp>=1.30.0,!=2.0.,!=2.1.`
`harbor` 或 `eval`	`uv>=0.13.4,<0.14`

full extra 包含上述要求。完整发布说明见 0.3.8 更新日志。

从 0.3.8 升级到 0.3.9

升级前，请使用创建 run 的 SDK 版本完成被中断的命名本地 eval run。即使 rollout 文件没有变化，新 source digest 也会改变。因此，0.3.9 会拒绝恢复或对 0.3.8 及更早版本创建的 run 使用 --retry-failed，并报告 Changed: rollout。
将 CLI、调用方和 rollout 依赖升级到 osmosis-ai>=0.3.9,<0.4，保留原有 extras。解决冲突的版本限制，更新 lockfile，并重新构建受影响的运行时镜像。相关 extras 现在要求 LiteLLM >=1.103.1,<2.0.0（排除 1.104.0rc1）、filelock >=4.2.1、Strands Agents >=1.48.0,<2.0.0 和 OpenTelemetry API >=1.45.1,<2.0.0；各项要求所属的 extra 见更新日志。
升级后，使用新的 run 名称，或传入 --fresh 归档原目录并重新开始。被拒绝的恢复会保留旧 manifest 和结果，已完成的旧结果仍然可以上传。请勿手动修改 manifest.json 中的 digest，它也绑定了平台导入身份。参见 Source digest upgrades。

新的本地 run 会写入并上传 dataset_rows.jsonl，以支持 prompt 和 ground truth 搜索。已完成的旧 run 仍可在没有该文件的情况下上传；升级不会将该文件补充到旧结果中。Digest 升级后，Harbor bundle cache 会重建一次。 Rollout 结果新增 agent_started_at。在使用 None 识别准备阶段失败之前，请同时升级 server 和调用方；旧 server 会省略该字段。内置 OpenSandbox 环境还支持通过 OPENSANDBOX_REQUEST_TIMEOUT_SEC 设置默认值。

从 0.3.9 升级到 0.3.10

升级 CLI 之前，请确认您的 Osmosis 平台支持 archive import。在 0.3.10 中，osmosis eval upload 和 osmosis eval run --upload 会将已完成的 run 作为单个流式 archive 上传。没有逐文件上传的回退方式。
将 CLI、调用方和 rollout 依赖升级到 osmosis-ai>=0.3.10,<0.4，保留原有 extras，然后更新 lockfile。Strands rollout 需要更新 rollouts/<name>/pyproject.toml，才能在后续请求和 trajectory 中保留先前的 assistant reasoning。
如果您不通过 CLI，而是直接调用 OsmosisClient.start_eval_run_import()，请用 archive= 替换 files=。将 files.jsonl 和 run.zip 上传到返回的 slot，然后调用 start_eval_run_import_extraction()，并轮询 get_eval_run_import_extraction()，直到 extraction 达到 ready 后再完成导入。
更新构造或读取 eval-import 结果的代码。upload_mode 现在为必填字段，archive import 会在 files 中列出上传 slot，且 slot 的 sha256 可以为 None。

已完成的本地 run 无需修改，会以新的 archive 格式上传。参见本地执行与上传。

LocalBackend 用户

LocalBackend 在 v0.3 中保留相同的 keyword-only constructor：

from osmosis_ai.rollout import LocalBackend

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

迁移工作集中在 workflow、grader、integrations，以及 backend 周围的自定义 protocol 代码。

1. 升级 Package 并选择功能

基础 distribution 包含 CLI 和 framework-neutral rollout core。只添加 rollout 实际 import 的 extras：

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"

需要时可以组合 extras。例如，使用 Strands 的 server entrypoint 应声明：

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

其他 extras 包括 openai-agents、harbor、rubric 和 parquet。验证 Parquet dataset 时，请用 parquet 替换以前的 platform extra。对于 source checkout，请使用仓库的 dev dependency group，而不是 published dev extra。

2. 更新 Public Import 和 Workflow Return

Rollout package root 现在只导出 framework-neutral core types。请从对应的 public submodule import 每项 optional feature：

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

请按照 HarborBackend 用户中的示例从 osmosis_ai.rollout.backend.harbor import HarborBackend。不要再依赖 from osmosis_ai import *，也不要使用以前由 osmosis_ai.rollout re-export 的 optional name。 AgentWorkflow.run() 现在返回一个 message history，而不是 samples mapping。可以返回 AgentWorkflowOutput、返回由 SDK 包装为 messages 的 bare message list，或返回 None 以使用 active RolloutContext 收集的 sample：

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

metrics 中的每个 value 都必须是有限值；NaN、正无穷和负无穷都会被拒绝。只有当 integration 或 custom source 已为该 execution 注册 ambient sample 时，才应返回 None。

3. 从多个 Sample 改为一个 Sample

每次 workflow execution 现在最多生成一个 RolloutSample，grader 为它分配一个标量 reward。

v0.2	v0.3	操作
`GraderContext.samples`	`GraderContext.sample`	读取并评分单个 sample
`ctx.set_sample_reward(sample_id, reward)`	`ctx.set_reward(reward)`	移除 sample ID 参数
`register_sample_source(name, source)`	`set_sample_source(source)`	只注册一个 source
`get_samples()`	`get_sample()`	返回一个 `RolloutSample` 或 `None`
`RolloutSample.id`	已移除	使用 execution URL 提供的 rollout identity
`MultiTurnMode`	已移除	在单个 sample 中保留 conversation history
多个已注册 agent 或 session	一个已注册 agent 或 session	把独立 candidates 拆分为不同的 workflow executions

将遍历 samples 的 grader 改为显式检查一个 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)

Workflow 没有生成 sample 时，set_reward() 会抛出 ValueError。在评分前显式抛出错误，通常能提供更清晰的 evaluation failure。

4. 每次 Execution 只注册一个 Agent 或 Session

在 AgentWorkflow.run() 内只构造一个已注册的 OsmosisStrandsAgent 或 OsmosisMemorySession。第二次 registration 会抛出 ValueError。对于 OpenAI Agents，v0.3 session 不再接收 name 或 sample-ID 参数：

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)

Handoff 和 tool call 可以继续保留在这一次 agent run 中。如果一个 prompt 需要多个 candidate answers，请配置 evaluation 或 training 多次执行 workflow。

5. 更新自定义 Sample Source

内置 integrations 已使用 v0.3 API。自定义 integration 必须实现单数形式的 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()

不要为 RolloutSample 设置 id。如需控制标准化的 ATIF transcript，请设置 trajectory_messages；将其设为 None 会关闭该 sample 的 trajectory 持久化。

6. 更新自定义 Routing 和 Backend Adapter

如果只使用内置 integrations 和 LocalBackend，请跳过此步骤。将 execution 提供的 chat-completions URL 视为不透明的 rollout-scoped endpoint。Completion callback URL 已在 0.3.3 中移除。不要追加 rollout ID，也不要附加已移除的 x-sample-id 和 x-rollout-id routing headers。自定义 backend 返回 ExecutionOutcome，包含 workflow 和可选 grader 的 ExecutionResult，每个 result 至多包含一个 sample。如果直接读取 container exchange files，请将 reader 更新为单数 file names 和 payloads：

sample.json

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

reward.json

{
  "reward": 1.0
}

7. 迁移 Dataset Schema

从 0.3.0rc3 开始，是否存在 metadata column 会为整个 dataset 选择一种统一的 schema mode：

模式	每行必需	可选
Prompt mode	`user_prompt` 和 `ground_truth`（接受 `label` 作为 alias）	`system_prompt` 和其他一致的 fields
Metadata mode	Non-empty `metadata` JSON object	`system_prompt` 和其他一致的 fields

不要混用 prompt-mode 和 metadata-mode rows。JSONL rows 必须使用一致的 field set，metadata value 在整个 file 中也必须有效且 type-consistent。Upload 或 submission 前请在本地验证 JSONL、CSV 或 Parquet：

osmosis dataset validate data/train.jsonl

Validator 会扫描每一行 JSONL 和 CSV，以及每个 Parquet metadata value，因此应修复每一条 reported row，而不只是第一个示例。

8. 迁移 Per-Run Secret

在 run config 中只声明 secret name，绝不要填写 value：

[secrets]
required = ["OPENAI_API_KEY"]

Stored secret name 会发送到 platform 并由 server-side 解析。若只想为当前 run 提供 value，请使用 --secrets-file、process environment 或隐藏的 interactive prompt：

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

本地提供的 value 会随受 TLS 保护的 submit request 发送，但不会加入 platform secret store 或持久化 run config，CLI 和 platform response 也不会将其回显。每次 run 都必须重新提供。osmosis train submit 和 osmosis benchmark submit 的行为相同。对于 benchmark run，只有 [secrets].required 中的 name 可以接收 per-run value；model、harness、judge 和 verifier secret reference 必须已存在于 platform secret store 中。

9. 验证 LocalBackend 迁移

确认 rollout 中不再出现已移除的 API：

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

重新创建 rollout environment，确保 lockfile 中包含 osmosis-ai>=0.3.10,<0.4 和所选 extras。
在本地运行 workflow，确认每次成功的 execution 都生成一个 sample。
提交一次 evaluation run，确认每个已评分 sample 都有一个标量 reward。
在提交 training 前，将 reward 和最终 messages 与最近一次成功的 v0.2 evaluation 进行对比。

LocalBackend 常见问题

第二个 agent 或 session 触发 registration error

该 workflow execution 已经注册了 sample source。请复用一个 agent 或 session 完成 conversation，或者将独立 candidates 拆分到不同的 workflow executions。

Grader 没有 sample

请在 AgentWorkflow.run() 内构造受支持的 agent 或 session。在模块 import 时创建的 object 无法向 active rollout context 注册。

无法导入可选 integration

在 rollout-local environment 中安装对应的 extra，然后重新生成 lockfile。

Model call 到达了错误的 rollout

将提供的 chat-completions URL 直接传给 integration。移除重新构造 URL、追加 rollout path segment 或附加旧 routing headers 的代码。

HarborBackend 用户

Harbor 用户必须先完成 LocalBackend 用户中的共享 dependency、import、workflow、grader、sample-source、routing、dataset 和 secret 变更，然后再迁移 Harbor class 和 constructor。

HarborBackend 这个名称在 v0.3 中仍可 import，但现在指向之前名为 HarborBackendV2 的实现。使用 task_dir、user_code_dir 或 workflow 的 pre-v0.3 调用会抛出 TypeError；不存在 legacy compatibility mode。

1. 升级 Package 和 Import

安装 v0.3 Harbor 和 server 功能：

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

harbor extra 已包含 Daytona 和 OpenSandbox 依赖。请在 entrypoint 中选择环境：OpenSandbox 使用预构建任务镜像，Daytona 可以构建任务的 Dockerfile。配置与凭据说明见托管与自托管环境。

使用 Harbor submodule import：

from osmosis_ai.rollout.backend.harbor import HarborBackend

如果已经使用 HarborBackendV2，只需修改 class name，并保留其 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 不会作为 alias 保留。

2. 替换 Pre-v0.3 Constructor

旧 backend 会把 source tree 和 SDK mount 到 task environment。v0.3 backend 会把 workflow project 打包为 wheel，并安装到 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,
)

按照下表迁移所有旧 constructor parameters：

v0.3 之前的参数	v0.3 替代项	迁移说明
`orchestrator=`	`orchestrator=`	保持不变
`task_dir=`	`tasks_dir=` 和 `task_mode=`	一个可复用 task 使用 `"template"`，task directory 集合使用 `"dataset"`
`user_code_dir=`	`code_dir=` 或 `bundle=`	`code_dir` 指向包含 `pyproject.toml` 的 package project，或提供预构建 bundle wheel
`workflow=`	`agent=`	传入 `AgentWorkflow` class/import path 或已注册的原生 Harbor agent name
`workflow_config=`	`workflow_config=`	保持不变；它会与 workflow agent 一起打包
`grader=`	`grader=`	保持不变；grader 会被打包并作为 Harbor verifier 运行
`grader_config=`	`grader_config=`	保持不变
`trials_dir=`	`trials_dir=`	继续支持，但省略时现在使用 backend-specific temporary root，而不是 `Path("trials")`
`custom_tests_dir=`	已移除	把 tests 放在每个 task 的 `tests/` 下，或传入 Osmosis `grader=`
`environment_config=`	`environment_config=`	保持不变
`prebuild_local_image=`	已移除	Harbor 负责 image caching；开始服务前调用 `prewarm()` 或 `prewarm_lifespan()`
`symlink_environment=`	已移除	每个 rollout 都会 materialize 一个 task 副本，并依赖 Harbor image caching
`cleanup_successful_trials=`	`cleanup_successful_trials=`	保持不变

如果 harness 使用了 private _sdk_source_dir argument，请将其移除。 v0.3 constructor 还新增了以下控制项：

新增参数	用途
`native_agent_kwargs`	配置已注册的原生 Harbor agent
`model_name`	选择原生 agent model；默认为 `openai/osmosis-rollout`
`bundle`	复用预构建 Osmosis bundle wheel，而不是从 `code_dir` 构建
`patch_dockerfile_with_sdk`	控制是否在 task image 中预装 bundle dependencies
`agent_setup_timeout_sec`	限制 Harbor agent setup 时间
`max_queue_depth`	限制 queued rollouts，并启用 `429` admission control

3. 选择 Task Mode

要最接近地替代旧的单个 task_dir，请使用 template mode：

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

Request prompt 会在每个 rollout 的副本中替换 instruction.md。这会保留与 LocalBackend 相同的 prompt ownership，同时增加 Harbor trial environment。当 tasks_dir 中每个 task 都有独立目录时，请使用 dataset mode：

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

每个 request 都必须设置 metadata["harbor_task_id"]；选中的 task 会保留自己的 instruction.md。需要保留已编写 Harbor tasks，或已经可以逐 task 运行的本地 Harbor dataset 时，请使用此 mode。无论使用哪种 mode，metadata["harbor_task"] 都可以选择 per-rollout 本地路径、"org/name@ref" 形式的 Harbor registry package，或 Git task。Git task 还需要设置 metadata["git_url"]，并应固定 metadata["git_commit_id"]。如果旧 backend 使用 custom_tests_dir，请把这些 tests 移入每个 task：

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

即使同时配置 grader=，task-native verifier 仍然是权威来源；只有缺少 tests/test.sh 时，backend 才会生成 Osmosis grader verifier。传入 grader=None 可明确选择 task-native reward path。

4. 打包 Workflow 代码，而不是 Mount

对于 AgentWorkflow，backend 会从 code_dir 构建 wheel，并在 trial 启动时安装到 container。该目录必须包含 pyproject.toml 和一个可导入的 top-level Python package。省略 code_dir 时，backend 会尝试定位包含 workflow class 的 project。如果 build system 会提前创建 Osmosis bundle wheel，请使用 bundle=。不要同时传入两个路径并期望它们合并；提供 bundle 后会直接使用它。旧的 HarborAgentWorkflowContext.environment adapter 已移除。Workflow 现在会在 task container 内运行，接收标准 AgentWorkflowContext，并通过普通 Python API 访问文件或 processes：

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 也已移除。不要实例化或继承它；请通过 agent= 传入 AgentWorkflow，或选择已注册的原生 Harbor agent name。

5. 选择 Agent 和 Reward Source

agent= 接受 AgentWorkflow class/import path，或以下已注册的原生名称之一："terminus-2"、"mini-swe-agent" 和 "oracle"。

"oracle" 会运行 reference solution 来验证 dataset 或 verifier。它不会生成 model trajectory，不能用于 training。

请选择一种 reward 路径：

配置	Reward 来源
`grader=MyGrader`	打包后的 Osmosis grader 作为 Harbor verifier 运行
`grader=None`	Task 自己的 `tests/` 生成 reward

6. 添加 Prewarming 和 Lifecycle Controls

在 rollout server 接收流量前，prewarm 所选 task images 和 agent setup：

from osmosis_ai.rollout.server import create_rollout_server

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

从 0.3.8 起，dataset mode 在省略 ID 时会自动发现 tasks_dir 下的 task。若只需预热部分 task，请传入其 ID：

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

设置 max_queue_depth 后，queue 已满时 POST /rollout 会返回带 Retry-After: 5 的 429。v0.3 还提供：

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

7. 验证 HarborBackend 迁移

确认旧 class 和 constructor keywords 不再出现：

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

确认 tasks_dir 指向有效的 template task 或 dataset root。
构建 workflow bundle，并修复 package layout 或缺少 dependency 的错误。
运行 await backend.prewarm() 预热 template 或自动发现 dataset task。若只需预热部分 dataset task，或使用 0.3.8 之前的 SDK，请传入 task ID。
提交一个 rollout，并检查 workflow sample、reward source、Harbor logs 和已归档 artifacts。
如果 calling controller 依赖 status 和 cancellation，请实际验证这些功能。
在 training 前运行 evaluation，并将 reward 和最终 messages 与最近一次成功的 v0.2 run 对比。

HarborBackend 常见问题

HarborBackend 拒绝 task_dir、user_code_dir 或 workflow

Import 已解析到 v0.3 backend，但调用仍使用已移除的 constructor。请按照上表替换所有旧 parameters。

无法打包 workflow project

将 code_dir 指向包含 pyproject.toml 和一个可导入 package 的目录。确保 workflow 和 grader 可以通过该 package 的 import path 寻址。

Dataset-mode request 找不到 task

将 metadata["harbor_task_id"] 设为 tasks_dir 下的目录，或将 metadata["harbor_task"] 设为受支持的本地、package 或 Git reference。

Trial 完成后没有 reward

如果 task 包含 tests/test.sh，请修复该 verifier，并确认它会输出 Harbor 的 reward channel；Osmosis grader 不会覆盖它。如果 task 没有 verifier，则改为传入 Osmosis grader。

Rollout 代码仍依赖 ctx.environment

移除 legacy adapter 调用。Workflow 现在运行在 container 内，因此请使用普通 filesystem、subprocess 和 network API。

版本说明

迁移指南

SDK v0.2 → v0.3 迁移指南

升级到 0.3.3

从 0.3.3–0.3.6 升级到 0.3.7

从 0.3.7 升级到 0.3.8

从 0.3.8 升级到 0.3.9

从 0.3.9 升级到 0.3.10

LocalBackend 用户

1. 升级 Package 并选择功能

2. 更新 Public Import 和 Workflow Return

3. 从多个 Sample 改为一个 Sample

4. 每次 Execution 只注册一个 Agent 或 Session

5. 更新自定义 Sample Source

6. 更新自定义 Routing 和 Backend Adapter

7. 迁移 Dataset Schema

8. 迁移 Per-Run Secret

9. 验证 LocalBackend 迁移

LocalBackend 常见问题

HarborBackend 用户

1. 升级 Package 和 Import

2. 替换 Pre-v0.3 Constructor

3. 选择 Task Mode

4. 打包 Workflow 代码，而不是 Mount

5. 选择 Agent 和 Reward Source

6. 添加 Prewarming 和 Lifecycle Controls

7. 验证 HarborBackend 迁移

HarborBackend 常见问题

相关资源

​升级到 0.3.3

​从 0.3.3–0.3.6 升级到 0.3.7

​从 0.3.7 升级到 0.3.8

​从 0.3.8 升级到 0.3.9

​从 0.3.9 升级到 0.3.10

​LocalBackend 用户

​1. 升级 Package 并选择功能

​2. 更新 Public Import 和 Workflow Return

​3. 从多个 Sample 改为一个 Sample

​4. 每次 Execution 只注册一个 Agent 或 Session

​5. 更新自定义 Sample Source

​6. 更新自定义 Routing 和 Backend Adapter

​7. 迁移 Dataset Schema

​8. 迁移 Per-Run Secret

​9. 验证 LocalBackend 迁移

​LocalBackend 常见问题

​HarborBackend 用户

​1. 升级 Package 和 Import

​2. 替换 Pre-v0.3 Constructor

​3. 选择 Task Mode

​4. 打包 Workflow 代码，而不是 Mount

​5. 选择 Agent 和 Reward Source

​6. 添加 Prewarming 和 Lifecycle Controls

​7. 验证 HarborBackend 迁移

​HarborBackend 常见问题

​相关资源

升级到 0.3.3

从 0.3.3–0.3.6 升级到 0.3.7

从 0.3.7 升级到 0.3.8

从 0.3.8 升级到 0.3.9

从 0.3.9 升级到 0.3.10

LocalBackend 用户

1. 升级 Package 并选择功能

2. 更新 Public Import 和 Workflow Return

3. 从多个 Sample 改为一个 Sample

4. 每次 Execution 只注册一个 Agent 或 Session

5. 更新自定义 Sample Source

6. 更新自定义 Routing 和 Backend Adapter

7. 迁移 Dataset Schema

8. 迁移 Per-Run Secret

9. 验证 LocalBackend 迁移

LocalBackend 常见问题

HarborBackend 用户

1. 升级 Package 和 Import

2. 替换 Pre-v0.3 Constructor

3. 选择 Task Mode

4. 打包 Workflow 代码，而不是 Mount

5. 选择 Agent 和 Reward Source

6. 添加 Prewarming 和 Lifecycle Controls

7. 验证 HarborBackend 迁移

HarborBackend 常见问题

相关资源