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

> ## Agent Instructions
> Treat this site as the source of truth for public Osmosis behavior.
> Distinguish the web Platform, the open source Python SDK, and the CLI.
> Use documented commands, configuration fields, and public APIs exactly as written; do not infer internal endpoints or services.

# Strands Integration

> Use the Strands agent framework with Osmosis for training

[Strands Agents](https://github.com/strands-agents/sdk-python) is an AWS agent framework for building tool-using agents. Use the Osmosis Strands integration when you want Strands tools, Strands message handling, and a direct migration path from an existing `strands.Agent`.

Install the `strands` extra when a rollout uses this integration: `osmosis-ai[strands]>=0.3.0rc1,<0.4`.

## Integration Objects

| Object                | Purpose                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| `OsmosisStrandsAgent` | Drop-in replacement for Strands `Agent` that registers the sample with the active rollout context |
| `OsmosisRolloutModel` | Placeholder model that resolves to the current Osmosis policy at runtime                          |

`OsmosisStrandsAgent` preserves normal Strands constructor arguments such as `tools`, `system_prompt`, `messages`, and callback handlers.

## Quick Example

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext
from osmosis_ai.rollout.integrations.agents.strands import (
    OsmosisRolloutModel,
    OsmosisStrandsAgent,
)


class StrandsWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisStrandsAgent(
            name="assistant",
            model=OsmosisRolloutModel(params={"temperature": 1.0}),
            messages=ctx.prompt,
            callback_handler=None,
        )
        await agent.invoke_async()
```

<Note>
  `ctx.prompt` is already the ready-to-use input for the current sample. If your dataset row contains `system_prompt` and `user_prompt`, the SDK assembles those fields before your workflow runs.
</Note>

## Tools

Define Strands tools normally with `@tool`, then pass them to `OsmosisStrandsAgent`:

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
from strands import tool
from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext
from osmosis_ai.rollout.integrations.agents.strands import (
    OsmosisRolloutModel,
    OsmosisStrandsAgent,
)


@tool
def search(query: str) -> str:
    """Search for information."""
    return f"Results for: {query}"


class SearchWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisStrandsAgent(
            name="search-agent",
            model=OsmosisRolloutModel(params={"temperature": 1.0}),
            tools=[search],
            system_prompt="You are a helpful assistant.",
            messages=ctx.prompt,
            callback_handler=None,
        )
        await agent.invoke_async()
```

For most tool-using agents, one `invoke_async()` call is enough because Strands handles the model-tool loop internally. Add an outer loop only when you need extra stopping conditions or a hard cap across repeated invocations.

## OsmosisRolloutModel

`OsmosisRolloutModel` does not take a `model_id`. The SDK uses the placeholder model id `openai/osmosis-rollout` at runtime, and Osmosis routes it to the current policy.

Pass LiteLLM sampling options through `params`, matching the Strands `LiteLLMModel` configuration:

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
model = OsmosisRolloutModel(
    params={"temperature": 1.0, "max_tokens": 1024},
)
```

<Warning>
  Construct `OsmosisStrandsAgent` inside `AgentWorkflow.run()` or another path where the execution backend has already installed an active `RolloutContext`. Constructing it at module import time will fail because no rollout context exists yet.
</Warning>

## How Sample Collection Works

When constructed with an `OsmosisRolloutModel`, `OsmosisStrandsAgent` performs these steps:

<Steps>
  <Step title="Read the rollout context">
    It reads the active `RolloutContext` from the current execution scope and raises `RuntimeError` if none is available.
  </Step>

  <Step title="Resolve the model">
    It creates a LiteLLM model connected directly to the rollout-scoped Osmosis chat-completions URL.
  </Step>

  <Step title="Register the agent">
    It registers itself with the rollout context so the backend can collect the Strands message history as a `RolloutSample`.
  </Step>

  <Step title="Initialize Strands Agent">
    It delegates to the normal Strands `Agent` constructor with the resolved model. Tools, prompts, messages, and callbacks pass through unchanged.
  </Step>
</Steps>

The collected `RolloutSample.messages` preserves Strands' native message history for graders. The integration separately performs a best-effort normalization for ATIF persistence; a normalization failure does not replace or discard the native sample. ATIF usage, model, and timestamp fields are included only when the source provides them.

## Complete Example

```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
from operator import add, mul, sub, truediv

from strands import tool
from osmosis_ai.rollout import (
    AgentWorkflow,
    AgentWorkflowContext,
    Grader,
    GraderContext,
)
from osmosis_ai.rollout.integrations.agents.strands import (
    OsmosisRolloutModel,
    OsmosisStrandsAgent,
)


@tool
def calculator(left: float, operator: str, right: float) -> str:
    """Apply +, -, *, or / to two numbers."""
    operations = {"+": add, "-": sub, "*": mul, "/": truediv}
    if operator not in operations:
        raise ValueError("operator must be one of: +, -, *, /")
    return str(operations[operator](left, right))


class MathWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisStrandsAgent(
            name="math-agent",
            model=OsmosisRolloutModel(params={"temperature": 1.0}),
            tools=[calculator],
            system_prompt="You are a math assistant. Use the calculator tool.",
            messages=ctx.prompt,
            callback_handler=None,
        )
        await agent.invoke_async()


def _last_text(sample) -> str:
    if not sample.messages:
        return ""
    content = sample.messages[-1].get("content", "")
    if isinstance(content, str):
        return content
    if isinstance(content, list):
        return next((b["text"] for b in content if isinstance(b, dict) and "text" in b), "")
    return ""


class MathGrader(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 ctx.label and ctx.label.strip() in answer else 0.0
        ctx.set_reward(reward)
```

## Migrating from Strands Agent

If you already have a Strands agent, migrate it in four steps:

<Steps>
  <Step title="Replace the agent import">
    Replace `from strands import Agent` with:

    ```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    from osmosis_ai.rollout.integrations.agents.strands import OsmosisStrandsAgent
    ```
  </Step>

  <Step title="Replace the model">
    Replace your fixed LiteLLM model with an Osmosis placeholder:

    ```python theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/cli.json"]}}
    from osmosis_ai.rollout.integrations.agents.strands import OsmosisRolloutModel

    model = OsmosisRolloutModel(params={"temperature": 1.0})
    ```

    Drop the `model_id`; the training cluster decides which policy to serve.
  </Step>

  <Step title="Swap the agent class">
    Replace `Agent(...)` with `OsmosisStrandsAgent(...)`. Keep tools, system prompt, messages, and callbacks the same.
  </Step>

  <Step title="Wrap in AgentWorkflow">
    Move the agent construction and `await agent.invoke_async()` call into `AgentWorkflow.run()`.
  </Step>
</Steps>

## Strands vs OpenAI Agents

| Choose Strands when                                  | Choose OpenAI Agents when                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------- |
| Your tools are already Strands `@tool` functions     | Your workflow already uses `Runner.run` and OpenAI Agents SDK sessions    |
| You want Strands message traces in `sample.messages` | You want persisted Responses API-style session items in `sample.messages` |
| You are migrating from `strands.Agent`               | You are migrating from OpenAI Agents SDK `Agent`                          |

See [OpenAI Agents Integration](/sdk/integrations/openai-agents) for the OpenAI Agents SDK path.

## Next Steps

<CardGroup cols={2}>
  <Card title="AgentWorkflow" icon="robot" href="/sdk/agent-workflow">
    Review the shared workflow contract.
  </Card>

  <Card title="Grader" icon="scale-balanced" href="/sdk/grader">
    Score the sample produced by your Strands agent.
  </Card>

  <Card title="Evaluation" icon="flask-vial" href="/cli/evaluation">
    Submit an evaluation run for your Strands rollout.
  </Card>

  <Card title="OpenAI Agents Integration" icon="route" href="/sdk/integrations/openai-agents">
    Compare the OpenAI Agents SDK integration.
  </Card>
</CardGroup>