> ## 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.

# Overview

> Build custom agent workflows and graders for training on Osmosis

A **rollout** is the unit of agent behavior that Osmosis evaluates during reinforcement learning training. It combines an `AgentWorkflow`, which produces one or more samples for a prompt, with a `Grader`, which turns those samples into reward signals.

Rollouts are normal Python code in your workspace. They can use a simple single-call LLM workflow, a tool-using agent built with Strands Agents, an OpenAI Agents SDK workflow, or a custom harness that you drive through the open source `osmosis-ai` SDK.

## Training Loop

Training on Osmosis repeatedly runs the same four-part loop:

<Steps>
  <Step title="Select a dataset row">
    The training cluster selects one row from your dataset and sends its prompt fields to your `AgentWorkflow`. Common datasets contain `system_prompt`, `user_prompt`, and `ground_truth`.
  </Step>

  <Step title="Run the AgentWorkflow">
    Your workflow receives an `AgentWorkflowContext`, calls the current policy through an Osmosis-supported agent integration, uses any tools you provide, and records rollout samples.
  </Step>

  <Step title="Grade the samples">
    Your `Grader` receives the collected samples plus the row's reference answer (`ground_truth`, exposed as `ctx.label`) and assigns a numerical reward to each sample.
  </Step>

  <Step title="Update the model">
    The reward signal drives the training update, moving the policy toward behavior that receives higher rewards on your task.
  </Step>
</Steps>

This loop is why rollout code must route model calls through Osmosis integrations. The training cluster needs to serve the current policy, attach rollout metadata, collect traces, and connect rewards back to the samples that produced them.

## Files in a Rollout

Each rollout lives under `rollouts/` and is referenced by evaluation and 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`        | Defines exactly one concrete `AgentWorkflow` and one concrete `Grader` for training and evaluation  |
| `rollouts/my-rollout/pyproject.toml` | Declares rollout-local Python dependencies                                                          |
| `configs/eval/my-rollout.toml`       | Points the evaluation run at the rollout, entrypoint, evaluation policy model, and platform dataset |
| `configs/training/my-rollout.toml`   | Points the training run at the rollout code version and training settings                           |

<Note>
  `osmosis train submit` and `osmosis eval submit` both discover rollout classes from the entrypoint file and run the rollout server-side. Keep helper classes, tools, and config objects wherever you like, but expose the concrete `AgentWorkflow` and `Grader` classes that the platform should validate.
</Note>

## Core Abstractions

| Abstraction       | What it does                                                                                    | Where to learn more                                                                                                          |
| ----------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `AgentWorkflow`   | Defines agent behavior: prompt handling, model calls, tool use, and sample creation             | [Building AgentWorkflows](/cli/rollout/agent-workflows)                                                                      |
| `Grader`          | Defines reward logic: exact matching, programmatic checks, LLM-as-judge, or custom scoring      | [Building Graders](/cli/rollout/graders)                                                                                     |
| Agent integration | Connects your agent framework to the active Osmosis rollout context                             | [Strands Integration](/cli/rollout/strands-integration), [OpenAI Agents Integration](/cli/rollout/openai-agents-integration) |
| Execution backend | Runs rollout code in-process or in a Harbor-managed environment when you drive the SDK yourself | [Execution Backends](/cli/rollout/execution-backends)                                                                        |

## Choose an Agent Framework

Most rollout authors start with one of the built-in agent integrations:

<CardGroup cols={2}>
  <Card title="Strands Agents" icon="link" href="/cli/rollout/strands-integration">
    Use `OsmosisStrandsAgent` when you want Strands tools, Strands message handling, and a direct migration path from an existing Strands `Agent`.
  </Card>

  <Card title="OpenAI Agents" icon="route" href="/cli/rollout/openai-agents-integration">
    Use `OsmosisAgent` when your workflow already uses the OpenAI Agents SDK, `Runner.run`, sessions, handoffs, or OpenAI-style tool orchestration.
  </Card>
</CardGroup>

Both integrations use an `OsmosisRolloutModel` placeholder. You do not hard-code the training model inside rollout code; Osmosis resolves the placeholder to the current policy at runtime.

<Warning>
  Do not call provider SDKs directly from `AgentWorkflow.run()` with a fixed model such as `openai/gpt-5.2`. Direct calls bypass the active `RolloutContext`, so the platform cannot route policy requests, collect samples, or connect rewards to the right rollout.
</Warning>

## Choose an Execution Backend

If you use `osmosis eval submit` or `osmosis train submit`, the platform manages execution and you do not choose a backend from the CLI. The entrypoint decides which SDK backend to construct when the rollout server starts, and the starter templates use `LocalBackend` unless you choose the Harbor template.

<Warning>
  If you build on the Harbor template for platform training, use the Daytona-backed Harbor path; the managed platform does not currently support Docker-backed Harbor execution.
</Warning>

You only choose a backend explicitly when embedding the open source SDK in your own harness:

| Backend         | Use when                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------ |
| `LocalBackend`  | You want fast in-process execution, easy debugging, and no Docker dependency                                       |
| `HarborBackend` | You need Harbor-managed per-trial isolation and are using the Daytona-backed path required by the managed platform |

See [Execution Backends](/cli/rollout/execution-backends) for SDK-level examples and tradeoffs.

## Start from a Template

If you already have a task or dataset, start with [Create Your Own Rollout](/platform/create-your-own-rollout). Platform-created workspace repositories include project-local Agent Skills that guide an AI coding agent through dataset planning, rollout creation, evaluation runs, debugging, and training run readiness.

List available starter templates:

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

Apply a Strands starter:

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

Or apply an OpenAI Agents starter:

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

Templates are copied from the platform workspace template repository. They write rollout code under `rollouts/` plus matching evaluation and training configs, and are the quickest way to see the expected file layout, dependency declaration, and end-to-end workflow.

## Path to Training

Once your rollout exists, use this path:

<Steps>
  <Step title="Implement the workflow">
    Put policy calls behind `OsmosisStrandsAgent` or `OsmosisAgent`, pass the dataset prompt from `ctx.prompt`, and keep any task-specific tools close to the rollout.
  </Step>

  <Step title="Implement the grader">
    Score every sample in `ctx.samples`. Start with a deterministic grader when possible, then add LLM-as-judge logic only when the task is subjective.
  </Step>

  <Step title="Commit and sync">
    Push rollout changes to the default branch so [Git Sync](/cli/workspace/git-sync) publishes the code version used by evaluation runs and training runs.
  </Step>

  <Step title="Submit an evaluation run">
    Run `osmosis eval submit configs/eval/my-rollout.toml` and inspect rewards, failures, and per-row results with `osmosis eval info <name>`. See [Evaluation](/cli/rollout/eval).
  </Step>

  <Step title="Submit training">
    Run `osmosis train submit configs/training/my-rollout.toml`. See [Training Runs](/platform/training-runs) for submission behavior.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Your Own Rollout" icon="wand-magic-sparkles" href="/platform/create-your-own-rollout">
    Use project-local Agent Skills to create a task-specific rollout with evaluation run gates.
  </Card>

  <Card title="Building AgentWorkflows" icon="robot" href="/cli/rollout/agent-workflows">
    Learn the `AgentWorkflow.run(ctx)` contract and common implementation patterns.
  </Card>

  <Card title="Building Graders" icon="scale-balanced" href="/cli/rollout/graders">
    Define reward signals that can drive training.
  </Card>

  <Card title="Strands Integration" icon="link" href="/cli/rollout/strands-integration">
    Build tool-using rollouts with AWS Strands Agents.
  </Card>

  <Card title="OpenAI Agents Integration" icon="route" href="/cli/rollout/openai-agents-integration">
    Build rollouts with the OpenAI Agents SDK.
  </Card>
</CardGroup>