Osmosis Python SDK 概览

开源 osmosis-ai SDK 用 Python 定义和运行 agent 行为；同一 package 中的 osmosis CLI 用于提交和检查 runs；Osmosis Platform 管理 datasets、evaluation 和 training。它们一起交付，但各自承担不同职责。一个 rollout definition 会显式连接 AgentWorkflow、可选的 Grader、它们的 configs 和 execution backend。一次 rollout execution 会针对一个 dataset prompt 运行该 definition 一次，并产生至多一个 rollout sample：agent 的 framework-native message history，以及可选的 reward 和 metrics。

训练循环

Osmosis 上的训练会重复运行同一个四段循环：

选择数据集行

训练集群从数据集中选择一行，并将其中的 prompt 字段发送给您的 AgentWorkflow。常见数据集包含 system_prompt、user_prompt 和 ground_truth。

运行 AgentWorkflow

您的 workflow 接收 AgentWorkflowContext，通过 Osmosis 支持的 agent integration 调用当前策略，使用您提供的工具，并记录一个 rollout sample。

给 sample 打分

您的 Grader 接收 sample，以及该行的参考答案（ground_truth，以 ctx.label 暴露），并分配一个数值 reward。

更新模型

reward 信号驱动训练更新，让策略向在您的任务上获得更高 reward 的行为移动。

这就是 rollout 代码必须通过 Osmosis integrations 路由模型调用的原因。训练集群需要通过 rollout-scoped endpoint 服务当前策略、收集 traces，并把 reward 连接回产出它的 sample。

Rollout 中的文件

每个 rollout 都位于 rollouts/ 下，并由 evaluation 和 training configs 引用：

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

文件	用途
`rollouts/my-rollout/main.py`	定义 workflow 和 grader classes，将选中的 classes 显式连接到 backend，并暴露 server app
`rollouts/my-rollout/pyproject.toml`	声明 rollout-local Python dependencies
`configs/eval/my-rollout.toml`	将 evaluation run 指向 rollout、entrypoint、evaluation policy 模型和 platform dataset
`configs/training/my-rollout.toml`	将 training run 指向 rollout 代码版本和训练设置

Submit preflight 会校验 rollout 路径，然后导入配置的 entrypoint 一次，使 import-time wiring errors 暴露出来并让 submit 失败。该导入是 best-effort 的：当本地环境不满足 rollout 声明的 dependencies，或导入抛出 ModuleNotFoundError 时，CLI 只会发出警告并继续提交，由平台在安装这些 dependencies 后校验 entrypoint。Preflight 不会扫描 module namespace。多个 workflow 或 grader classes 可以共存；backend constructor 会选择实际运行的 classes 和 config objects。

该导入会在您本地的 CLI 进程中执行 rollout package 和 entrypoint，可访问您的文件系统、环境变量和凭据。请只提交您信任的 workspace 代码。

核心抽象

抽象	作用	了解更多
`AgentWorkflow`	定义 agent 行为：prompt 处理、模型调用、工具使用和 sample 创建	AgentWorkflow
`Grader`	定义 reward 逻辑：精确匹配、程序化检查、LLM-as-judge 或自定义评分	Grader
Agent integration	将您的 agent 框架连接到活跃的 Osmosis rollout context	Strands 集成、OpenAI Agents 集成
Execution backend	以进程内或 Harbor-managed environment 运行 rollout 代码	执行后端

选择 Agent 框架

多数 rollout 作者会从内置 agent integrations 之一开始：

Strands Agents

如果您需要 Strands tools、Strands message handling，或想从已有 Strands Agent 直接迁移，请使用 OsmosisStrandsAgent。

OpenAI Agents

如果您的 workflow 已经使用 OpenAI Agents SDK、Runner.run、sessions、handoffs 或 OpenAI 风格的 tool orchestration，请使用 OsmosisAgent。

两个 integrations 都使用 OsmosisRolloutModel 占位符。您不会在 rollout 代码中硬编码训练模型；Osmosis 会在运行时把占位符解析为当前策略。

不要在 AgentWorkflow.run() 中用固定模型（例如 openai/gpt-5.2）直接调用 provider SDK。直接调用会绕过活跃的 RolloutContext，平台就无法路由策略请求、收集 sample，或把 reward 连接到正确的 rollout。

选择执行后端

如果您使用 osmosis eval submit 或 osmosis train submit，则不需要通过 CLI 选择 backend。Platform 启动 rollout server 时，rollout entrypoint 会构造它；starter templates 默认使用 LocalBackend，除非您选择 Harbor template。

如果您基于 Harbor template 构建，请在 SkyPilot Sandboxes 中运行 trials。Osmosis Platform 不支持 Docker-backed Harbor execution。

在该 entrypoint 或自托管 SDK harness 中选择 backend 路径：

路径	适用场景
`LocalBackend`	一个 workflow 应在当前 Python 进程中处理变化的 dataset prompts
`HarborBackend` template mode	同一个 prompt-driven workflow 需要一个可复用的隔离 task environment
`HarborBackend` dataset mode	已有 Harbor tasks 应保留自己的 instructions、environments 和 verifiers

完整决策指南请参见执行后端。

正在把 SDK harness 从 v0.2 升级吗？LocalBackend 保留原 constructor，而 v0.3 会用之前名为 HarborBackendV2 的实现取代 pre-v0.3 HarborBackend。修改 dependencies 前，请先阅读 SDK v0.2 → v0.3 迁移指南。

从模板开始

如果您已经有任务或数据集，请从自定义 Rollout 指南开始。Platform-created workspace repositories 会包含 project-local Agent Skills，用来引导 AI coding agent 完成 dataset planning、rollout creation、evaluation run、debugging 和 training run readiness。请先安装 package，参见 SDK 安装，并在已 clone 的 workspace directory 内运行 osmosis template apply。列出可用 starter templates：

osmosis template list

应用 Strands starter：

osmosis template apply multiply-local-strands

或应用 OpenAI Agents starter：

osmosis template apply multiply-local-openai

Templates 来自平台 workspace template repository。它们会在 rollouts/ 下写入 rollout 代码，并写入匹配的 evaluation 和 training configs，是了解预期文件布局、依赖声明和端到端 workflow 的最快方式。

下一步

自定义 Rollout 指南

使用 project-local Agent Skills 和 evaluation run gates 创建 task-specific rollout。

AgentWorkflow

学习 AgentWorkflow.run(ctx) contract 和常见实现模式。

Grader

定义可驱动训练的 reward signals。

Strands 集成

使用 AWS Strands Agents 构建工具型 rollouts。

OpenAI Agents 集成

使用 OpenAI Agents SDK 构建 rollouts。

开始使用

核心 API

集成

执行

Agent 工具

训练循环

Rollout 中的文件

核心抽象

选择 Agent 框架

Strands Agents

OpenAI Agents

选择执行后端

从模板开始

下一步

自定义 Rollout 指南

AgentWorkflow

Grader

Strands 集成

OpenAI Agents 集成

​训练循环

​Rollout 中的文件

​核心抽象

​选择 Agent 框架

Strands Agents

OpenAI Agents

​选择执行后端

​从模板开始

​下一步

自定义 Rollout 指南

AgentWorkflow

Grader

Strands 集成

OpenAI Agents 集成

训练循环

Rollout 中的文件

核心抽象

选择 Agent 框架

选择执行后端

从模板开始

下一步