evalstone/evalscope/docs/zh/user_guides/agent/native.md

内置 AgentLoop 模式

让常规基准（GSM8K、AIME、IFEval、SWE-bench 等）变成多轮工具调用任务，评测模型自身的工具使用与多步推理能力。EvalScope 在每一轮执行 生成 → 解析 → 调用工具 → 观察 → 再生成，直到模型提交最终答案或达到步数上限，整个轨迹记录到 AgentTrace 用于 可视化回放。

想直接评测 Claude Code / Codex 等成品 Agent CLI，请参见 外部 Agent Bridge 模式。

何时使用

• 评测模型的多步推理与工具调用能力 例：qwen-plus 在 GSM8K 上是否会主动调用 python_exec 验证计算，在 AIME 上能否逐步推导并自我检查。

• 让模型在代码修复任务中自主探索 例：在 SWE-bench 上让模型通过 bash 工具读代码、跑测试、提交补丁，全程无需人工介入。

• 接入 MCP 生态工具，扩展模型能力边界 例：给模型挂上 fetch、Brave Search 等 MCP 服务器，评测 GAIA 等需要联网检索的 benchmark。

快速开始

最小可运行示例：让 qwen-plus 在求解 GSM8K 时通过 python_exec 验证计算。

from evalscope import TaskConfig, run_task
from evalscope.api.agent import NativeAgentConfig

task_config = TaskConfig(
    model='qwen-plus',
    api_url='https://dashscope.aliyuncs.com/compatible-mode/v1',
    api_key='<your-key>',
    eval_type='openai_api',
    datasets=['gsm8k'],
    limit=5,
    generation_config={'parallel_tool_calls': True},
    agent_config=NativeAgentConfig(
        strategy='function_calling',
        tools=['python_exec'],
        environment='docker',
        environment_extra={
            'sandbox_config': {
                'image': 'python:3.11-slim',
            },
        },
        max_steps=5,
        kwargs={'system_prompt': 'Use python_exec to verify your calculations.'},
    ),
)
run_task(task_config)

EvalScope 自动给模型注入 python_exec 工具定义，在 Docker 容器里执行模型生成的 Python 代码，把 stdout/stderr 作为观察回填给模型，直到模型用 submit 工具提交答案。

常用配置

NativeAgentConfig 常用字段：

字段	说明	推荐值
strategy	交互协议	function_calling（默认）；模型不支持时用 react 或 swe_bench_backticks
tools	工具白名单	按需，如 ['python_exec'] / ['bash']
environment	工具或外部 Agent 的执行环境	local（开发）/ docker（生产）
environment_extra	Agent 环境构造参数	Docker 镜像、超时、挂载等环境专属设置
max_steps	单样本最大轮数	数学/QA 5-10，代码修复 100+
skills_dir	可选的本机 Agent Skills 目录	EvalScope 会在 agent loop 开始前让 skills 可用
kwargs	策略参数	最常用 {'system_prompt': '...'} 引导模型行为

可选的 strategy 值：

名称	适用场景
function_calling（默认）	模型支持原生 function-calling
react	ReAct 风格，让模型先思考再行动
swe_bench_toolcall	SWE-bench 工具调用协议
swe_bench_backticks	SWE-bench 反引号文本协议（模型不支持 function-calling 时）

可选的工具（tools）：

名称	说明
bash	执行 shell 命令
python_exec	执行 Python 代码
submit	提交最终答案（自动注入，无需手动配置）

- `local` 环境无文件系统隔离，生产请改用 `docker`。
- `agent_config` 也接受字典形式，`TaskConfig` 会自动转成 `NativeAgentConfig`。

Agent Skills

如果要让模型使用自定义 Agent Skills，可以把 NativeAgentConfig.skills_dir 设成本机目录。该目录的直接子目录应包含 SKILL.md。EvalScope 会在 agent loop 开始前让这些 skills 可用，并在 skill_prompt_nudge=True 时加入简短提示。

MCP 工具接入

除了内置工具，NativeAgentConfig 通过 mcp_servers 接入任意 MCP（Model Context Protocol） 服务器——把 fetch、网页搜索、GitHub 等 MCP 生态能力一键接入评测，不必自己写工具。

安装

pip install evalscope[mcp]

evalscope[mcp] 自带 mcp Python SDK 和 mcp-server-fetch（通用 HTTP 抓取，无需 API key）。其他 MCP server 按需安装或通过 uvx / npx 即调即用。

如果要看搜索类 benchmark 如何组合搜索 MCP 与 fetch/browser 类工具，请参考 DeepSearchQA 和 WideSearch 使用指南。

快速开始

给 GAIA 评测挂上 HTTP 抓取和远端 MCP 工具：

import sys
from evalscope import TaskConfig, run_task
from evalscope.api.agent import NativeAgentConfig
from evalscope.api.agent.mcp import MCPServerConfigStdio, MCPServerConfigHTTP

task_config = TaskConfig(
    model='qwen3-max',
    api_url='https://dashscope.aliyuncs.com/compatible-mode/v1',
    eval_type='openai_api',
    datasets=['gaia'],
    agent_config=NativeAgentConfig(
        mcp_servers=[
            # 本地启动 MCP 服务器进程
            MCPServerConfigStdio(
                command=sys.executable,
                args=['-m', 'mcp_server_fetch', '--ignore-robots-txt'],
                name='fetch',
            ),
            # 连接远端 MCP endpoint
            MCPServerConfigHTTP(
                url='https://mcp.api-inference.modelscope.net/<server-id>/mcp',
                headers={'Authorization': 'Bearer <TOKEN>'},
                name='modelscope_tool',
            ),
        ],
    ),
    dataset_args={'gaia': {'subset_list': ['2023_level1']}},
    limit=5,
)
run_task(task_config)

配置好后，agent loop 里模型会同时看到内置工具和所有 MCP 服务器声明的工具，按名称选用。MCP 工具调用如果失败，错误信息会返回给模型让它重试，不会中断整个评测。

接入方式

EvalScope 支持三种 MCP 传输协议，按场景选用：

配置类	适用场景	关键参数
MCPServerConfigStdio	本地启动 MCP 服务器进程	command、args、env
MCPServerConfigHTTP	连接远端 Streamable HTTP endpoint（推荐）	url、headers
MCPServerConfigSSE	连接旧版 SSE endpoint	url、headers

所有配置类共享 name（日志显示名）和 tools（工具白名单，默认 'all'）两个通用字段。完整参数列表见 源码。

- CI/生产环境推荐 `python -m mcp_server_<x>` + 提前 `pip install`，避免运行时拉包。
- `uvx mcp-server-<x>` 适合临时调试，首次调用会自动安装。
- 远端服务同时提供 `/mcp` 和 `/sse` 时，优先选 `/mcp`（Streamable HTTP）。

用例：SWE-bench Agentic

swe_bench_*_agentic 系列（swe_bench_verified_agentic、swe_bench_verified_mini_agentic、swe_bench_lite_agentic）由基准自己管理每个样本的 Docker 环境和必需的 bash 工具。显式设置的 NativeAgentConfig 仍可覆盖策略、步数上限等循环配置。dataset_args.extra_params 只用于镜像准备等基准专属参数。

from evalscope.api.agent import NativeAgentConfig

task_config = TaskConfig(
    model='qwen-plus',
    api_url='...',
    api_key='...',
    eval_type='openai_api',
    datasets=['swe_bench_verified_mini_agentic'],
    agent_config=NativeAgentConfig(
        strategy='swe_bench_toolcall',
        max_steps=250,
    ),
    dataset_args={
        'swe_bench_verified_mini_agentic': {
            'extra_params': {
                'build_docker_images': True,
                'pull_remote_images_if_available': True,
            },
        },
    },
    limit=3,
    generation_config={'max_tokens': 4096, 'temperature': 0.0},
)
run_task(task_config)

不支持 function calling 的模型可用 NativeAgentConfig(strategy='swe_bench_backticks')。常用 extra_params 包括 build_docker_images、pull_remote_images_if_available、force_arch。完整说明见对应 benchmark 文档。

前置依赖：`pip install evalscope[swe_bench]`，本机已装好 Docker。

常见问题

模型完全没有调用工具

1. 检查 tools 中的工具名拼写。
2. 确认模型支持 function-calling；不支持的可换 react 或 swe_bench_backticks 等文本协议。
3. 用 kwargs={'system_prompt': '...'} 显式引导模型调用工具。

max_steps 应该设多大

• 数学/简单 QA：3–10 通常够用。
• 代码修复/SWE-bench 类：沿用默认 250，过低会大量出现 max_steps_exceeded。