环境、基准测试与数据生成

Hermes Agent 包含一个完整的环境框架，将它的工具调用能力与 Atropos 强化学习（RL）训练框架相连接。这支持三种工作流：

强化学习训练 —— 使用 GRPO 在多轮代理任务上训练语言模型
基准测试 —— 在标准化的代理基准上评估模型表现
数据生成 —— 从代理回放中生成 SFT 训练数据

这三者共享同一个核心：一个定义任务、运行代理循环并评分输出的 环境类。

仓库环境 vs RL 训练工具

此处文档所描述的 Python 环境框架位于仓库的 environments/ 目录下，是 Hermes/Atropos 集成的实现级 API。它与面向用户的 rl_* 工具是分开的——后者作为远程强化学习训练工作流的编排界面。

快速链接

想运行基准测试？ 跳转至可用基准测试
想使用 RL 进行训练？ 参考 RL 训练工具获取基于代理的接口，或参考运行环境手动执行
想创建新环境？ 参考创建环境

架构设计

该环境系统基于三层继承链构建：

BaseEnv（Atropos）

来自 atroposlib 的基础层，提供以下功能：

服务器管理 —— 连接 OpenAI 兼容 API（VLLM、SGLang、OpenRouter）
工作节点调度 —— 并行回放协调
Wandb 集成 —— 指标记录与回放可视化
CLI 接口 —— 三个子命令：serve、process、evaluate
评估日志 —— evaluate_log() 将结果保存为 JSON + JSONL 格式

HermesAgentBaseEnv

Hermes Agent 层（environments/hermes_base_env.py）。新增功能包括：

终端后端配置 —— 设置 TERMINAL_ENV 以实现沙箱化执行（本地、Docker、Modal、Daytona、SSH、Singularity）
工具解析 —— _resolve_tools_for_group() 调用 hermes-agent 的 get_tool_definitions() 来根据启用/禁用的工具集获取正确的工具 Schema
代理循环集成 —— collect_trajectory() 运行 HermesAgentLoop 并对结果进行评分
双阶段操作 —— 第一阶段（OpenAI 服务器）用于评估/SFT，第二阶段（VLLM ManagedServer）用于完整 RL（带 logprobs）
异步安全补丁 —— 对 Modal 后端进行猴子补丁，使其可在 Atropos 的事件循环内正常工作

具体环境

你的环境需继承自 HermesAgentBaseEnv，并实现以下五个方法：

方法	用途
`setup()`	加载数据集，初始化状态
`get_next_item()`	返回下一项用于回放
`format_prompt(item)`	将一项转换为用户消息
`compute_reward(item, result, ctx)`	对回放结果进行评分（0.0–1.0）
`evaluate()`	定期评估逻辑

核心组件

代理循环

HermesAgentLoop（environments/agent_loop.py）是可复用的多轮代理引擎。其运行方式与 hermes-agent 主循环一致：

通过 server.chat_completion() 将消息和工具 Schema 发送到 API
若响应包含 tool_calls，则通过 handle_function_call() 分派每个工具调用
将工具结果追加到对话中，返回步骤 1
若无 tool_calls，则代理完成

工具调用在线程池（ThreadPoolExecutor(128)）中执行，以避免异步后端（如 Modal、Docker）在 Atropos 事件循环中死锁。

返回一个 AgentResult：

@dataclass
class AgentResult:
    messages: List[Dict[str, Any]]       # Full conversation history
    turns_used: int                       # Number of LLM calls made
    finished_naturally: bool              # True if model stopped on its own
    reasoning_per_turn: List[Optional[str]]  # Extracted reasoning content
    tool_errors: List[ToolError]          # Errors encountered during tool dispatch
    managed_state: Optional[Dict]         # VLLM ManagedServer state (Phase 2)

工具上下文

ToolContext（environments/tool_context.py）使奖励函数能够直接访问 与模型回放期间相同的沙箱。task_id 的作用域意味着所有状态（文件、进程、浏览器标签页等）均被保留。

async def compute_reward(self, item, result, ctx: ToolContext):
    # Run tests in the model's terminal sandbox
    test = ctx.terminal("pytest -v")
    if test["exit_code"] == 0:
        return 1.0

    # Check if a file was created
    content = ctx.read_file("/workspace/solution.py")
    if content.get("content"):
        return 0.5

    # Download files for local verification
    ctx.download_file("/remote/output.bin", "/local/output.bin")
    return 0.0

可用方法：

类别	方法
终端	`terminal(command, timeout)`
文件	`read_file(path)`、`write_file(path, content)`、`search(query, path)`
传输	`upload_file()`、`upload_dir()`、`download_file()`、`download_dir()`
网页	`web_search(query)`、`web_extract(urls)`
浏览器	`browser_navigate(url)`、`browser_snapshot()`
通用	`call_tool(name, args)` —— 任意 hermes-agent 工具的“逃生舱”
清理	`cleanup()` —— 释放所有资源

工具调用解析器

对于 第二阶段（VLLM ManagedServer），服务器返回原始文本而非结构化工具调用。客户端的解析器（位于 environments/tool_call_parsers/）从原始输出中提取 tool_calls：

from environments.tool_call_parsers import get_parser

parser = get_parser("hermes")  # or "mistral", "llama3_json", "qwen", "deepseek_v3", etc.
content, tool_calls = parser.parse(raw_model_output)

可用解析器：hermes、mistral、llama3_json、qwen、qwen3_coder、deepseek_v3、deepseek_v3_1、kimi_k2、longcat、glm45、glm47。

在第一阶段（OpenAI 服务器类型）中，无需解析器——服务器原生处理工具调用解析。

可用基准测试

TerminalBench2

89 个具有挑战性的终端任务，每个任务配有独立的 Docker 沙箱环境。


测试内容	单任务编程/系统管理能力
评分方式	二元通过/失败（通过测试套件验证）
沙箱	Modal 云沙箱（每任务专用 Docker 镜像）
工具	`terminal` + `file`
任务数量	跨多个类别共 89 项任务
成本	完整评估约 $50–200（并行执行）
耗时	约 2–4 小时

python environments/benchmarks/terminalbench_2/terminalbench2_env.py evaluate \
    --config environments/benchmarks/terminalbench_2/default.yaml

# Run specific tasks
python environments/benchmarks/terminalbench_2/terminalbench2_env.py evaluate \
    --config environments/benchmarks/terminalbench_2/default.yaml \
    --env.task_filter fix-git,git-multibranch

数据集：NousResearch/terminal-bench-2 on HuggingFace。

TBLite（OpenThoughts 终端基准精简版）

100 个难度校准的任务 —— TerminalBench2 的快速替代品。


测试内容	与 TB2 相同（编程/系统管理），具备难度分级
评分方式	二元通过/失败
沙箱	Modal 云沙箱
工具	`terminal` + `file`
任务数量	100 项：简单（40）、中等（26）、困难（26）、极端（8）
相关性	与完整 TB2 的相关系数 r=0.911
速度	比 TB2 快 2.6–8 倍

python environments/benchmarks/tblite/tblite_env.py evaluate \
    --config environments/benchmarks/tblite/default.yaml

TBLite 是 TerminalBench2 的轻量子类——仅数据集和超时设置不同。由 OpenThoughts Agent 团队（Snorkel AI + Bespoke Labs）创建。数据集：NousResearch/openthoughts-tblite。

YC-Bench

长周期战略基准测试 —— 代理扮演一家 AI 初创公司的 CEO。


测试内容	在数百轮中保持多轮战略连贯性
评分方式	综合评分：`0.5 × survival + 0.5 × normalised_funds`
沙箱	本地终端（无需 Modal）
工具	仅 `terminal`
运行次数	9 次默认运行（3 种预设 × 3 个种子），顺序执行
成本	完整评估约 $50–200
耗时	约 3–6 小时

# Install yc-bench (optional dependency)
pip install "hermes-agent[yc-bench]"

# Run evaluation
bash environments/benchmarks/yc_bench/run_eval.sh

# Or directly
python environments/benchmarks/yc_bench/yc_bench_env.py evaluate \
    --config environments/benchmarks/yc_bench/default.yaml

# Quick single-preset test
python environments/benchmarks/yc_bench/yc_bench_env.py evaluate \
    --config environments/benchmarks/yc_bench/default.yaml \
    --env.presets '["fast_test"]' --env.seeds '[1]'

YC-Bench 使用 collinear-ai/yc-bench —— 一个确定性模拟环境，包含 4 个技能领域（研究、推理、数据环境、训练）、声望系统、员工管理及财务压力。与 TB2 的单任务二元评分不同，YC-Bench 衡量的是代理能否在数百次累积决策中维持连贯的战略。

训练环境

TerminalTestEnv

一个最小化的自包含环境，任务内联（无需外部数据集）。用于 端到端验证整个系统栈。每个任务要求模型在已知路径创建文件；验证器检查内容是否正确。

# Process mode (saves rollouts to JSONL, no training server needed)
python environments/terminal_test_env/terminal_test_env.py process \
    --env.data_path_to_save_groups terminal_test_output.jsonl

# Serve mode (connects to Atropos API for RL training)
python environments/terminal_test_env/terminal_test_env.py serve

HermesSweEnv

类似 SWE-bench 的训练环境。模型获得一个编码任务，使用终端、文件、网页工具解决，奖励函数在相同的 Modal 沙箱中运行测试。

python environments/hermes_swe_env/hermes_swe_env.py serve \
    --openai.model_name YourModel \
    --env.dataset_name bigcode/humanevalpack \
    --env.terminal_backend modal

运行环境

每个环境都是一个独立的 Python 脚本，包含三个 CLI 子命令：

`evaluate` —— 运行基准测试

适用于仅评估环境（基准测试）。运行所有项目，计算指标，并记录到 Wandb。

python environments/benchmarks/tblite/tblite_env.py evaluate \
    --config environments/benchmarks/tblite/default.yaml \
    --openai.model_name anthropic/claude-sonnet-4.6

无需训练服务器或 run-api。环境自身处理全部流程。

`process` —— 生成 SFT 数据运行回滚并以 JSONL 格式保存评分后的轨迹。适用于在不进行完整强化学习（RL）循环的情况下生成训练数据。

python environments/terminal_test_env/terminal_test_env.py process \
    --env.data_path_to_save_groups output.jsonl \
    --openai.model_name anthropic/claude-sonnet-4.6

输出格式：每行包含一个评分轨迹，包含完整的对话历史、奖励值和元数据。

`serve` — 连接 Atropos 用于 RL 训练

将环境连接到正在运行的 Atropos API 服务器（run-api）。用于实时 RL 训练期间。

# Terminal 1: Start the Atropos API
run-api

# Terminal 2: Start the environment
python environments/hermes_swe_env/hermes_swe_env.py serve \
    --openai.model_name YourModel

环境从 Atropos 接收项目，执行代理回滚，计算奖励，并将评分后的轨迹发送回以供训练。

两阶段操作

阶段 1：OpenAI 服务器（评估 / SFT）

使用 server.chat_completion() 并设置 tools= 参数。服务器（VLLM、SGLang、OpenRouter、OpenAI）原生处理工具调用解析。返回包含结构化 tool_calls 的 ChatCompletion 对象。

用途：评估、SFT 数据生成、基准测试、测试
在 Atropos 流水线中创建占位符 token（因为 OpenAI API 无法提供真实 token ID）

阶段 2：VLLM ManagedServer（完整 RL）

使用 ManagedServer 获取精确的 token ID 和 logprobs，通过 /generate 实现。客户端侧的工具调用解析器从原始输出重建结构化的 tool_calls。

用途：支持 GRPO/PPO 的完整 RL 训练
真实 token、掩码和 logprobs 经过流水线传递
在配置中设置 tool_call_parser 以匹配你的模型格式（例如 "hermes"、"qwen"、"mistral"）

创建环境

训练环境

from environments.hermes_base_env import HermesAgentBaseEnv, HermesAgentEnvConfig
from atroposlib.envs.server_handling.server_manager import APIServerConfig

class MyEnvConfig(HermesAgentEnvConfig):
    my_custom_field: str = "default_value"

class MyEnv(HermesAgentBaseEnv):
    name = "my-env"
    env_config_cls = MyEnvConfig

    @classmethod
    def config_init(cls):
        env_config = MyEnvConfig(
            enabled_toolsets=["terminal", "file"],
            terminal_backend="modal",
            max_agent_turns=30,
        )
        server_configs = [APIServerConfig(
            base_url="https://openrouter.ai/api/v1",
            model_name="anthropic/claude-sonnet-4.6",
            server_type="openai",
        )]
        return env_config, server_configs

    async def setup(self):
        from datasets import load_dataset
        self.dataset = list(load_dataset("my-dataset", split="train"))
        self.iter = 0

    async def get_next_item(self):
        item = self.dataset[self.iter % len(self.dataset)]
        self.iter += 1
        return item

    def format_prompt(self, item):
        return item["instruction"]

    async def compute_reward(self, item, result, ctx):
        # ctx gives full tool access to the rollout's sandbox
        test = ctx.terminal("pytest -v")
        return 1.0 if test["exit_code"] == 0 else 0.0

    async def evaluate(self, *args, **kwargs):
        # Periodic evaluation during training
        pass

if __name__ == "__main__":
    MyEnv.cli()

仅评估基准测试

对于基准测试，请遵循 TerminalBench2、TBLite 和 YC-Bench 使用的模式：

在 environments/benchmarks/your-benchmark/ 下创建
设置仅评估配置：eval_handling=STOP_TRAIN、steps_per_eval=1、total_steps=1
存根训练方法：collect_trajectories() 返回 (None, [])，score() 返回 None
实现 rollout_and_score_eval(eval_item) — 每个项目的代理循环 + 评分逻辑
实现 evaluate() — 协调所有运行，计算聚合指标
添加流式 JSONL 以实现崩溃安全的结果持久化
添加清理逻辑：KeyboardInterrupt 处理、cleanup_all_environments()、_tool_executor.shutdown()
使用 evaluate 子命令运行

参见 environments/benchmarks/yc_bench/yc_bench_env.py 获取一个清晰且文档完善的参考实现。

配置参考

HermesAgentEnvConfig 字段

字段	类型	默认值	说明
`enabled_toolsets`	`List[str]`	`None`（全部）	启用哪些 hermes 工具集
`disabled_toolsets`	`List[str]`	`None`	要过滤掉的工具集
`distribution`	`str`	`None`	概率性工具集分布名称
`max_agent_turns`	`int`	`30`	每次回滚的最大 LLM 调用次数
`agent_temperature`	`float`	`1.0`	采样温度
`system_prompt`	`str`	`None`	代理的系统消息
`terminal_backend`	`str`	`"local"`	`local`、`docker`、`modal`、`daytona`、`ssh`、`singularity`
`terminal_timeout`	`int`	`120`	每条终端命令的秒数限制
`terminal_lifetime`	`int`	`3600`	最大沙箱生命周期
`dataset_name`	`str`	`None`	HuggingFace 数据集标识符
`tool_pool_size`	`int`	`128`	工具执行的线程池大小
`tool_call_parser`	`str`	`"hermes"`	第二阶段原始输出的解析器
`extra_body`	`Dict`	`None`	OpenAI API 的额外参数（如 OpenRouter 提供商偏好）
`eval_handling`	`Enum`	`STOP_TRAIN`	`STOP_TRAIN`、`LIMIT_TRAIN`、`NONE`

YAML 配置

可通过传入 YAML 文件进行环境配置，使用 --config：

env:
  enabled_toolsets: ["terminal", "file"]
  max_agent_turns: 60
  max_token_length: 32000
  agent_temperature: 0.8
  terminal_backend: "modal"
  terminal_timeout: 300
  dataset_name: "NousResearch/terminal-bench-2"
  tokenizer_name: "NousResearch/Hermes-3-Llama-3.1-8B"
  use_wandb: true
  wandb_name: "my-benchmark"

openai:
  base_url: "https://openrouter.ai/api/v1"
  model_name: "anthropic/claude-sonnet-4.6"
  server_type: "openai"
  health_check: false

YAML 值会覆盖 config_init() 的默认值。CLI 参数会覆盖 YAML 值：

python my_env.py evaluate \
    --config my_config.yaml \
    --openai.model_name anthropic/claude-opus-4.6  # overrides YAML

先决条件

所有环境通用

Python >= 3.11
atroposlib：`pip install git+https://github.com/NousResearch/atropos.git``
LLM API 密钥（OpenRouter、OpenAI 或自托管 VLLM/SGLang）

Modal 账户及 CLI：pip install "hermes-agent[modal]"
设置 MODAL_TOKEN_ID 和 MODAL_TOKEN_SECRET 环境变量

适用于 YC-Bench

pip install "hermes-agent[yc-bench]"（安装 yc-bench CLI + SQLAlchemy）
不需要 Modal —— 使用本地终端后端运行

适用于 RL 训练

TINKER_API_KEY — Tinker[https://tinker.computer] 训练服务的 API 密钥
WANDB_API_KEY — 用于 Weights & Biases 指标追踪
仓库中位于 tinker-atropos/ 的 tinker-atropos 子模块

参见 RL 训练了解由代理驱动的 RL 工作流程。

目录结构

environments/
├── hermes_base_env.py          # Abstract base class (HermesAgentBaseEnv)
├── agent_loop.py               # Multi-turn agent engine (HermesAgentLoop)
├── tool_context.py             # Per-rollout tool access for reward functions
├── patches.py                  # Async-safety patches for Modal backend
│
├── tool_call_parsers/          # Phase 2 client-side parsers
│   ├── hermes_parser.py        # Hermes/ChatML <tool_call> format
│   ├── mistral_parser.py       # Mistral [TOOL_CALLS] format
│   ├── llama_parser.py         # Llama 3 JSON tool calling
│   ├── qwen_parser.py          # Qwen format
│   ├── deepseek_v3_parser.py   # DeepSeek V3 format
│   └── ...                     # + kimi_k2, longcat, glm45/47, etc.
│
├── terminal_test_env/          # Stack validation (inline tasks)
├── hermes_swe_env/             # SWE-bench training environment
│
└── benchmarks/                 # Evaluation benchmarks
    ├── terminalbench_2/        # 89 terminal tasks, Modal sandboxes
    ├── tblite/                 # 100 calibrated tasks (fast TB2 proxy)
    └── yc_bench/               # Long-horizon strategic benchmark

架构设计​

BaseEnv（Atropos）​

HermesAgentBaseEnv​

具体环境​

核心组件​

代理循环​

工具上下文​

工具调用解析器​

可用基准测试​

TerminalBench2​

TBLite（OpenThoughts 终端基准精简版）​

YC-Bench​

训练环境​

TerminalTestEnv​

HermesSweEnv​

运行环境​

evaluate —— 运行基准测试​

process —— 生成 SFT 数据运行回滚并以 JSONL 格式保存评分后的轨迹。适用于在不进行完整强化学习（RL）循环的情况下生成训练数据。​

serve — 连接 Atropos 用于 RL 训练​

两阶段操作​

阶段 1：OpenAI 服务器（评估 / SFT）​

阶段 2：VLLM ManagedServer（完整 RL）​

创建环境​

训练环境​

仅评估基准测试​

配置参考​

HermesAgentEnvConfig 字段​

YAML 配置​

先决条件​

所有环境通用​

适用于 Modal 沙箱基准测试（TB2、TBLite）​

适用于 YC-Bench​

适用于 RL 训练​

目录结构​

架构设计

BaseEnv（Atropos）

HermesAgentBaseEnv

具体环境

核心组件

代理循环

工具上下文

工具调用解析器

可用基准测试

TerminalBench2

TBLite（OpenThoughts 终端基准精简版）

YC-Bench

训练环境

TerminalTestEnv

HermesSweEnv

运行环境

`evaluate` —— 运行基准测试

`process` —— 生成 SFT 数据运行回滚并以 JSONL 格式保存评分后的轨迹。适用于在不进行完整强化学习（RL）循环的情况下生成训练数据。

`serve` — 连接 Atropos 用于 RL 训练

两阶段操作

阶段 1：OpenAI 服务器（评估 / SFT）

阶段 2：VLLM ManagedServer（完整 RL）

创建环境

训练环境

仅评估基准测试

配置参考

HermesAgentEnvConfig 字段

YAML 配置

先决条件

所有环境通用

适用于 Modal 沙箱基准测试（TB2、TBLite）

适用于 YC-Bench

适用于 RL 训练

目录结构