跳转到主要内容
大多数用户不需要通过 CLI 配置执行后端。osmosis eval submit 和 osmosis train submit 都会把执行交给 Osmosis 平台；rollout entrypoint 在服务端构造 backend。本页面是面向把开源 osmosis-ai 包嵌入自定义 harness 或自托管实验的用户的 SDK 级指南。
当您直接通过 SDK 编排 rollouts 时，执行后端决定 AgentWorkflow 和 Grader 在哪里运行。
BackendRuns whereBest for
LocalBackend当前 Python 进程快速本地开发、自定义 eval harnesses、调试
HarborBackendHarbor-managed trial environments每次 trial 隔离、task environments、依赖隔离

​
后端职责

每个后端都有相同的核心职责：
1

接收 execution request

Request 包含某一行数据集的输入 prompt，以及在启用 grading 时使用的参考 label。
2

运行 workflow

后端创建 AgentWorkflowContext，安装 RolloutContext，并调用 AgentWorkflow.run(ctx)。
3

收集 samples

OsmosisStrandsAgent 和 OsmosisAgent 等 agent integrations 会在 rollout context 上注册 sample sources。Workflow 完成后，后端会收集这些 samples。
4

运行 grader

如果 grader 和 label 可用，后端会创建 GraderContext 并调用 Grader.grade(ctx)。
5

返回结构化结果

后端返回包含 status、samples、rewards 和任何分类错误的 ExecutionResult objects。

​
ExecutionBackend 接口

所有后端都实现以下形状： 
class ExecutionBackend(ABC):
    async def execute(
        self,
        request: ExecutionRequest,
        on_workflow_complete: ResultCallback,
        on_grader_complete: ResultCallback | None = None,
    ) -> None: ...

    @property
    def max_concurrency(self) -> int: ...  # 0 = no limit

    def health(self) -> dict[str, Any]: ...  # default: {"status": "ok"}
MethodDescription
execute()为一个 request 运行 AgentWorkflow，并可选运行 Grader
max_concurrency最大并行执行数。0 表示无限制。
health()返回后端健康信息

​
LocalBackend

LocalBackend 会在当前 Python 进程中直接执行 workflow 和 grader。 
from osmosis_ai.rollout.backend import LocalBackend

backend = LocalBackend(
    workflow=MyWorkflow,
    workflow_config=my_workflow_config,
    grader=MyGrader,
    grader_config=my_grader_config,
)
Constructor fields：
ParameterTypeDescription
workflowclass or "module:attr" stringAgentWorkflow subclass 或 import path
workflow_configAgentWorkflowConfig | None传给 workflow 的可选 config
graderclass or "module:attr" string可选 Grader subclass 或 import path
grader_configGraderConfig | None传给 grader 的可选 config
适合使用 LocalBackend 的情况：
  • 您需要最短的调试循环。
  • 您需要 breakpoints、stack traces 或简单 print debugging。
  • 您的 rollout 可以共享当前 Python 环境。
  • 您正在围绕 SDK 构建自定义 harness 或 eval runner。
LocalBackend 使用 AgentWorkflowConfig.concurrency.max_concurrent 限制并行 workflow executions。如果没有提供 workflow config，默认 concurrency 为 4。

​
本地错误分类

LocalBackend 会把 workflow 和 grader exceptions 映射到结构化 categories：
ExceptionCategory
TimeoutErrorTIMEOUT
ValueError, TypeError, AssertionErrorVALIDATION_ERROR
Other exceptionsAGENT_ERROR

​
HarborBackend

HarborBackend 会在 Harbor-managed trial environments 中运行 workflows。对于面向平台的 Harbor rollouts，请使用 workspace template 使用的 Daytona-backed 路径；当前 managed platform 不支持 Docker-backed Harbor execution。
仅在需要面向平台训练的 Harbor-specific execution 或 SDK 级实验时，才使用 Daytona-backed Harbor template。当前 managed platform 不支持 Docker-backed Harbor execution。
from pathlib import Path

from osmosis_ai.rollout.backend import HarborBackend

backend = HarborBackend(
    orchestrator=trial_queue,
    task_dir=Path("tasks/my-task"),
    user_code_dir=Path("."),
    workflow="rollouts.my_rollout.main:MyWorkflow",
    grader="rollouts.my_rollout.main:MyGrader",
)
关键 constructor fields：
ParameterDescription
orchestrator用于运行 trials 的 Harbor TrialQueue
task_dir用于构建 Harbor environment 的 task directory
user_code_dir包含 rollout code、会复制进 Harbor workspace 的目录
workflowAgentWorkflow class 或 import path
workflow_config可选 workflow config class/object import path
grader可选 Grader class 或 import path
grader_config可选 grader config class/object import path
environment_config可选 Harbor environment configuration；面向平台的 Harbor rollouts 应使用 Daytona
prebuild_local_imageSDK 实验中的本地 Docker runtime 选项；managed platform 不支持
cleanup_successful_trials成功 completion 后是否移除 trial artifacts
只有在 SDK harness 中显式使用本地 Docker runtime 时，HarborBackend 才会调用 Docker shell 命令。当前 managed Osmosis platform 不支持 Docker-backed Harbor execution；面向平台运行的 Harbor rollouts 请使用 Daytona。

​
Harbor Runtime Notes

使用 HarborBackend 时，workflow 会在 Harbor-managed trial environment 内运行，但它仍然接收标准的 AgentWorkflowContext： 
from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext


class HarborWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        # This code is already running inside the Harbor trial environment.
        ...
不要在 rollout 代码中期待 ctx.environment object。如果 workflow 需要 trial environment 内的文件、tools 或 processes，请把它们打包到 Harbor task environment 中，并在 run() 内通过普通 Python 代码访问。

​
对比

DimensionLocalBackendHarborBackend
Execution environment当前 Python 进程Harbor trial environment
Isolation共享进程和文件系统每个 trial 隔离进程和文件系统
Startup cost最小准备 Harbor task environment
Dependencies当前 Python environmentHarbor task environment
Debugging直接 debugger、stack traces、print outputHarbor logs 和 trial artifacts
Typical userSDK harness author、eval tooling需要隔离的自托管实验

​
选择后端

除非确定需要 Harbor 隔离，否则从 LocalBackend 开始。它更容易调试、moving parts 更少，并且匹配默认本地 starter templates 的 smoke test 行为。
以下情况可以考虑 HarborBackend：
  • 不受信任或混乱的 rollout code 不应共享 host process。
  • Tools 会写文件或 spawn processes，且每次 trial 应该隔离。
  • 每次 rollout execution 都需要可复现 task environment。
  • 您正在 managed Osmosis training path 之外实验 Harbor。

​
与 Eval 和训练的关系

osmosis eval submit 和 osmosis train submit 都在服务端运行 rollout，并不把这些 SDK backends 作为用户可选项暴露。rollout server 在平台启动时，由 entrypoint 构造 backend。这些 SDK 级 backends 只在您把 osmosis-ai 嵌入自己的 harness 时才需要关注。

​
下一步

评估

在训练前提交 evaluation run。

构建 AgentWorkflow

了解 workflows 如何通过受支持 integrations 注册 samples。

Strands 集成

在 Osmosis workflow 中使用 Strands Agents。

OpenAI Agents 集成

在 Osmosis workflow 中使用 OpenAI Agents SDK。