AutoAgent 评估框架（Evaluation Harness）实战指南：为 LLM Agent 构建自定义评测基准工作流

AutoAgent 评估框架Evaluation Harness实战指南为 LLM Agent 构建自定义评测基准工作流【免费下载链接】AutoAgentAutoAgent: Fully-Automated and Zero-Code LLM Agent Framework项目地址: https://gitcode.com/GitHub_Trending/au/AutoAgent本指南以 AutoAgent 仓库中的评测框架evaluation/目录为核心系统讲解如何将你自己的 benchmark 接入框架、如何基于现有 GAIA / MATH500 / MultiHopRAG 评测脚本快速起步以及如何理解评测循环中模拟用户交互这一关键机制。读完本文你将掌握从配置 LLM、编写process_instance处理函数、构造EvalOutput结果对象到并行运行与打分统计的完整评测工作流能够为任意 Agent 任务构建可复现、可扩展的自动化评测基准。环境与 LLM 配置评测前的基础准备评测的前提是配置好可用的 LLM。原文档以config.toml管理多个模型的配置典型示例如下[llm] # IMPORTANT在此处填入 API Key并指定你要评测的模型 model claude-3-5-sonnet-20241022 api_key sk-XXX [llm.eval_gpt4_1106_preview_llm] model gpt-4-1106-preview api_key XXX temperature 0.0 [llm.eval_some_openai_compatible_model_llm] model openai/MODEL_NAME base_url https://OPENAI_COMPATIBLE_URL/v1 api_key XXX temperature 0.0这段配置揭示了评测配置的三大要素模型名model、认证凭据api_key与推理参数temperature。注意评测场景通常将temperature设为0.0以保证结果可复现、避免随机性干扰打分。在 AutoAgent 仓库中评测时的模型选择并不依赖config.toml而是直接以命令行参数传入。以 evaluation/gaia/run_infer.py 为例get_args()中通过--model指定评测模型默认claude-3-5-sonnet-20241022通过--agent_func指定被测 Agent 的工厂函数默认get_system_triage_agent并支持--container_name、--port、--data_split、--eval_n_limit、--eval_num_workers等评测专用参数evaluation/gaia/scripts/run_infer.sh 还展示了通过环境变量注入COMPLETION_MODEL、BASE_IMAGES、EVAL_MODE、DEBUG的完整启动方式。MATH500 的评测入口 evaluation/math500/run_infer.py 则额外支持--limit、--stride、--offset等采样控制参数与--workflow可选majority_voting多智能体投票流程。命令行运行评测脚本的启动方式原文档给出的通用运行格式为poetry run python ./openhands/core/main.py \ -i max_iterations \ -t task_description \ -c agent_class \ -l llm_config其中-i限制最大迭代次数、-t是任务描述、-c指定 Agent 类、-l指向配置中对应的 LLM 段。示例poetry run python ./openhands/core/main.py \ -i 10 \ -t 给我写一个输出 hello world 的 bash 脚本。 \ -c CodeActAgent \ -l llm在 AutoAgent 仓库中这一一条命令跑完评测的模式由各 benchmark 的run_infer.py承担。例如运行 GAIA 验证集评测python evaluation/gaia/run_infer.py \ --container_name gaia_lite_eval \ --model claude-3-5-sonnet-20241022 \ --test_pull_name test_pull_1225 \ --eval_num_workers 1 \ --port 12345 \ --data_split validation \ --level 2023_all \ --agent_func get_system_triage_agent \ --git_clone运行完成后结果以 JSONL 格式写入输出目录再通过 evaluation/gaia/get_score.py 统计总成功率以及 L1/L2/L3 分级别成功率。整个流程与文档描述的指定任务 指定 Agent 指定 LLM 配置一脉相承只是将config.toml中的参数扁平化为命令行参数更利于脚本化批量评测。评测执行原理从入口函数到运行控制器原文档描述了评测框架的内部执行流程主入口解析参数与加载配置 → 通过create_runtime()创建运行环境 → 初始化指定 Agent → 通过run_controller()执行控制器将运行时绑定到 Agent、执行任务、返回最终状态。run_controller()是执行的核心负责协调 Agent、运行时与任务三者之间的交互并处理用户输入的模拟与事件处理。在 AutoAgent 仓库中这一职责由 autoagent/main.py 中的run_in_client/run_in_client_non_async承担。以 GAIA 评测为例evaluation/gaia/run_infer.py流程为从autoagent.registry的registry.agents中按--agent_func取出 Agent 工厂并实例化如system_triage_agent构造messages列表装入任务指令构造context_variables将三类环境注入上下文code_envDocker 代码执行环境、web_env浏览器环境、file_envMarkdown 文件浏览环境通过asyncio.run(run_in_client(...))运行 Agentmeta_agent参数传入工具编辑 Agentdocker_config与code_env提供沙箱执行能力返回Response对象其messages即为 Agent 的完整交互历史与最终回答。这与原文档创建运行时 → 初始化 Agent → 执行控制器 → 返回最终状态的骨架完全对应只是把运行时具体化为仓库中的DockerEnv、BrowserEnv、RequestsMarkdownBrowser三件套见 evaluation/gaia/run_infer.py 的create_environment。最省力的起点复用仓库中已有的评测基准原文档建议与其从零开始不如先查看仓库中已有的 benchmark选择与自身需求最接近的一个作为模板在其结构上修改适配。AutoAgent 仓库的 evaluation/ 目录恰好提供了三个可直接参照的完整实例GAIAevaluation/gaia/面向通用 AI 助手的多轮、多模态任务基准评测脚本包含 Docker 容器管理、文件复制进工作区、solution/solution答案解析与question_scorer打分支持数值、逗号/分号分隔列表、字符串三类标准答案的归一化比较见 evaluation/gaia/scorer.py是环境密集型评测的最佳模板MATH500evaluation/math500/数学推理基准通过MATH_COT_PROMPT少样本提示evaluation/math500/prompts.py驱动数学求解 Agent可对比单 Agent 与majority_voting工作流的差异是纯文本推理型评测的轻量模板MultiHopRAGevaluation/multihoprag/run_rag.py面向 RAG 的多跳问答评测从 CSV 读取 query 与标准答案结果写入result.json适合检索增强场景。建议的做法是先跑通与自己任务最相近的那个脚本如需要工具/环境交互就参考 GAIA纯文本生成就参考 MATH500再逐步替换数据集加载、指令构造与打分逻辑。如何创建自己的评测工作流这是原文档的核心章节也是接入 AutoAgent 评测框架的关键。其骨架由五个步骤组成1. 导入评测工具原文档的导入清单EvalMetadata、EvalOutput、make_metadata、prepare_dataset、run_evaluation等在 AutoAgent 仓库中对应evaluation包实际导入语句为from evaluation.utils import ( make_metadata, prepare_dataset, run_evaluation, update_progress, check_port_available, clean_msg, ) from evaluation.types import EvalMetadata, EvalOutput其中evaluation/types.py定义了评测数据模型EvalMetadata携带agent_func、model、eval_output_dir、start_time、dataset、data_split、port、container_name、git_clone等元信息evaluation/types.pyEvalOutput则封装单条实例的评测结果包括instance_id、test_result、instruction、metadata、messages、error等字段evaluation/types.py。2. 创建配置生成函数def get_config(instance: pd.Series, metadata: EvalMetadata) - AppConfig: config AppConfig( default_agentmetadata.agent_class, runtimedocker, max_iterationsmetadata.max_iterations, sandboxSandboxConfig( base_container_imageyour_container_image, enable_auto_lintTrue, timeout300, ), ) config.set_llm_config(metadata.llm_config) return config在 AutoAgent 中配置的对象从AppConfig变为DockerConfig见 evaluation/gaia/run_infer.py 的get_config。它根据instance_id生成唯一容器名metadata.container_name _ instance_id并通过文件锁 端口探测确保多进程并行时端口分配原子性随后组装DockerConfig(workplace_name..., container_name..., communication_port..., conda_path..., local_root..., git_clone..., test_pull_name...)。评测容器默认基于BASE_IMAGES指定的镜像如tjbtech1/gaia-bookworm:v2。3. 初始化运行环境def initialize_runtime(runtime: Runtime, instance: pd.Series): # 在此配置评测环境例如设置环境变量、准备文件等 pass在 AutoAgent 中对应create_environment(docker_config)创建DockerEnv并调用init_container()启动容器同时创建BrowserEnv浏览器与RequestsMarkdownBrowser文件浏览返回code_env, web_env, file_env三元组。GAIA 评测还会把数据集附带的任务文件复制进容器工作区dest_file os.path.join(local_workplace, ffile.{extension_name})并将文件路径追加进指令文本。4. 编写单实例处理函数process_instancedef process_instance(instance: pd.Series, metadata: EvalMetadata) - EvalOutput: config get_config(instance, metadata) runtime create_runtime(config) call_async_from_sync(runtime.connect) initialize_runtime(runtime, instance) instruction get_instruction(instance, metadata) state run_controller( configconfig, task_strinstruction, runtimeruntime, fake_user_response_fnyour_user_response_function, ) # 评测 Agent 的行为 evaluation_result await evaluate_agent_actions(runtime, instance) return EvalOutput( instance_idinstance.instance_id, instructioninstruction, test_resultevaluation_result, metadatametadata, historycompatibility_for_eval_history_pairs(state.history), metricsstate.metrics.get() if state.metrics else None, errorstate.last_error if state and state.last_error else None, )AutoAgent 中的真实实现evaluation/gaia/run_infer.py完整地遵循了这一骨架并展示了三个值得借鉴的细节指令构造即评测约束process_instance中把instance[Question]作为主指令并拼接多条IMPORTANT约束——禁止在任务完成前停止使用工具、必须交接给合适的 Agent、不确定时用 Web Surfer 搜索、需要计算时用 Programming Agent、绝不向人类求助、最终答案必须包裹在solution/solution标签中。这些约束正是文档所述模拟用户交互、将人工干预降到最低的工程化实现结果解析用re.findall(rsolution(.*?)/solution, ...)从最终消息中提取答案解析失败则回退为原始文本资源回收在finally块中停止容器并释放端口标记文件避免并行评测时资源泄漏。5. 执行评测主流程metadata make_metadata(llm_config, dataset_name, agent_class, max_iterations, eval_note, eval_output_dir) output_file os.path.join(metadata.eval_output_dir, output.jsonl) instances prepare_dataset(your_dataset, output_file, eval_n_limit) await run_evaluation( instances, metadata, output_file, num_workers, process_instance )AutoAgent 的对应实现位于 evaluation/utils.py四个核心函数的实际行为如下make_metadataevaluation/utils.py按eval_output_dir/dataset/agent_func/model_maxiter/的层级创建输出目录自动写入metadata.json并填充start_time等元信息prepare_datasetevaluation/utils.py要求数据集必须含instance_id列若输出文件已存在会读取其中已完成的实例并自动跳过断点续跑还支持eval_n_limit限制实例数、eval_ids指定实例 ID、skip_num跳过前 N 条三种采样策略run_evaluationevaluation/utils.py当num_workers 1时启用多进程并行通过mp.Queue收集结果、以tqdm进度条跟踪进度单进程模式则串行遍历数据集。每个实例由_process_instance_wrapper包装支持最多max_retries次失败重试默认 3 次应对网络抖动等瞬时错误重试耗尽后抛出RuntimeError终止评测evaluation/utils.pyupdate_progressevaluation/utils.py每条实例完成后将EvalOutput以 JSON 行形式追加写入output.jsonl并立即 flush保证进程异常时已完成的评测结果不丢失。流程闭合后run_evaluation管理全部并行化与进度追踪你只需要按 benchmark 需求定制get_instruction指令构造与打分函数如 GAIA 的question_scorer、MATH500 的is_correct即可获得健壮的评测工作流。理解user_response_fn模拟用户交互的关键组件user_response_fn是评测工作流中至关重要的组件它模拟用户与 Agent 之间的交互让评测过程可以自动化地给出预设的、一致性的回复。它的价值在于当你想给 Agent 的询问或动作提供固定、可预期的答复时不必真的有人守在终端前。工作流与交互循环正确的处理流程如下Agent 收到任务并开始处理Agent 发出一个 Action若该 Action 可执行如CmdRunAction、IPythonRunCellActionRuntime 处理该 Action并返回一个 Observation若该 Action 不可执行通常是MessageAction即 Agent 想向用户发消息user_response_fn被调用返回一条模拟的用户回复Agent 收到 Observation 或模拟回复重复步骤 25直到任务完成或达到最大迭代次数。更精确的流程示意如下[Agent] | v [发出一个 Action] | v [该 Action 可执行吗] / \ 是 否 | | v v [Runtime] [user_response_fn] | | v v [返回一个 Observation] [模拟回复] \ / \ / v v [Agent 收到反馈] | v [继续或结束任务]在这个工作流中可执行动作命令执行、代码运行等由 Runtime 直接处理不可执行动作通常是 Agent 想沟通或请求澄清由user_response_fn处理Agent 随后消化反馈——无论是 Runtime 的 Observation 还是函数返回的模拟回复。这一机制让具体动作的自动化处理与用户交互的模拟解耦非常适合在最小人工干预下测试 Agent 独立完成任务的能力。实现示例来自 SWE-Bench 评测def codeact_user_response(state: State | None) - str: msg ( 请继续以你认为合适的方式处理任务。\n 如果你认为任务已完成请先通过消息把你的答复发给用户然后执行 execute_bash exit /execute_bash。\n 重要你绝不应寻求人类帮助。\n ) if state and state.history: # 检查 Agent 是否已尝试与用户沟通 3 次若是则告知其可以放弃 user_msgs [ event for event in state.history if isinstance(event, MessageAction) and event.source user ] if len(user_msgs) 2: # 当 Agent 尝试 3 次后告知其可以放弃 return ( msg 如果你想放弃请执行execute_bash exit /execute_bash。\n ) return msg该函数做三件事提供标准提示词鼓励 Agent 继续工作检查 Agent 已经尝试与用户沟通的次数若多次尝试后仍未得到答复允许 Agent 通过exit主动放弃。使用这类函数可以保证多次评测运行之间的行为一致性并防止 Agent 因等待人工输入而卡死。需要说明的是在 AutoAgent 仓库中这个不让 Agent 等待人工的职责被前移至指令构造阶段——GAIA 评测在每条指令中显式追加IMPORTANT: You should ONLY interact with the environment provided to you AND NEVER ASK FOR HUMAN HELP.同时借助run_evaluation的失败重试机制吸收偶发异常从而在无user_response_fn的前提下实现了同等效果的自动化闭环见 evaluation/gaia/run_infer.py。结果统计与打分让评测闭环评测的最后一环是把output.jsonl转化为可读的指标。AutoAgent 提供了两个典型打分器GAIAevaluation/gaia/get_score.py逐行读取output.jsonl按test_result[score]判定单题成败并依据instance[Level]分别统计 L1/L2/L3 及总体成功率其底层打分器question_scorerevaluation/gaia/scorer.py对数字型答案做单位/逗号归一化后比较浮点值对列表型答案先按逗号/分号切分再逐元素比较长度不一致直接判负对字符串型答案去除空白、标点并统一小写后比较MATH500evaluation/math500/get_score.py遍历结果目录中的 YAML 文件复用lm-eval-harness的 minerva-math 工具normalize_final_answer、is_equiv等对answer与gt_answer做严格数学等价判定输出Accuracy。这两套打分器覆盖了数值/枚举/字符串精确匹配与数学表达式等价判定两类最常见评测需求均可直接复用或按需改写。结语从配置 LLM、运行评测脚本到理解run_controller的执行内核、复用evaluation/下的既有基准再到按照make_metadata → prepare_dataset → process_instance → run_evaluation → get_score的完整链路接入自有 benchmarkAutoAgent 的评测框架为 LLM Agent 的能力验证提供了端到端的工程化支撑。核心要领有三条以现有 benchmark 为模板起步GAIA 管环境交互、MATH500 管纯推理、MultiHopRAG 管检索增强让process_instance同时承担环境初始化、指令约束注入与结果解析通过并行 worker、断点续跑与自动重试保证评测的规模与稳健性。按此模式你可以在数小时内为自己的 Agent 构建出可复现、可横向对比的评测基准。【免费下载链接】AutoAgentAutoAgent: Fully-Automated and Zero-Code LLM Agent Framework项目地址: https://gitcode.com/GitHub_Trending/au/AutoAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考