`utils.py` — 提供 Agent 循环的辅助工具函数¶

文件路径: verl/experimental/agent_loop/utils.py

文件概述¶

提供 Agent 循环的辅助工具函数，主要包括： 1. 配置文件路径解析 2. GPT-OSS 模型的工具响应格式化

关键代码讲解¶

1. resolve_config_path - 配置路径解析¶

在分布式 Ray 训练中，远程节点的工作目录可能与驱动节点不同，导致相对路径无法正确解析。该函数按以下顺序尝试解析路径：

def resolve_config_path(config_path: str) -> str:
    # 1. 绝对路径直接返回
    if os.path.isabs(config_path):
        return config_path

    # 2. 尝试当前工作目录
    cwd_path = os.path.abspath(os.path.join(os.getcwd(), config_path))
    if os.path.exists(cwd_path):
        return cwd_path

    # 3. 尝试 verl 项目根目录（开发模式安装）
    import verl
    project_root = os.path.dirname(os.path.dirname(verl.__file__))
    dev_path = os.path.join(project_root, config_path)
    if os.path.exists(dev_path):
        return dev_path

    # 4. 尝试 verl 包目录（标准安装）
    install_path = os.path.join(os.path.dirname(verl.__file__), config_path)
    if os.path.exists(install_path):
        return install_path

    raise FileNotFoundError(f"Agent loop configuration file not found: {config_path}")

2. GPT-OSS 工具响应格式化¶

由于 GPT-OSS 模型的 tokenizer.apply_chat_template 无法正确处理工具响应（需要工具调用消息才能解析），因此需要手动格式化：

def format_gpt_oss_tool_response_manually(tool_response: str, tool_call_name: str) -> str:
    """手动格式化工具响应"""
    return (
        f"<|start|>functions.{tool_call_name} to=assistant"
        f"<|channel|>commentary<|message|>{tool_response}<|end|>"
    )

def add_generation_prompt_for_gpt_oss(message_content: str) -> str:
    """添加生成提示标记"""
    return message_content + "<|start|>assistant"

def build_gpt_oss_tool_response_text(messages, tool_call_names):
    """构建完整的工具响应文本（格式化 + 生成提示）"""
    tool_response_texts = []
    for i, tool_msg in enumerate(messages):
        formatted = format_gpt_oss_tool_response_manually(tool_msg["content"], tool_call_names[i])
        tool_response_texts.append(formatted)
    return add_generation_prompt_for_gpt_oss("".join(tool_response_texts))

输出示例：

<|start|>functions.search to=assistant<|channel|>commentary<|message|>搜索结果...<|end|><|start|>assistant

核心类/函数列表¶

名称	类型	说明
`resolve_config_path()`	函数	解析配置文件路径（支持分布式环境）
`format_gpt_oss_tool_response_manually()`	函数	GPT-OSS 工具响应格式化
`add_generation_prompt_for_gpt_oss()`	函数	添加 GPT-OSS 生成提示
`build_gpt_oss_tool_response_text()`	函数	构建完整的 GPT-OSS 工具响应文本

与其他模块的关系¶

resolve_config_path 被 AgentLoopWorker.__init__() 调用，解析 agent loop 配置文件
build_gpt_oss_tool_response_text 被 ToolAgentLoop._handle_processing_tools_state() 调用

小结¶

utils.py 提供两类工具：一是跨节点的配置路径解析（解决分布式训练的路径问题），二是 GPT-OSS 模型的特殊工具响应格式化（因为该模型的 tokenizer 无法自动处理工具消息）。

utils.py — 提供 Agent 循环的辅助工具函数¶