OpenAI Agents 集成

Osmosis SDK 提供面向 OpenAI Agents SDK 的 integration。如果 rollout 使用 Agent、Runner.run、sessions、tools、handoffs 或其他 OpenAI Agents SDK primitives，请安装 openai-agents extra（osmosis-ai[openai-agents]>=0.3.0rc1,<0.4）。该集成有三个主要对象：

对象	用途
`OsmosisAgent`	OpenAI Agents SDK `Agent` 的直接替代品，会把 `OsmosisRolloutModel` 绑定到活跃的 rollout context
`OsmosisRolloutModel`	占位 policy model，`OsmosisAgent` 会将其替换为活跃 rollout model
`OsmosisMemorySession`	In-memory session，用来记录 runner conversation，并将其作为 rollout sample 暴露给 grader

快速示例

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

使用 OsmosisRolloutModel 时，请始终传入一个 OsmosisMemorySession。Session 会持久化 grader 将读取的 conversation。请在 AgentWorkflow.run() 内构造它，使其成为 active RolloutContext 的唯一 sample source。

工作原理

在 run 内构造 agent

OsmosisAgent 会检查 model 参数是否为 OsmosisRolloutModel。如果是，它会把占位符替换为绑定到活跃 RolloutContext 的 OsmosisLitellmModel。

创建 memory session

OsmosisMemorySession 会在当前 RolloutContext 上将自身注册为唯一 sample source。

运行 OpenAI agent

Runner.run() 通过 get_items() 和 add_items() 与 session 交互。Session 会以 canonical Responses API shape 存储持久化的 OpenAI Agents SDK items。

路由策略调用

解析后的 model 会直接向 rollout-scoped Osmosis chat-completions URL 发送请求。

收集 sample

run() 完成后，backend 会向 rollout context 请求其 sample。Session 会返回一个包含 runner 持久化 conversation 的 RolloutSample。

完整示例

此示例使用 OpenAI Agents SDK tool，并使用 grader 从 session-backed sample 中读取最后一条 assistant text。

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 会为 graders 保留 OpenAI Agents SDK session 的 native persisted items。Integration 会另外为 ATIF 执行 best-effort normalization；conversion 失败时 native sample 保持不变。使用 create_rollout_server() 创建的 server 会持久化该 ATIF view，并且只在 source 提供 usage、model 或 timestamp fields 时包含它们。

OsmosisRolloutModel

OsmosisRolloutModel 是占位符。不要直接调用它，也不要在 rollout 代码中传入固定 policy model name。在 workspace templates 中，采样选项放在 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,
    ),
)

运行时，OsmosisAgent 会把该占位符替换为指向活跃 Osmosis rollout endpoint 的 model。

OsmosisRolloutModel 与 Strands integration 的占位符 constructor 不同。OpenAI Agents examples 使用 OsmosisRolloutModel() 和 ModelSettings(...)，而不是 params={...} dict。

每个 Rollout 使用一个 Session

每次使用 OsmosisRolloutModel 的 workflow execution 都必须恰好使用一个 OsmosisMemorySession。

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

请在 run() 内创建 session。在 active rollout context 之外创建的 session 无法在 rollout run 内复用，因为它没有注册到该 context。在同一次 execution 中构造第二个 session 会抛出 ValueError；需要多个 candidate samples 时，请在同一次 run 内使用 handoffs，或配置多次独立 workflow executions。

从 OpenAI Agents SDK 迁移

如果您已有 OpenAI Agents SDK workflow，可以通过四步迁移：

用 OsmosisAgent 替换 Agent

修改 import 和 class：

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

然后构造 OsmosisAgent(...)，而不是 Agent(...)。

替换 policy model

将固定 model string 替换为 OsmosisRolloutModel 占位符：

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

model = OsmosisRolloutModel()

添加 OsmosisMemorySession

在 AgentWorkflow.run() 内创建 session，并传给 Runner.run()：

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

包装到 AgentWorkflow 中

将 runner call 放入 AgentWorkflow.run() 方法。除非 tools、instructions、handoffs 和 agent 行为依赖 out-of-band state，否则保持它们不变。

评估

使用普通 eval 命令：

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

Eval 期间，平台会把 openai/osmosis-rollout 路由到 eval TOML 中 [experiment].model_path 指定的 model。训练期间，Osmosis 会把同一个占位符路由到当前训练中的 policy。

下一步

AgentWorkflow

查看共享的 AgentWorkflow.run(ctx) contract。

Grader

为 OpenAI Agents session sample 编写 reward 逻辑。

评估

在训练前为您的 OpenAI Agents rollout 提交 evaluation run。

开始使用

核心 API

集成

执行

Agent 工具

快速示例

工作原理

完整示例

OsmosisRolloutModel

每个 Rollout 使用一个 Session

从 OpenAI Agents SDK 迁移

评估

下一步

AgentWorkflow

Grader

评估

​快速示例

​工作原理

​完整示例

​OsmosisRolloutModel

​每个 Rollout 使用一个 Session

​从 OpenAI Agents SDK 迁移

​评估

​下一步

AgentWorkflow

Grader

评估

快速示例

工作原理

完整示例

OsmosisRolloutModel

每个 Rollout 使用一个 Session

从 OpenAI Agents SDK 迁移

评估

下一步