克隆官方模板仓库、实现 Agent 逻辑、连接 Osmosis 训练集群 —— 这是搭建 Remote Rollout 服务器的最快路径。
从模板创建您的项目
创建仓库
访问我们的官方模板仓库：
osmosis-remote-rollout-example 点击右上角的 “Use this template” 按钮，基于此模板创建您自己的仓库。
此模板包含完整的项目结构、示例代码和测试数据，让您可以立即开始开发。
克隆并安装依赖
克隆您新创建的仓库并安装依赖： 如果您没有安装 uv，也可以使用 pip： pip install osmosis-ai[server]
登录 Osmosis Platform
通过 Osmosis Platform 进行身份验证以启用服务器注册： 这将打开浏览器进行身份验证。登录后，您的凭据将保存到 ~/.config/osmosis/credentials.json。 您可以使用以下命令验证登录状态： 服务器使用您的凭据向 Osmosis Platform 注册，使训练系统能够发现并连接到您的服务器。
运行服务器
使用 SDK CLI 启动服务器： uv run osmosis serve -m server:agent_loop
您应该会看到类似以下的输出： INFO: Osmosis RolloutServer starting... INFO: Agent: calculator INFO: Tools: 4 INFO: Uvicorn running on http://0.0.0.0:9000
模板结构 模板仓库包含以下关键组件：
my-rollout-server/ ├── server.py # Agent Loop 主文件 ├── tools.py # 工具定义和执行逻辑 ├── rewards.py # 奖励计算（可选） ├── test_data.jsonl # 测试数据集 ├── pyproject.toml # 项目依赖 └── README.md # 文档
核心概念：Agent Loop Agent Loop 是 Remote Rollout 的核心。它继承自 RolloutAgentLoop 并实现两个必需的方法：
from osmosis_ai.rollout import RolloutAgentLoop, RolloutContext, RolloutResult, RolloutRequest, create_app class CalculatorAgent ( RolloutAgentLoop ): name = "calculator" def get_tools ( self , request : RolloutRequest): """Return available tools.""" return CALCULATOR_TOOLS # Defined in tools.py async def run ( self , ctx : RolloutContext) -> RolloutResult: """Execute the agent loop.""" ... # See template repo for full implementation agent_loop = CalculatorAgent() app = create_app(agent_loop)
查看 Agent 循环指南 以获取包含工具执行、奖励计算和高级模式的完整实现参考。
工具定义 工具使用 OpenAI function calling 格式定义：
CALCULATOR_TOOLS = [ { "type" : "function" , "function" : { "name" : "multiply" , "description" : "Multiply two numbers" , "parameters" : { "type" : "object" , "properties" : { "a" : { "type" : "number" , "description" : "First number" }, "b" : { "type" : "number" , "description" : "Second number" } }, "required" : [ "a" , "b" ] } } } ]
验证与测试 验证 Agent 配置 在运行之前，使用 CLI 验证您的 Agent 实现：
uv run osmosis validate -m server:agent_loop
预期输出：
✓ Agent loop validated successfully Name: calculator Tools: 4 (add, subtract, multiply, divide)
本地测试 模板包含一个 test_data.jsonl 测试数据集。设置您的 API 密钥并运行测试：
export OPENAI_API_KEY = "your-key-here" # Run batch tests uv run osmosis test -m server:agent_loop -d test_data.jsonl # Limit number of tests uv run osmosis test -m server:agent_loop -d test_data.jsonl --limit 10 # Use a different model uv run osmosis test -m server:agent_loop -d test_data.jsonl --model anthropic/claude-sonnet-4-5
有关逐步调试和高级测试选项，请参阅测试模式 。
开发技巧 启用热重载 在开发过程中启用自动重载，当代码更改时自动重启服务器：
uv run osmosis serve -m server:agent_loop --reload
启用调试日志 将执行轨迹写入文件以便调试：
uv run osmosis serve -m server:agent_loop --log ./logs
日志文件结构：
logs/ └── {timestamp}/ ├── rollout-abc123.jsonl └── rollout-def456.jsonl
本地模式（无需登录） 跳过登录和平台注册，用于本地开发：
uv run osmosis serve -m server:agent_loop --local
本地模式会禁用 API 密钥认证和平台注册。这仅用于开发环境，不应在生产环境中使用。
下一步
Agent 循环指南 学习高级 Agent 循环模式
