OpenAI Agents Integration

The Osmosis SDK provides an integration for the OpenAI Agents SDK. Install the openai-agents extra (osmosis-ai[openai-agents]>=0.3.0rc1,<0.4) when your rollout uses Agent, Runner.run, sessions, tools, handoffs, or other OpenAI Agents SDK primitives. The integration has three main objects:

Object	Purpose
`OsmosisAgent`	Drop-in replacement for OpenAI Agents SDK `Agent` that binds an `OsmosisRolloutModel` to the active rollout context
`OsmosisRolloutModel`	Placeholder policy model that `OsmosisAgent` replaces with the active rollout model
`OsmosisMemorySession`	In-memory session that records the runner conversation and exposes it as a rollout sample for grading

Quick Example

from agents import ModelSettings, Runner
from osmosis_ai.rollout import AgentWorkflow, AgentWorkflowContext
from osmosis_ai.rollout.integrations.agents.openai_agents import (
    OsmosisAgent,
    OsmosisMemorySession,
    OsmosisRolloutModel,
)


class OpenAIWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisAgent(
            name="assistant",
            instructions="Answer the user's request clearly.",
            model=OsmosisRolloutModel(),
            model_settings=ModelSettings(temperature=1.0, max_tokens=4096),
        )
        session = OsmosisMemorySession()
        await Runner.run(
            agent,
            ctx.prompt,
            session=session,
        )

Always pass one OsmosisMemorySession when using OsmosisRolloutModel. The session persists the conversation that your grader will read. Construct it inside AgentWorkflow.run() so it registers as the single sample source for the active RolloutContext.

How It Works

Construct the agent inside run

OsmosisAgent checks whether the model argument is an OsmosisRolloutModel. If so, it replaces the placeholder with an OsmosisLitellmModel bound to the active RolloutContext.

Create a memory session

OsmosisMemorySession registers itself as the single sample source on the current RolloutContext.

Run the OpenAI agent

Runner.run() interacts with the session through get_items() and add_items(). The session stores the persisted OpenAI Agents SDK items in the canonical Responses API shape.

Route policy calls

The resolved model sends requests directly to the rollout-scoped Osmosis chat-completions URL.

Collect the sample

After run() completes, the backend asks the rollout context for its sample. The session returns one RolloutSample containing the runner’s persisted conversation.

Complete Example

This example uses an OpenAI Agents SDK tool and a grader that reads the final assistant text from the session-backed sample.

from agents import ModelSettings, Runner, function_tool
from osmosis_ai.rollout import (
    AgentWorkflow,
    AgentWorkflowContext,
    Grader,
    GraderContext,
)
from osmosis_ai.rollout.integrations.agents.openai_agents import (
    OsmosisAgent,
    OsmosisMemorySession,
    OsmosisRolloutModel,
)


@function_tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b


class MultiplyWorkflow(AgentWorkflow):
    async def run(self, ctx: AgentWorkflowContext) -> None:
        agent = OsmosisAgent(
            name="multiply-agent",
            instructions="Use the multiply tool when arithmetic is required.",
            model=OsmosisRolloutModel(),
            model_settings=ModelSettings(temperature=1.0, max_tokens=4096),
            tools=[multiply],
        )
        session = OsmosisMemorySession()
        await Runner.run(
            agent,
            ctx.prompt,
            session=session,
        )


def _last_text(sample) -> str:
    for item in reversed(sample.messages):
        if item.get("role") != "assistant":
            continue
        content = item.get("content", "")
        if isinstance(content, str):
            return content
        if isinstance(content, list):
            for block in content:
                if isinstance(block, dict):
                    text = block.get("text") or block.get("content")
                    if text:
                        return text
    return ""


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

sample.messages preserves the OpenAI Agents SDK session’s native persisted items for graders. The integration separately performs a best-effort normalization for ATIF; conversion failure leaves the native sample intact. A server created with create_rollout_server() persists that ATIF view, and includes usage, model, or timestamp fields only when the source provides them.

OsmosisRolloutModel

OsmosisRolloutModel is a placeholder. Do not call it directly and do not pass a fixed policy model name into rollout code. In the workspace templates, sampling options live in OpenAI Agents ModelSettings.

from agents import ModelSettings
from osmosis_ai.rollout.integrations.agents.openai_agents import (
    OsmosisAgent,
    OsmosisRolloutModel,
)

agent = OsmosisAgent(
    name="assistant",
    model=OsmosisRolloutModel(),
    model_settings=ModelSettings(
        temperature=1.0,
        top_p=1.0,
        max_tokens=4096,
    ),
)

At runtime, OsmosisAgent replaces the placeholder with a model that points at the active Osmosis rollout endpoint.

OsmosisRolloutModel is different from the Strands integration’s placeholder constructor. For OpenAI Agents examples, use OsmosisRolloutModel() with ModelSettings(...), not a params={...} dict.

One Session per Rollout

Use exactly one OsmosisMemorySession in each workflow execution that uses OsmosisRolloutModel.

session = OsmosisMemorySession()
await Runner.run(agent, ctx.prompt, session=session)

Create the session inside run(). A session created outside the active rollout context cannot be reused inside a rollout run because it was not registered with that context. Constructing a second session in the same execution raises ValueError; use handoffs within the same run, or configure multiple independent workflow executions when you need multiple candidate samples.

Migrating from OpenAI Agents SDK

If you already have an OpenAI Agents SDK workflow, migrate it in four steps:

Replace Agent with OsmosisAgent

Change the import and class:

from osmosis_ai.rollout.integrations.agents.openai_agents import OsmosisAgent

Then construct OsmosisAgent(...) instead of Agent(...).

Replace the policy model

Replace a fixed model string with an OsmosisRolloutModel placeholder:

from osmosis_ai.rollout.integrations.agents.openai_agents import OsmosisRolloutModel

model = OsmosisRolloutModel()

Add an OsmosisMemorySession

Create the session inside AgentWorkflow.run() and pass it to Runner.run():

session = OsmosisMemorySession()
await Runner.run(agent, ctx.prompt, session=session)

Wrap the runner in AgentWorkflow

Put the runner call inside an AgentWorkflow.run() method. Keep your tools, instructions, handoffs, and agent behavior the same unless they depend on out-of-band state.

Evaluation

Use the normal eval command:

osmosis eval submit configs/eval/<rollout-name>.toml

During an evaluation run, the platform routes openai/osmosis-rollout to the model named in [experiment].model_path of the evaluation TOML. During a training run, Osmosis routes the same placeholder to the current training policy.

Next Steps

AgentWorkflow

Review the shared AgentWorkflow.run(ctx) contract.

Grader

Write reward logic for the OpenAI Agents session sample.

Evaluation

Submit an evaluation run for your OpenAI Agents rollout before a training run.

Get started

Core API

Integrations

Execution

Agent tools

Quick Example

How It Works

Complete Example

OsmosisRolloutModel

One Session per Rollout

Migrating from OpenAI Agents SDK

Evaluation

Next Steps

AgentWorkflow

Grader

Evaluation

​Quick Example

​How It Works

​Complete Example

​OsmosisRolloutModel

​One Session per Rollout

​Migrating from OpenAI Agents SDK

​Evaluation

​Next Steps

AgentWorkflow

Grader

Evaluation

Quick Example

How It Works

Complete Example

OsmosisRolloutModel

One Session per Rollout

Migrating from OpenAI Agents SDK

Evaluation

Next Steps