Strands Integration

Strands Agents 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

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()

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.

Tools

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

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:

model = OsmosisRolloutModel(
    params={"temperature": 1.0, "max_tokens": 1024},
)

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.

How Sample Collection Works

When constructed with an OsmosisRolloutModel, OsmosisStrandsAgent performs these steps:

Read the rollout context

It reads the active RolloutContext from the current execution scope and raises RuntimeError if none is available.

Resolve the model

It creates a LiteLLM model connected directly to the rollout-scoped Osmosis chat-completions URL.

It registers itself with the rollout context so the backend can collect the Strands message history as a RolloutSample.

Initialize Strands Agent

It delegates to the normal Strands Agent constructor with the resolved model. Tools, prompts, messages, and callbacks pass through unchanged.

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

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:

Replace the agent import

Replace from strands import Agent with:

from osmosis_ai.rollout.integrations.agents.strands import OsmosisStrandsAgent

Replace the model

Replace your fixed LiteLLM model with an Osmosis placeholder:

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.

Swap the agent class

Replace Agent(...) with OsmosisStrandsAgent(...). Keep tools, system prompt, messages, and callbacks the same.

Wrap in AgentWorkflow

Move the agent construction and await agent.invoke_async() call into AgentWorkflow.run().

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 for the OpenAI Agents SDK path.

Next Steps

AgentWorkflow

Review the shared workflow contract.

Grader

Score the sample produced by your Strands agent.

Evaluation

Submit an evaluation run for your Strands rollout.

OpenAI Agents Integration

Compare the OpenAI Agents SDK integration.

Get started

Core API

Integrations

Execution

Agent tools

Integration Objects

Quick Example

Tools

OsmosisRolloutModel

How Sample Collection Works

Complete Example

Migrating from Strands Agent

Strands vs OpenAI Agents

Next Steps

AgentWorkflow

Grader

Evaluation

OpenAI Agents Integration

​Integration Objects

​Quick Example

​Tools

​OsmosisRolloutModel

​How Sample Collection Works

​Complete Example

​Migrating from Strands Agent

​Strands vs OpenAI Agents

​Next Steps

AgentWorkflow

Grader

Evaluation

OpenAI Agents Integration

Integration Objects

Quick Example

Tools

OsmosisRolloutModel

How Sample Collection Works

Complete Example

Migrating from Strands Agent

Strands vs OpenAI Agents

Next Steps