> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osmosis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 概览

> 构建用于在 Osmosis 上训练的自定义 agent workflows 和 graders

**Rollout** 是 Osmosis 在强化学习训练期间评估 agent 行为的单元。它把负责为 prompt 生成一个或多个 samples 的 `AgentWorkflow`，和负责把这些 samples 转换成 reward signals 的 `Grader` 组合在一起。

Rollout 是 workspace 中的普通 Python 代码。它可以是简单的单次 LLM 调用 workflow，也可以是使用 Strands Agents 的工具型 agent、OpenAI Agents SDK workflow，或者您通过开源 `osmosis-ai` SDK 自行驱动的自定义 harness。

## 训练循环

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

<Steps>
  <Step title="选择数据集行">
    训练集群从数据集中选择一行，并将其中的 prompt 字段发送给您的 `AgentWorkflow`。常见数据集包含 `system_prompt`、`user_prompt` 和 `ground_truth`。
  </Step>

  <Step title="运行 AgentWorkflow">
    您的 workflow 接收 `AgentWorkflowContext`，通过 Osmosis 支持的 agent integration 调用当前策略，使用您提供的工具，并记录 rollout samples。
  </Step>

  <Step title="给 samples 打分">
    您的 `Grader` 接收收集到的 samples，以及该行的参考答案（`ground_truth`，以 `ctx.label` 暴露），并为每个 sample 分配数值 reward。
  </Step>

  <Step title="更新模型">
    reward 信号驱动训练更新，让策略向在您的任务上获得更高 reward 的行为移动。
  </Step>
</Steps>

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

## Rollout 中的文件

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
repository/
├── rollouts/
│   └── my-rollout/
│       ├── main.py
│       └── pyproject.toml
├── configs/
│   ├── eval/
│   │   └── my-rollout.toml
│   └── training/
│       └── my-rollout.toml
└── data/
    └── test.jsonl
```

| File                                 | Purpose                                                                       |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| `rollouts/my-rollout/main.py`        | 定义恰好一个具体 `AgentWorkflow` 和一个具体 `Grader`，同时用于 training 和 evaluation            |
| `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 代码版本和训练设置                                           |

<Note>
  `osmosis train submit` 和 `osmosis eval submit` 都会从 entrypoint 文件中发现 rollout classes，并在服务端运行 rollout。Helper classes、tools 和 config objects 可以放在任意位置，但请暴露平台应验证的具体 `AgentWorkflow` 和 `Grader` classes。
</Note>

## 核心抽象

| Abstraction       | What it does                                                | Where to learn more                                                                                             |
| ----------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `AgentWorkflow`   | 定义 agent 行为：prompt 处理、模型调用、工具使用和 sample 创建                  | [构建 AgentWorkflow](/zh/cli/rollout/agent-workflows)                                                             |
| `Grader`          | 定义 reward 逻辑：精确匹配、程序化检查、LLM-as-judge 或自定义评分                 | [构建 Graders](/zh/cli/rollout/graders)                                                                           |
| Agent integration | 将您的 agent 框架连接到活跃的 Osmosis rollout context                  | [Strands 集成](/zh/cli/rollout/strands-integration)、[OpenAI Agents 集成](/zh/cli/rollout/openai-agents-integration) |
| Execution backend | 在您自行驱动 SDK 时，以进程内或 Harbor-managed environment 运行 rollout 代码 | [执行后端](/zh/cli/rollout/execution-backends)                                                                      |

## 选择 Agent 框架

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

<CardGroup cols={2}>
  <Card title="Strands Agents" icon="link" href="/zh/cli/rollout/strands-integration">
    如果您需要 Strands tools、Strands message handling，或想从已有 Strands `Agent` 直接迁移，请使用 `OsmosisStrandsAgent`。
  </Card>

  <Card title="OpenAI Agents" icon="route" href="/zh/cli/rollout/openai-agents-integration">
    如果您的 workflow 已经使用 OpenAI Agents SDK、`Runner.run`、sessions、handoffs 或 OpenAI 风格的 tool orchestration，请使用 `OsmosisAgent`。
  </Card>
</CardGroup>

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

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

## 选择执行后端

如果您使用 `osmosis eval submit` 或 `osmosis train submit`，平台会管理执行，您不需要通过 CLI 选择后端。entrypoint 决定 rollout server 启动时构造哪个 SDK backend；starter templates 默认使用 `LocalBackend`，除非您选择 Harbor template。

<Warning>
  如果您基于 Harbor template 做平台训练，请使用 Daytona-backed Harbor 路径；当前 managed platform 不支持 Docker-backed Harbor execution。
</Warning>

只有在把开源 SDK 嵌入自己的 harness 时，才需要选择 backend：

| Backend         | Use when                                                                            |
| --------------- | ----------------------------------------------------------------------------------- |
| `LocalBackend`  | 您需要快速进程内执行、容易调试，并且不依赖 Docker                                                        |
| `HarborBackend` | 您需要 Harbor-managed per-trial isolation，并且使用 managed platform 所要求的 Daytona-backed 路径 |

SDK 级 examples 和 tradeoffs 请参见 [执行后端](/zh/cli/rollout/execution-backends)。

## 从模板开始

如果您已经有任务或数据集，请从 [创建自己的 Rollout](/zh/platform/create-your-own-rollout) 开始。Platform-created workspace repositories 会包含 project-local Agent Skills，用来引导 AI coding agent 完成 dataset planning、rollout creation、evaluation run、debugging 和 training run readiness。

列出可用 starter templates：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis template list
```

应用 Strands starter：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis template apply multiply-local-strands
```

或应用 OpenAI Agents starter：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
osmosis template apply multiply-local-openai
```

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

## 进入训练的路径

Rollout 创建后，按以下路径推进：

<Steps>
  <Step title="实现 workflow">
    把策略调用放在 `OsmosisStrandsAgent` 或 `OsmosisAgent` 后面，从 `ctx.prompt` 传入数据集 prompt，并把 task-specific tools 保持在 rollout 附近。
  </Step>

  <Step title="实现 grader">
    为 `ctx.samples` 中的每个 sample 打分。能用确定性 grader 时先从确定性逻辑开始；只有在任务主观时再加入 LLM-as-judge 逻辑。
  </Step>

  <Step title="Commit 并同步">
    将 rollout 修改 push 到默认分支，让 [Git Sync](/zh/cli/workspace/git-sync) 发布 evaluation run 和 training run 使用的代码版本。
  </Step>

  <Step title="提交 evaluation run">
    运行 `osmosis eval submit configs/eval/my-rollout.toml`，并用 `osmosis eval info <name>` 查看 rewards、failures 和 per-row 结果。参见 [评估](/zh/cli/rollout/eval)。
  </Step>

  <Step title="提交训练">
    运行 `osmosis train submit configs/training/my-rollout.toml`。提交行为请参见 [训练任务](/zh/platform/training-runs)。
  </Step>
</Steps>

## 下一步

<CardGroup cols={2}>
  <Card title="创建自己的 Rollout" icon="wand-magic-sparkles" href="/zh/platform/create-your-own-rollout">
    使用 project-local Agent Skills 和 evaluation run gates 创建 task-specific rollout。
  </Card>

  <Card title="构建 AgentWorkflow" icon="robot" href="/zh/cli/rollout/agent-workflows">
    学习 `AgentWorkflow.run(ctx)` contract 和常见实现模式。
  </Card>

  <Card title="构建 Graders" icon="scale-balanced" href="/zh/cli/rollout/graders">
    定义可驱动训练的 reward signals。
  </Card>

  <Card title="Strands 集成" icon="link" href="/zh/cli/rollout/strands-integration">
    使用 AWS Strands Agents 构建工具型 rollouts。
  </Card>

  <Card title="OpenAI Agents 集成" icon="route" href="/zh/cli/rollout/openai-agents-integration">
    使用 OpenAI Agents SDK 构建 rollouts。
  </Card>
</CardGroup>