用型Agent評測環(huán)境)
在實際 LLM 項目中Agent 的能力邊界往往不由模型參數(shù)單獨決定而是取決于它能不能在一連串不確定環(huán)境里穩(wěn)定地把外部工具用起來。MCP-Bench 這類以“復(fù)雜真實世界任務(wù)”為對象的工具調(diào)用型 Agent 基準(zhǔn)正是為了回答這個問題而出現(xiàn)的任務(wù)不是簡單問答而是讀取日志、查詢數(shù)據(jù)庫、調(diào)用 API、根據(jù)中間結(jié)果糾正動作的多步流程。協(xié)議層面用 MCP 統(tǒng)一工具接入評估層面用一組可打分、可復(fù)現(xiàn)、可歸因的任務(wù)去測量不同模型和 Agent 框架的實際表現(xiàn)這正是 MCP-Bench 的核心思路。這篇文章以 MCP-Bench 的評測主線展開。先解釋為什么工具調(diào)用型 Agent 需要獨立基準(zhǔn)再拆解 MCP 協(xié)議的工具調(diào)用鏈路與評測任務(wù)設(shè)計要點隨后從零搭建最小可運行評測環(huán)境實現(xiàn)任務(wù)定義、工具執(zhí)行、結(jié)果評分和日志采集最后討論指標(biāo)讀取、高頻故障定位以及把本地 Demo 擴展成生產(chǎn)級評測時該補哪些能力。適合正在做 Agent 評測、準(zhǔn)備接入 MCP 工具或者想在自己項目中量化 LLM 工具調(diào)用質(zhì)量的開發(fā)者閱讀。1. 工具調(diào)用型 Agent 為什么需要獨立的評測基準(zhǔn)1.1 QA 正確率衡量不了“會不會用工具”傳統(tǒng)大模型評測通常把模型當(dāng)作知識問答器給輸入比輸出算正確率。這種模式對事實記憶、推理能力、文本生成質(zhì)量有效但對 Agent 場景不夠。Agent 的產(chǎn)出不是一個靜態(tài)答案而是一串動作序列判斷當(dāng)前缺什么信息決定調(diào)用哪個工具解析返回結(jié)果再決定下一步。同一個任務(wù)兩個模型可能都完成了目標(biāo)但一個用了 3 次工具調(diào)用另一個用了 20 次一個能處理工具返回的異常格式另一個直接卡死。這種差異無法用選擇題正確率體現(xiàn)。所以工具調(diào)用型 Agent 需要獨立基準(zhǔn)。它要測量的是模型在“決策-行動-觀察”循環(huán)中的綜合能力而不是單次生成能力。MCP-Bench 這類基準(zhǔn)把這種循環(huán)固化成標(biāo)準(zhǔn)任務(wù)讓不同模型和框架在同樣條件下跑同樣的流程結(jié)果才有可比性。1.2 復(fù)雜真實世界任務(wù)給 Agent 出的三道難題進(jìn)入真實場景后工具調(diào)用型 Agent 面對的問題通常比教科書示例復(fù)雜得多主要體現(xiàn)為三點。第一上下文碎片化。任務(wù)需要的信息分散在不同文件、數(shù)據(jù)庫、接口里Agent 必須主動拉取不能指望用戶一次性給全。第二工具協(xié)議不統(tǒng)一。團隊里可能有 REST API、數(shù)據(jù)庫連接、命令行腳本、內(nèi)部 SDK如果每個工具都自己定義調(diào)用格式Agent 適配成本非常高。第三失敗難復(fù)現(xiàn)。工具會超時、返回空值、報權(quán)限錯誤Agent 必須能感知并調(diào)整否則同樣的任務(wù)換個環(huán)境就失敗。這些難題意味著評測任務(wù)必須設(shè)計成“真實世界的復(fù)雜度”而不是把多個簡單問答拼在一起。一個合格的工具調(diào)用型 Agent 評測任務(wù)應(yīng)該要求 Agent 自己決定調(diào)用順序、自己判斷結(jié)果正確性、自己處理異常分支。1.3 MCP 和 MCP-Bench 的關(guān)系MCPModel Context Protocol是一個開放協(xié)議用來標(biāo)準(zhǔn)化 LLM 應(yīng)用與外部數(shù)據(jù)源、工具之間的連接方式。在 MCP 生態(tài)里工具提供方只需要按協(xié)議實現(xiàn)一套服務(wù)模型應(yīng)用就能通過統(tǒng)一方式發(fā)現(xiàn)工具、描述參數(shù)、發(fā)起調(diào)用、接收結(jié)果。這解決了 1.2 節(jié)提到的協(xié)議碎片化問題。MCP-Bench 則可以理解成圍繞這種工具調(diào)用模式設(shè)計的評估框架用 MCP 服務(wù)承載待測工具用復(fù)雜的真實任務(wù)驅(qū)動模型行動再用統(tǒng)一評分邏輯判斷模型是否完成了目標(biāo)。需要說明的是不同團隊對 MCP-Bench 的落地方式并不完全一致有的基于公開評測集有的基于內(nèi)部業(yè)務(wù)任務(wù)集但共同點是“MCP 協(xié)議 工具調(diào)用型 Agent 復(fù)雜任務(wù)評分”這個組合。1.4 評測時應(yīng)該關(guān)注的對象跑一個 MCP-Bench 風(fēng)格評測關(guān)注的不是某一次工具調(diào)用有沒有成功而是整條 Agent 鏈路的表現(xiàn)至少包含四層模型層是否理解任務(wù)語義能否把用戶請求拆成工具調(diào)用計劃。協(xié)議層MCP Server 是否正常工具參數(shù)是否符合 Schema返回結(jié)果能否被解析。Agent 框架層是否維護(hù)多輪上下文是否限制最大調(diào)用次數(shù)是否對工具異常有兜底。評測任務(wù)層任務(wù)答案是否明確評分規(guī)則是否覆蓋部分完成的情況任務(wù)是否具備區(qū)分度。如果只盯著“工具有沒有返回結(jié)果”很容易被一次偶發(fā)成功誤導(dǎo)。MCP-Bench 的價值在于把上述每一層都變成可觀測、可評分的對象。2. MCP 工具調(diào)用鏈路與評測任務(wù)的關(guān)鍵設(shè)計點2.1 MCP 的三段式架構(gòu)理解 MCP-Bench 前要先理解 MCP 工具調(diào)用鏈路。MCP 采用三段式結(jié)構(gòu)MCP Host運行 LLM 的應(yīng)用負(fù)責(zé)組織對話流程把模型決策轉(zhuǎn)發(fā)給工具。MCP ClientHost 內(nèi)部連接 Server 的客戶端組件負(fù)責(zé)協(xié)議通信。MCP Server實際執(zhí)行工具的服務(wù)進(jìn)程暴露工具清單并接收調(diào)用請求。調(diào)用鏈路可以概括為用戶在 Host 中發(fā)起任務(wù) - 模型分析后決定調(diào)用某個工具 - Host 通過 Client 向 Server 請求工具執(zhí)行 - Server 返回結(jié)構(gòu)化結(jié)果 - 模型根據(jù)結(jié)果繼續(xù)決策。整個過程是循環(huán)的直到模型認(rèn)為任務(wù)完成或達(dá)到最大輪數(shù)限制。這種結(jié)構(gòu)天然適合評測Server 負(fù)責(zé)提供可復(fù)現(xiàn)的工具環(huán)境Runner 負(fù)責(zé)記錄每一輪決策和結(jié)果任務(wù)集負(fù)責(zé)定義預(yù)期目標(biāo)。評測框架可以把它抽象成“輸入任務(wù) - 循環(huán)工具調(diào)用 - 輸出最終答案 - 對照評分”。2.2 三個核心原語Resources、Prompts、ToolsMCP 給模型應(yīng)用提供了三類能力評測任務(wù)設(shè)計時經(jīng)常涉及原語作用評測中的典型用法Resources向模型提供讀取型數(shù)據(jù)比如文件內(nèi)容、數(shù)據(jù)庫記錄提供任務(wù)背景資料避免把信息全部塞進(jìn) promptPrompts可復(fù)用的提示模板規(guī)范模型如何完成某類操作定義工具調(diào)用說明和輸出格式模板Tools模型可以主動調(diào)用的執(zhí)行型函數(shù)需要參數(shù) Schema作為評測中的被調(diào)用對象記錄調(diào)用軌跡對工具調(diào)用型 Agent 評測來說Tools 是核心。一個 Tool 包含名稱、描述、輸入 Schema 和執(zhí)行邏輯。描述寫得好不好直接影響模型能否正確選擇工具Schema 設(shè)計得清不清楚直接影響參數(shù)填充是否正確。這兩點也是評測中差異最大的變量。2.3 一個多步任務(wù)在 MCP 鏈路中如何執(zhí)行用一個例子說明多步任務(wù)在 MCP 鏈路里的執(zhí)行過程。假設(shè)評測任務(wù)要求 Agent“統(tǒng)計某個服務(wù)日志中出現(xiàn) ERROR 的次數(shù)并判斷錯誤最集中的時間段”。模型會把任務(wù)拆成兩步先調(diào)用read_log工具讀取日志文件再調(diào)用extract_stats工具或自己分析文本。如果設(shè)計成鏈?zhǔn)饺蝿?wù)第二步可能依賴第一步的返回值。實際的協(xié)議消息可以簡化成下面這樣先列出 Server 支持的工具{ jsonrpc: 2.0, id: 1, method: tools/list, params: {} }Server 返回工具描述{ jsonrpc: 2.0, id: 1, result: { tools: [ { name: read_log, description: 讀取指定日志文件返回全部行, inputSchema: { type: object, properties: { path: { type: string } }, required: [path] } } ] } }模型決定調(diào)用工具后發(fā)送tools/call請求{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: read_log, arguments: { path: logs/app.log } } }Server 返回執(zhí)行結(jié)果{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: ERROR count: 17\n[2025-01-01 00:01:02] ERROR ... } ] } }評測腳本要記錄的就是這些請求和響應(yīng)模型在什么輪次調(diào)用什么工具、傳了什么參數(shù)、拿到什么結(jié)果、最后得出什么結(jié)論。有了這種完整軌跡評分和排錯才有依據(jù)。2.4 評測框架必須采集的四類數(shù)據(jù)一個合格的工具調(diào)用型 Agent 評測框架最少要采集四類數(shù)據(jù)任務(wù)輸入與預(yù)期任務(wù)原始描述、預(yù)期結(jié)果表達(dá)式、允許的最大調(diào)用輪數(shù)。動作序列模型每一步的決策類型、工具名、參數(shù)、對應(yīng)輪次。工具執(zhí)行結(jié)果每個工具的成功狀態(tài)、返回內(nèi)容、耗時、異常信息。最終輸出與評分模型給出的最終答案、任務(wù)得分、扣分項說明。采集這些數(shù)據(jù)不只為給一個分?jǐn)?shù)而是為了讓失敗可以歸因。一個 Agent 任務(wù)失敗可能是模型規(guī)劃錯誤也可能是工具參數(shù) Schema 寫錯還可能是 Server 崩潰。沒有動作序列和工具執(zhí)行日志這幾個原因很難區(qū)分。3. 搭建最小可復(fù)現(xiàn)的評測環(huán)境3.1 依賴與目錄結(jié)構(gòu)推薦使用 Python 3.10 以上版本配合 MCP 官方 SDK 搭建本地評測環(huán)境。依賴安裝命令如下mkdir -p mcp-bench-demo/{tasks,logs,server,runner} cd mcp-bench-demo python -m venv .venv source .venv/bin/activate pip install mcp不同版本的 MCP SDK 在 FastMCP API 上略有差異落地前可以用pip show mcp查看版本再對照官方文檔確認(rèn)接口寫法。下面的例子基于 mcp SDK 1.x 的常見寫法。推薦的目錄結(jié)構(gòu)mcp-bench-demo/ ├── server/ │ └── bench_server.py ├── runner/ │ └── bench_runner.py ├── tasks/ │ └── tasks.json └── logs/ └── app.loglogs 目錄放模擬業(yè)務(wù)日志server 目錄放 MCP Serverrunner 目錄放評測腳本tasks 目錄放任務(wù)集。目錄職責(zé)分開后續(xù)擴展任務(wù)和排查問題都會方便很多。3.2 用 FastMCP 編寫一個帶兩個工具的 Server下面這個 Server 暴露兩個工具一個統(tǒng)計日志關(guān)鍵字次數(shù)一個讀取用戶信息。前者是單步工具后者用于演示鏈?zhǔn)讲樵儭? server/bench_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(bench-tools) mcp.tool() def count_keyword(log_path: str, keyword: str) - str: 統(tǒng)計指定日志文件中關(guān)鍵字出現(xiàn)的次數(shù)。 Args: log_path: 日志文件路徑例如 logs/app.log keyword: 要統(tǒng)計的關(guān)鍵字例如 ERROR count 0 with open(log_path, r, encodingutf-8) as f: for line in f: if keyword in line: count 1 return str(count) mcp.tool() def get_user_region(user_id: str) - str: 根據(jù)用戶 ID 返回用戶所在地區(qū)。 Args: user_id: 用戶唯一標(biāo)識例如 u-1001 mock_users { u-1001: shenzhen, u-1002: beijing, u-1003: chengdu, } region mock_users.get(user_id, unknown) return region mcp.tool() def get_weather(city: str) - str: 返回指定城市的天氣情況。 Args: city: 城市英文名例如 shenzhen mock_weather { shenzhen: sunny, 28c, beijing: cloudy, 18c, chengdu: rainy, 22c, } return mock_weather.get(city, unknown weather) if __name__ __main__: mcp.run()這個示例中用字典模擬用戶數(shù)據(jù)和天氣數(shù)據(jù)實際項目里可以替換成數(shù)據(jù)庫查詢或外部 API 調(diào)用。三個工具中count_keyword是獨立工具get_user_region和get_weather可以組合成鏈?zhǔn)饺蝿?wù)先查用戶地區(qū)再根據(jù)地區(qū)查天氣。3.3 通過 JSON-RPC 驗證 Server 是否正常啟動 Server 前先用 Python 自帶方式檢查能否加載模塊cd mcp-bench-demo python -c import server.bench_server; print(import ok)如果輸出import ok說明依賴和模塊路徑正常。接著啟動服務(wù)python server/bench_server.py本地 MCP Server 一般通過 stdio 或 HTTP 與客戶端通信。FastMCP 的mcp.run()在不同版本中默認(rèn)傳輸方式不同有的是 stdio有的是 HTTP。為了方便評測腳本調(diào)用可以顯式配置成 HTTP 模式也可以直接讓 Runner 以子進(jìn)程方式啟動 Server。學(xué)習(xí)階段建議先用 HTTP 模式便于用 curl 驗證。如果 Server 以 HTTP 方式運行可以用下面這條命令驗證tools/listcurl -s -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}}響應(yīng)里能列出三個工具說明 Server 工作正常。這一步很重要因為后面的 Runner 會對 Server 通信結(jié)果做依賴如果 Server 沒起來所有評測都會失敗。3.4 任務(wù)集 JSON 的設(shè)計與示例任務(wù)集是評測的核心資產(chǎn)。設(shè)計任務(wù)時要把任務(wù)描述、最大步數(shù)、預(yù)期結(jié)果校驗方式都定義清楚。下面是一個合適的示例{ tasks: [ { id: task-001, name: 統(tǒng)計 ERROR 日志數(shù)量, prompt: 請統(tǒng)計 logs/app.log 中 ERROR 出現(xiàn)的總次數(shù)直接返回數(shù)字。, max_steps: 3, expected: 17 }, { id: task-002, name: 查詢用戶所在城市天氣, prompt: 用戶 u-1001 想了解自己所在城市的天氣請查詢該用戶的地區(qū)并返回當(dāng)?shù)靥鞖狻? max_steps: 4, expected: sunny, 28c } ] }任務(wù)一測試單工具調(diào)用。任務(wù)二測試鏈?zhǔn)秸{(diào)用模型必須先調(diào)用get_user_region再調(diào)用get_weather。如果模型直接猜測天氣即使答案碰巧正確評測腳本也能根據(jù)動作軌跡判斷它的行為不正確這就是動作序列采集的作用。4. 實現(xiàn)最小 MCP-Bench 評測 Runner4.1 Runner 的整體流程評測 Runner 是整篇文章的核心部分。它讀取任務(wù)集為每個任務(wù)建立一次 Agent 會話循環(huán)執(zhí)行“模型決策 - 工具調(diào)用 - 結(jié)果收集”最后輸出評分和軌跡。流程如下加載 tasks.json。啟動或連接 MCP Server。獲取工具列表緩存到本地。對每個任務(wù)構(gòu)造初始 prompt 并進(jìn)入循環(huán)。每一輪讓規(guī)劃器決定動作類型tool_call或finish。如果是tool_call調(diào)用 MCP Server 并記錄結(jié)果。如果是finish把最終答案交給評分函數(shù)。匯總所有任務(wù)的分?jǐn)?shù)、工具調(diào)用次數(shù)、異常日志。4.2 模型規(guī)劃器抽象本地用固定策略線上替換成真實 LLM為了不依賴具體模型 API Key也為了讓評測框架本身可以先跑通這里定義一個AgentPlanner抽象它只負(fù)責(zé)“根據(jù)當(dāng)前消息歷史生成下一個動作”。本地驗證時用MockPlanner它從任務(wù)配置里讀取預(yù)設(shè)的動作序列模擬一個聽話的 Agent真實評測時把它替換成真實 LLM 調(diào)用即可。# runner/agent_planner.py from abc import ABC, abstractmethod from dataclasses import dataclass, field from typing import Any dataclass class Action: type: str # tool_call or finish tool_name: str arguments: dict field(default_factorydict) answer: str class AgentPlanner(ABC): abstractmethod def next_action(self, messages: list[dict]) - Action: ... class MockPlanner(AgentPlanner): 本地驗證用按 task 中配置的固定動作序列執(zhí)行。 def __init__(self, plan: list[dict]): self.plan plan self.index 0 def next_action(self, messages: list[dict]) - Action: if self.index len(self.plan): return Action(typefinish, answerNO_ANSWER) step self.plan[self.index] self.index 1 if step[type] tool_call: return Action( typetool_call, tool_namestep[tool_name], argumentsstep[arguments], ) return Action(typefinish, answerstep[answer])真實項目里替換next_action時只需要把messages發(fā)給大模型解析模型返回的 tool_calls 和最終文本轉(zhuǎn)成Action。這個替換對 Runner 的其他部分完全透明。4.3 客戶端封裝連接 Server、列出工具、調(diào)用工具下面封裝一個 MCPClient負(fù)責(zé)與 Server 通信。如果使用官方 SDK可以直接用客戶端類這里為了展示原理寫一個基于 requests 的簡潔版本方便閱讀和調(diào)試。# runner/mcp_client.py import requests class MCPClient: def __init__(self, endpoint: str): self.endpoint endpoint self.tools: dict {} def list_tools(self) - dict: payload { jsonrpc: 2.0, id: 1, method: tools/list, params: {}, } resp requests.post(self.endpoint, jsonpayload, timeout10) resp.raise_for_status() data resp.json() tools data[result][tools] self.tools {t[name]: t for t in tools} return self.tools def call_tool(self, name: str, arguments: dict) - dict: payload { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: name, arguments: arguments, }, } resp requests.post(self.endpoint, jsonpayload, timeout15) resp.raise_for_status() data resp.json() if error in data: return {ok: False, error: data[error]} content data[result][content] text for item in content: if item.get(type) text: text item.get(text, ) return {ok: True, text: text}代碼里把tools/list的結(jié)果緩存到self.tools后續(xù)評分統(tǒng)計可以知道模型調(diào)用的工具是否真實存在。call_tool返回統(tǒng)一結(jié)構(gòu)無論成功失敗都包含可觀測的結(jié)果字段。4.4 任務(wù)執(zhí)行循環(huán)與結(jié)果收集主執(zhí)行循環(huán)記錄每一步動作、工具返回值和異常信息最后把完整軌跡交給評分函數(shù)。# runner/bench_runner.py import json from agent_planner import MockPlanner from mcp_client import MCPClient def run_single_task(client: MCPClient, task: dict, planner: AgentPlanner): max_steps task.get(max_steps, 5) messages [{role: user, content: task[prompt]}] trace { task_id: task[id], steps: [], final_answer: , tool_calls: 0, errors: [], } for step_index in range(max_steps): try: action planner.next_action(messages) except Exception as exc: trace[errors].append(fplanner_error: {exc}) break if action.type finish: trace[final_answer] action.answer return trace if action.type tool_call: trace[tool_calls] 1 result client.call_tool(action.tool_name, action.arguments) step_record { step: step_index 1, action: tool_call, tool_name: action.tool_name, arguments: action.arguments, result: result, } trace[steps].append(step_record) if not result.get(ok): trace[errors].append( ftool_error: {action.tool_name} - {result.get(error)} ) messages.append({ role: tool, content: json.dumps(result, ensure_asciiFalse), }) trace[errors].append(max_steps_exceeded) return trace注意這里把每一步的工具結(jié)果放進(jìn)了messages目的和真實 MCP 鏈路一致模型需要看到工具返回結(jié)果才能決定下一步。評測框架也應(yīng)該保留這些消息便于后續(xù)分析模型決策邏輯。4.5 評分函數(shù)與運行輸出評分函數(shù)需要平衡“完成正確性”和“過程效率”。下面是一個簡單但可擴展的版本def score_trace(task: dict, trace: dict) - float: score 0.0 expected task.get(expected) actual trace.get(final_answer, ).strip() if actual expected: score 1.0 elif expected in actual: score 0.6 else: score 0.0 tool_calls trace.get(tool_calls, 0) max_steps task.get(max_steps, 5) efficiency_penalty min(tool_calls / (max_steps * 2), 0.3) score - efficiency_penalty if trace.get(errors): score - 0.2 return round(max(score, 0.0), 2) def run_all(tasks_path: str, endpoint: str): with open(tasks_path, r, encodingutf-8) as f: tasks json.load(f)[tasks] client MCPClient(endpoint) client.list_tools() report [] for task in tasks: plan [ {type: tool_call, tool_name: count_keyword, arguments: {log_path: logs/app.log, keyword: ERROR}}, {type: finish, answer: 17}, ] if task[id] task-002: plan [ {type: tool_call, tool_name: get_user_region, arguments: {user_id: u-1001}}, {type: tool_call, tool_name: get_weather, arguments: {city: shenzhen}}, {type: finish, answer: sunny, 28c}, ] planner MockPlanner(plan) trace run_single_task(client, task, planner) score score_trace(task, trace) report.append({task_id: task[id], score: score, trace: trace}) for item in report: print(json.dumps({ task_id: item[task_id], score: item[score], tool_calls: item[trace][tool_calls], final_answer: item[trace][final_answer], }, ensure_asciiFalse)) if __name__ __main__: run_all(tasks/tasks.json, http://127.0.0.1:8000/mcp)運行后預(yù)期輸出{task_id: task-001, score: 1.0, tool_calls: 1, final_answer: 17} {task_id: task-002, score: 1.0, tool_calls: 2, final_answer: sunny, 28c}當(dāng)模型規(guī)劃正確、工具實現(xiàn)正確時兩個任務(wù)都能拿滿分。真實評測中MockPlanner 會被替換成 LLM分?jǐn)?shù)就會出現(xiàn)差異這時候就需要看 trace 里的每一步判斷是規(guī)劃錯誤還是工具錯誤。5. 評測指標(biāo)、參數(shù)與任務(wù)梯度結(jié)果不是跑出分?jǐn)?shù)就結(jié)束5.1 核心指標(biāo)怎么算、怎么用MCP-Bench 類評測不能只看一個總分建議把指標(biāo)拆開每個指標(biāo)對應(yīng)一類能力問題指標(biāo)計算方式反映的問題任務(wù)成功率完全正確任務(wù)數(shù) / 總?cè)蝿?wù)數(shù)基礎(chǔ)完成能力任務(wù)完成度各任務(wù)得分加權(quán)平均部分完成能力平均工具調(diào)用數(shù)工具調(diào)用總次數(shù) / 任務(wù)數(shù)規(guī)劃效率無效調(diào)用率返回錯誤或空結(jié)果的調(diào)用次數(shù) / 總調(diào)用次數(shù)工具描述和模型理解質(zhì)量異?；謴?fù)率出錯后仍完成任務(wù)數(shù) / 出錯任務(wù)數(shù)魯棒性最終答案命中率最終答案包含預(yù)期關(guān)鍵內(nèi)容的任務(wù)占比結(jié)果可靠性單一成功率會掩蓋過程問題。比如一個 Agent 靠亂猜答案碰巧命中成功率很高但工具基本沒用這就不是合格的工具調(diào)用 Agent。所以評測一定要結(jié)合動作軌跡查看不能只看最終分?jǐn)?shù)。5.2 任務(wù)梯度決定評測區(qū)分度評測任務(wù)不能全是“讀一個文件返回數(shù)字”這種簡單任務(wù)也不建議一上來就是十幾個工具的長鏈路任務(wù)。建議劃分難度梯度基礎(chǔ)層單工具調(diào)用直接返回結(jié)果例如統(tǒng)計關(guān)鍵字。鏈?zhǔn)綄觾蓚€或以上工具串聯(lián)后一個工具依賴前一個結(jié)果。條件層根據(jù)工具返回內(nèi)容決定調(diào)用哪個分支工具。異常層工具會返回空值、錯誤碼或超時考察模型恢復(fù)能力。并行層多個獨立工具需要分批調(diào)用再把結(jié)果匯總。配置任務(wù)時每層至少 3 到 5 個任務(wù)。如果某個模型在基礎(chǔ)層滿分、鏈?zhǔn)綄拥梅值驼f明它工具理解能力沒問題但多步規(guī)劃能力弱如果在鏈?zhǔn)綄右部梢?、異常層下降明顯說明它對錯誤處理缺少兜底策略。這種梯度化分析比一個總分?jǐn)?shù)更有診斷價值。5.3 影響評測結(jié)果的四個關(guān)鍵參數(shù)評測時容易忽略參數(shù)對結(jié)果的干擾。下面四個參數(shù)對結(jié)果影響最大建議統(tǒng)一記錄參數(shù)默認(rèn)值參考調(diào)大影響調(diào)小影響溫度 temperature0 到 0.2動作更多樣但更容易出現(xiàn)無效調(diào)用結(jié)果更穩(wěn)定但可能缺少探索最大步數(shù) max_steps5 到 10給長鏈路任務(wù)更多機會但掩蓋低效問題對長任務(wù)不友好容易截斷工具描述長度一到三句模型更好理解但會占用上下文描述過短時模型容易選錯工具上下文窗口模型按模型實際支持配置能容納更多中間結(jié)果但成本上升長鏈路任務(wù)容易截斷歷史評測報告里應(yīng)該記錄這些參數(shù)否則兩個團隊跑同一個任務(wù)集因為溫度或最大步數(shù)不同分?jǐn)?shù)完全不同結(jié)果無法對比。MCP-Bench 風(fēng)格評測對可復(fù)現(xiàn)性要求很高參數(shù)和模型版本都要寫進(jìn)報告。5.4 讓評測結(jié)果可復(fù)現(xiàn)的隔離策略為了讓結(jié)果可復(fù)現(xiàn)建議從四個方面做隔離。一是數(shù)據(jù)隔離。任務(wù)里的日志、用戶表、天氣數(shù)據(jù)都要用固定測試數(shù)據(jù)不用生產(chǎn)實時數(shù)據(jù)避免外部變化導(dǎo)致結(jié)果不穩(wěn)定。二是環(huán)境隔離。MCP Server 和 Runner 跑在固定容器或虛擬環(huán)境中依賴版本鎖定。至少把requirements.txt和 Python 版本寫入報告。三是隨機性隔離。LLM 采樣有隨機性建議同一任務(wù)跑多次取平均或取最低分并記錄每次結(jié)果。四是緩存隔離。如果工具內(nèi)部訪問數(shù)據(jù)庫或 API要在測試環(huán)境把這些依賴 Mock 掉保證每次調(diào)用返回相同結(jié)果。上面的天氣和用戶數(shù)據(jù)用字典模擬就是這個目的。6. 評測過程中的常見故障定位6.1 排查順序從環(huán)境到代碼再到模型策略評測跑出低分或直接報錯時不要第一時間懷疑模型能力按下面的順序排查MCP Server 是否啟動端口是否正確。tools/list是否能返回工具列表。工具描述和 Schema 是否合理。tools/call是否能正常返回。Runner 是否正確解析返回值。MockPlanner 或真實 LLM 是否輸出預(yù)期動作。評分規(guī)則是否符合任務(wù)語義。這里面有 60% 以上問題出在前四步屬于環(huán)境或工具實現(xiàn)問題而不是模型問題。直接懷疑模型只會讓排查變慢。6.2 高頻問題速查表問題現(xiàn)象常見原因檢查方式處理建議Server 啟動后端口連不上啟動模式不是 HTTP或配置了 stdio看啟動日志確認(rèn)監(jiān)聽地址顯式配置 HTTP endpointtools/list 返回空列表工具裝飾器未注冊或文件沒加載打印 server 日志調(diào)用方法名確認(rèn) import 路徑正確tools/call 返回 -32603工具函數(shù)內(nèi)部拋異常查看 Server stderr 堆棧修復(fù)工具函數(shù)增加異常兜底模型不調(diào)用工具直接給答案工具描述不清晰或 prompt 未說明可用工具查看模型消息歷史補全工具描述在 prompt 中強調(diào)必須調(diào)用工具同一任務(wù)多次跑分?jǐn)?shù)不同模型采樣隨機或數(shù)據(jù)不是固定測試集固定 temperature核對測試數(shù)據(jù)設(shè)置 temperature0固定 seed評分結(jié)果與預(yù)期不符expected 字段寫法不規(guī)范手動跑一次工具返回結(jié)果統(tǒng)一 expected 的類型和格式6.3 一個典型案例tools/list 正常但 tools/call 報錯現(xiàn)象是tools/list能列出get_user_region但調(diào)用時報內(nèi)部錯誤錯誤碼類似-32603。常見原因是工具函數(shù)里讀取的數(shù)據(jù)不存在比如mcp.tool() def get_user_region(user_id: str) - str: user mock_users[user_id] # 直接下標(biāo)訪問key 不存在會拋 KeyError return user[region]當(dāng)模型傳入一個不在 mock 數(shù)據(jù)里的用戶 ID 時函數(shù)直接拋異常錯誤被 MCP 包裝成-32603返回。解決方式是改成mock_users.get(user_id, unknown)并在函數(shù)說明里寫清楚支持的取值范圍。這個案例說明工具函數(shù)本身要有健壯性。評測工具不等于生產(chǎn)工具但它的容錯程度直接影響評測結(jié)果一個不夠健壯的工具會讓模型即使規(guī)劃正確也會失敗。6.4 分?jǐn)?shù)偏低時怎么從日志歸因分?jǐn)?shù)偏低時先看 trace按以下路徑歸因如果動作序列正確但最終答案錯誤檢查工具返回格式和評分邏輯。如果動作序列從一開始就跑偏檢查工具描述、prompt 和模型規(guī)劃能力。如果模型在第 N 步出現(xiàn)重復(fù)調(diào)用同一個工具檢查上下文是否展示了工具結(jié)果。如果出現(xiàn)大量max_steps_exceeded檢查任務(wù)最大步數(shù)設(shè)置是否合理。評測框架最好把 trace 導(dǎo)出成 JSON 文件包含 prompt、每一步模型輸出、工具結(jié)果、最終答案。這樣排查時可以直接回放整個過程而不是憑記憶猜。7. 從本地 Demo 到生產(chǎn)級 Agent 評測最佳實踐與擴展方向7.1 一套可直接使用的評測準(zhǔn)備清單在正式跑一組評測前建議逐項確認(rèn)下面這些內(nèi)容任務(wù)集是否覆蓋不同難度梯度每層至少 3 個任務(wù)。每個任務(wù)的 expected 字段是否唯一、可比較、可自動判斷。MCP Server 是否能穩(wěn)定啟動工具是否都有異常兜底。工具描述是否包含輸入含義、取值范圍、返回值格式。Runner 是否正確記錄動作序列、工具結(jié)果、最終答案和錯誤信息。是否固定模型版本、temperature、max_steps 和隨機種子。是否使用固定測試數(shù)據(jù)避免外部依賴波動。評分規(guī)則是否區(qū)分完全正確、部分正確和錯誤恢復(fù)。是否導(dǎo)出 JSON 軌跡方便失敗歸因。這份清單在發(fā)布評測報告前過一遍能避免大部分“分?jǐn)?shù)不可信”的問題。7.2 生產(chǎn)級評測與本地評測的差異本地 Demo 跑通后進(jìn)入生產(chǎn)環(huán)境差異主要在五個方面一是并發(fā)。真實評測通常同時跑幾十個模型實例MCP Server 要能支持并發(fā)請求不能只用本地單進(jìn)程。二是資源隔離。每個評測任務(wù)使用獨立沙箱數(shù)據(jù)避免任務(wù)間相互污染。三是回歸閾值。模型或 Agent 框架升級后要設(shè)定分?jǐn)?shù)下降閾值比如整體分?jǐn)?shù)下降超過 2% 就阻止發(fā)布。四是版本追蹤。模型版本、工具代碼版本、任務(wù)集版本都要記錄否則無法定位是模型變了還是工具變了。五是安全與審計。工具可能訪問敏感數(shù)據(jù)評測環(huán)境要用完全模擬數(shù)據(jù)并對工具調(diào)用做權(quán)限控制。7.3 可以繼續(xù)深入的方向MCP-Bench 風(fēng)格的評測框架本身還有不少擴展空間。后續(xù)可以加入多輪對話評測讓 Agent 在澄清需求后再行動可以加入多 Agent 協(xié)作場景評測多個 Agent 通過 MCP 工具分工完成復(fù)雜任務(wù)可以在評分中加入語義相似度允許模型用不同表達(dá)給出正確結(jié)果還可以引入人類偏好評估對 Agent 的步驟順序和解釋質(zhì)量做主觀打分。對正在做 Agent 應(yīng)用的團隊來說最值得投入的方向是先把“任務(wù)集 指標(biāo) 軌跡回放”三件套建立起來。任務(wù)集保證有標(biāo)準(zhǔn)可測指標(biāo)保證有量化結(jié)果軌跡回放保證失敗可排查。只要這三件事落地?zé)o論后續(xù)更換模型、增加工具還是調(diào)整 Agent 框架都能用一套穩(wěn)定的評測體系保障質(zhì)量?；氐?MCP-Bench 的核心判斷工具調(diào)用型 Agent 的能力不能靠感覺衡量必須放在復(fù)雜真實任務(wù)里用統(tǒng)一協(xié)議、標(biāo)準(zhǔn)任務(wù)、可復(fù)用指標(biāo)去約束。先跑通最小閉環(huán)再把任務(wù)集做厚、把指標(biāo)做細(xì)這比一開始追求上百個工具的大規(guī)模評測更實際。對剛接觸這個方向的開發(fā)者建議從本文的最小 Runner 開始替換成真實 LLM錄入自己的業(yè)務(wù)任務(wù)再用 trace 分析第一次失敗原因這會比閱讀大量評測論文更快建立手感。 MCP-Bench評測實踐：從零搭建工具調(diào)用型Agent評測環(huán)境
在實際 LLM 項目中Agent 的能力邊界往往不由模型參數(shù)單獨決定而是取決于它能不能在一連串不確定環(huán)境里穩(wěn)定地把外部工具用起來。MCP-Bench 這類以“復(fù)雜真實世界任務(wù)”為對象的工具調(diào)用型 Agent 基準(zhǔn)正是為了回答這個問題而出現(xiàn)的任務(wù)不是簡單問答而是讀取日志、查詢數(shù)據(jù)庫、調(diào)用 API、根據(jù)中間結(jié)果糾正動作的多步流程。協(xié)議層面用 MCP 統(tǒng)一工具接入評估層面用一組可打分、可復(fù)現(xiàn)、可歸因的任務(wù)去測量不同模型和 Agent 框架的實際表現(xiàn)這正是 MCP-Bench 的核心思路。這篇文章以 MCP-Bench 的評測主線展開。先解釋為什么工具調(diào)用型 Agent 需要獨立基準(zhǔn)再拆解 MCP 協(xié)議的工具調(diào)用鏈路與評測任務(wù)設(shè)計要點隨后從零搭建最小可運行評測環(huán)境實現(xiàn)任務(wù)定義、工具執(zhí)行、結(jié)果評分和日志采集最后討論指標(biāo)讀取、高頻故障定位以及把本地 Demo 擴展成生產(chǎn)級評測時該補哪些能力。適合正在做 Agent 評測、準(zhǔn)備接入 MCP 工具或者想在自己項目中量化 LLM 工具調(diào)用質(zhì)量的開發(fā)者閱讀。1. 工具調(diào)用型 Agent 為什么需要獨立的評測基準(zhǔn)1.1 QA 正確率衡量不了“會不會用工具”傳統(tǒng)大模型評測通常把模型當(dāng)作知識問答器給輸入比輸出算正確率。這種模式對事實記憶、推理能力、文本生成質(zhì)量有效但對 Agent 場景不夠。Agent 的產(chǎn)出不是一個靜態(tài)答案而是一串動作序列判斷當(dāng)前缺什么信息決定調(diào)用哪個工具解析返回結(jié)果再決定下一步。同一個任務(wù)兩個模型可能都完成了目標(biāo)但一個用了 3 次工具調(diào)用另一個用了 20 次一個能處理工具返回的異常格式另一個直接卡死。這種差異無法用選擇題正確率體現(xiàn)。所以工具調(diào)用型 Agent 需要獨立基準(zhǔn)。它要測量的是模型在“決策-行動-觀察”循環(huán)中的綜合能力而不是單次生成能力。MCP-Bench 這類基準(zhǔn)把這種循環(huán)固化成標(biāo)準(zhǔn)任務(wù)讓不同模型和框架在同樣條件下跑同樣的流程結(jié)果才有可比性。1.2 復(fù)雜真實世界任務(wù)給 Agent 出的三道難題進(jìn)入真實場景后工具調(diào)用型 Agent 面對的問題通常比教科書示例復(fù)雜得多主要體現(xiàn)為三點。第一上下文碎片化。任務(wù)需要的信息分散在不同文件、數(shù)據(jù)庫、接口里Agent 必須主動拉取不能指望用戶一次性給全。第二工具協(xié)議不統(tǒng)一。團隊里可能有 REST API、數(shù)據(jù)庫連接、命令行腳本、內(nèi)部 SDK如果每個工具都自己定義調(diào)用格式Agent 適配成本非常高。第三失敗難復(fù)現(xiàn)。工具會超時、返回空值、報權(quán)限錯誤Agent 必須能感知并調(diào)整否則同樣的任務(wù)換個環(huán)境就失敗。這些難題意味著評測任務(wù)必須設(shè)計成“真實世界的復(fù)雜度”而不是把多個簡單問答拼在一起。一個合格的工具調(diào)用型 Agent 評測任務(wù)應(yīng)該要求 Agent 自己決定調(diào)用順序、自己判斷結(jié)果正確性、自己處理異常分支。1.3 MCP 和 MCP-Bench 的關(guān)系MCPModel Context Protocol是一個開放協(xié)議用來標(biāo)準(zhǔn)化 LLM 應(yīng)用與外部數(shù)據(jù)源、工具之間的連接方式。在 MCP 生態(tài)里工具提供方只需要按協(xié)議實現(xiàn)一套服務(wù)模型應(yīng)用就能通過統(tǒng)一方式發(fā)現(xiàn)工具、描述參數(shù)、發(fā)起調(diào)用、接收結(jié)果。這解決了 1.2 節(jié)提到的協(xié)議碎片化問題。MCP-Bench 則可以理解成圍繞這種工具調(diào)用模式設(shè)計的評估框架用 MCP 服務(wù)承載待測工具用復(fù)雜的真實任務(wù)驅(qū)動模型行動再用統(tǒng)一評分邏輯判斷模型是否完成了目標(biāo)。需要說明的是不同團隊對 MCP-Bench 的落地方式并不完全一致有的基于公開評測集有的基于內(nèi)部業(yè)務(wù)任務(wù)集但共同點是“MCP 協(xié)議 工具調(diào)用型 Agent 復(fù)雜任務(wù)評分”這個組合。1.4 評測時應(yīng)該關(guān)注的對象跑一個 MCP-Bench 風(fēng)格評測關(guān)注的不是某一次工具調(diào)用有沒有成功而是整條 Agent 鏈路的表現(xiàn)至少包含四層模型層是否理解任務(wù)語義能否把用戶請求拆成工具調(diào)用計劃。協(xié)議層MCP Server 是否正常工具參數(shù)是否符合 Schema返回結(jié)果能否被解析。Agent 框架層是否維護(hù)多輪上下文是否限制最大調(diào)用次數(shù)是否對工具異常有兜底。評測任務(wù)層任務(wù)答案是否明確評分規(guī)則是否覆蓋部分完成的情況任務(wù)是否具備區(qū)分度。如果只盯著“工具有沒有返回結(jié)果”很容易被一次偶發(fā)成功誤導(dǎo)。MCP-Bench 的價值在于把上述每一層都變成可觀測、可評分的對象。2. MCP 工具調(diào)用鏈路與評測任務(wù)的關(guān)鍵設(shè)計點2.1 MCP 的三段式架構(gòu)理解 MCP-Bench 前要先理解 MCP 工具調(diào)用鏈路。MCP 采用三段式結(jié)構(gòu)MCP Host運行 LLM 的應(yīng)用負(fù)責(zé)組織對話流程把模型決策轉(zhuǎn)發(fā)給工具。MCP ClientHost 內(nèi)部連接 Server 的客戶端組件負(fù)責(zé)協(xié)議通信。MCP Server實際執(zhí)行工具的服務(wù)進(jìn)程暴露工具清單并接收調(diào)用請求。調(diào)用鏈路可以概括為用戶在 Host 中發(fā)起任務(wù) - 模型分析后決定調(diào)用某個工具 - Host 通過 Client 向 Server 請求工具執(zhí)行 - Server 返回結(jié)構(gòu)化結(jié)果 - 模型根據(jù)結(jié)果繼續(xù)決策。整個過程是循環(huán)的直到模型認(rèn)為任務(wù)完成或達(dá)到最大輪數(shù)限制。這種結(jié)構(gòu)天然適合評測Server 負(fù)責(zé)提供可復(fù)現(xiàn)的工具環(huán)境Runner 負(fù)責(zé)記錄每一輪決策和結(jié)果任務(wù)集負(fù)責(zé)定義預(yù)期目標(biāo)。評測框架可以把它抽象成“輸入任務(wù) - 循環(huán)工具調(diào)用 - 輸出最終答案 - 對照評分”。2.2 三個核心原語Resources、Prompts、ToolsMCP 給模型應(yīng)用提供了三類能力評測任務(wù)設(shè)計時經(jīng)常涉及原語作用評測中的典型用法Resources向模型提供讀取型數(shù)據(jù)比如文件內(nèi)容、數(shù)據(jù)庫記錄提供任務(wù)背景資料避免把信息全部塞進(jìn) promptPrompts可復(fù)用的提示模板規(guī)范模型如何完成某類操作定義工具調(diào)用說明和輸出格式模板Tools模型可以主動調(diào)用的執(zhí)行型函數(shù)需要參數(shù) Schema作為評測中的被調(diào)用對象記錄調(diào)用軌跡對工具調(diào)用型 Agent 評測來說Tools 是核心。一個 Tool 包含名稱、描述、輸入 Schema 和執(zhí)行邏輯。描述寫得好不好直接影響模型能否正確選擇工具Schema 設(shè)計得清不清楚直接影響參數(shù)填充是否正確。這兩點也是評測中差異最大的變量。2.3 一個多步任務(wù)在 MCP 鏈路中如何執(zhí)行用一個例子說明多步任務(wù)在 MCP 鏈路里的執(zhí)行過程。假設(shè)評測任務(wù)要求 Agent“統(tǒng)計某個服務(wù)日志中出現(xiàn) ERROR 的次數(shù)并判斷錯誤最集中的時間段”。模型會把任務(wù)拆成兩步先調(diào)用read_log工具讀取日志文件再調(diào)用extract_stats工具或自己分析文本。如果設(shè)計成鏈?zhǔn)饺蝿?wù)第二步可能依賴第一步的返回值。實際的協(xié)議消息可以簡化成下面這樣先列出 Server 支持的工具{ jsonrpc: 2.0, id: 1, method: tools/list, params: {} }Server 返回工具描述{ jsonrpc: 2.0, id: 1, result: { tools: [ { name: read_log, description: 讀取指定日志文件返回全部行, inputSchema: { type: object, properties: { path: { type: string } }, required: [path] } } ] } }模型決定調(diào)用工具后發(fā)送tools/call請求{ jsonrpc: 2.0, id: 2, method: tools/call, params: { name: read_log, arguments: { path: logs/app.log } } }Server 返回執(zhí)行結(jié)果{ jsonrpc: 2.0, id: 2, result: { content: [ { type: text, text: ERROR count: 17\n[2025-01-01 00:01:02] ERROR ... } ] } }評測腳本要記錄的就是這些請求和響應(yīng)模型在什么輪次調(diào)用什么工具、傳了什么參數(shù)、拿到什么結(jié)果、最后得出什么結(jié)論。有了這種完整軌跡評分和排錯才有依據(jù)。2.4 評測框架必須采集的四類數(shù)據(jù)一個合格的工具調(diào)用型 Agent 評測框架最少要采集四類數(shù)據(jù)任務(wù)輸入與預(yù)期任務(wù)原始描述、預(yù)期結(jié)果表達(dá)式、允許的最大調(diào)用輪數(shù)。動作序列模型每一步的決策類型、工具名、參數(shù)、對應(yīng)輪次。工具執(zhí)行結(jié)果每個工具的成功狀態(tài)、返回內(nèi)容、耗時、異常信息。最終輸出與評分模型給出的最終答案、任務(wù)得分、扣分項說明。采集這些數(shù)據(jù)不只為給一個分?jǐn)?shù)而是為了讓失敗可以歸因。一個 Agent 任務(wù)失敗可能是模型規(guī)劃錯誤也可能是工具參數(shù) Schema 寫錯還可能是 Server 崩潰。沒有動作序列和工具執(zhí)行日志這幾個原因很難區(qū)分。3. 搭建最小可復(fù)現(xiàn)的評測環(huán)境3.1 依賴與目錄結(jié)構(gòu)推薦使用 Python 3.10 以上版本配合 MCP 官方 SDK 搭建本地評測環(huán)境。依賴安裝命令如下mkdir -p mcp-bench-demo/{tasks,logs,server,runner} cd mcp-bench-demo python -m venv .venv source .venv/bin/activate pip install mcp不同版本的 MCP SDK 在 FastMCP API 上略有差異落地前可以用pip show mcp查看版本再對照官方文檔確認(rèn)接口寫法。下面的例子基于 mcp SDK 1.x 的常見寫法。推薦的目錄結(jié)構(gòu)mcp-bench-demo/ ├── server/ │ └── bench_server.py ├── runner/ │ └── bench_runner.py ├── tasks/ │ └── tasks.json └── logs/ └── app.loglogs 目錄放模擬業(yè)務(wù)日志server 目錄放 MCP Serverrunner 目錄放評測腳本tasks 目錄放任務(wù)集。目錄職責(zé)分開后續(xù)擴展任務(wù)和排查問題都會方便很多。3.2 用 FastMCP 編寫一個帶兩個工具的 Server下面這個 Server 暴露兩個工具一個統(tǒng)計日志關(guān)鍵字次數(shù)一個讀取用戶信息。前者是單步工具后者用于演示鏈?zhǔn)讲樵儭? server/bench_server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(bench-tools) mcp.tool() def count_keyword(log_path: str, keyword: str) - str: 統(tǒng)計指定日志文件中關(guān)鍵字出現(xiàn)的次數(shù)。 Args: log_path: 日志文件路徑例如 logs/app.log keyword: 要統(tǒng)計的關(guān)鍵字例如 ERROR count 0 with open(log_path, r, encodingutf-8) as f: for line in f: if keyword in line: count 1 return str(count) mcp.tool() def get_user_region(user_id: str) - str: 根據(jù)用戶 ID 返回用戶所在地區(qū)。 Args: user_id: 用戶唯一標(biāo)識例如 u-1001 mock_users { u-1001: shenzhen, u-1002: beijing, u-1003: chengdu, } region mock_users.get(user_id, unknown) return region mcp.tool() def get_weather(city: str) - str: 返回指定城市的天氣情況。 Args: city: 城市英文名例如 shenzhen mock_weather { shenzhen: sunny, 28c, beijing: cloudy, 18c, chengdu: rainy, 22c, } return mock_weather.get(city, unknown weather) if __name__ __main__: mcp.run()這個示例中用字典模擬用戶數(shù)據(jù)和天氣數(shù)據(jù)實際項目里可以替換成數(shù)據(jù)庫查詢或外部 API 調(diào)用。三個工具中count_keyword是獨立工具get_user_region和get_weather可以組合成鏈?zhǔn)饺蝿?wù)先查用戶地區(qū)再根據(jù)地區(qū)查天氣。3.3 通過 JSON-RPC 驗證 Server 是否正常啟動 Server 前先用 Python 自帶方式檢查能否加載模塊cd mcp-bench-demo python -c import server.bench_server; print(import ok)如果輸出import ok說明依賴和模塊路徑正常。接著啟動服務(wù)python server/bench_server.py本地 MCP Server 一般通過 stdio 或 HTTP 與客戶端通信。FastMCP 的mcp.run()在不同版本中默認(rèn)傳輸方式不同有的是 stdio有的是 HTTP。為了方便評測腳本調(diào)用可以顯式配置成 HTTP 模式也可以直接讓 Runner 以子進(jìn)程方式啟動 Server。學(xué)習(xí)階段建議先用 HTTP 模式便于用 curl 驗證。如果 Server 以 HTTP 方式運行可以用下面這條命令驗證tools/listcurl -s -X POST http://127.0.0.1:8000/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}}響應(yīng)里能列出三個工具說明 Server 工作正常。這一步很重要因為后面的 Runner 會對 Server 通信結(jié)果做依賴如果 Server 沒起來所有評測都會失敗。3.4 任務(wù)集 JSON 的設(shè)計與示例任務(wù)集是評測的核心資產(chǎn)。設(shè)計任務(wù)時要把任務(wù)描述、最大步數(shù)、預(yù)期結(jié)果校驗方式都定義清楚。下面是一個合適的示例{ tasks: [ { id: task-001, name: 統(tǒng)計 ERROR 日志數(shù)量, prompt: 請統(tǒng)計 logs/app.log 中 ERROR 出現(xiàn)的總次數(shù)直接返回數(shù)字。, max_steps: 3, expected: 17 }, { id: task-002, name: 查詢用戶所在城市天氣, prompt: 用戶 u-1001 想了解自己所在城市的天氣請查詢該用戶的地區(qū)并返回當(dāng)?shù)靥鞖狻? max_steps: 4, expected: sunny, 28c } ] }任務(wù)一測試單工具調(diào)用。任務(wù)二測試鏈?zhǔn)秸{(diào)用模型必須先調(diào)用get_user_region再調(diào)用get_weather。如果模型直接猜測天氣即使答案碰巧正確評測腳本也能根據(jù)動作軌跡判斷它的行為不正確這就是動作序列采集的作用。4. 實現(xiàn)最小 MCP-Bench 評測 Runner4.1 Runner 的整體流程評測 Runner 是整篇文章的核心部分。它讀取任務(wù)集為每個任務(wù)建立一次 Agent 會話循環(huán)執(zhí)行“模型決策 - 工具調(diào)用 - 結(jié)果收集”最后輸出評分和軌跡。流程如下加載 tasks.json。啟動或連接 MCP Server。獲取工具列表緩存到本地。對每個任務(wù)構(gòu)造初始 prompt 并進(jìn)入循環(huán)。每一輪讓規(guī)劃器決定動作類型tool_call或finish。如果是tool_call調(diào)用 MCP Server 并記錄結(jié)果。如果是finish把最終答案交給評分函數(shù)。匯總所有任務(wù)的分?jǐn)?shù)、工具調(diào)用次數(shù)、異常日志。4.2 模型規(guī)劃器抽象本地用固定策略線上替換成真實 LLM為了不依賴具體模型 API Key也為了讓評測框架本身可以先跑通這里定義一個AgentPlanner抽象它只負(fù)責(zé)“根據(jù)當(dāng)前消息歷史生成下一個動作”。本地驗證時用MockPlanner它從任務(wù)配置里讀取預(yù)設(shè)的動作序列模擬一個聽話的 Agent真實評測時把它替換成真實 LLM 調(diào)用即可。# runner/agent_planner.py from abc import ABC, abstractmethod from dataclasses import dataclass, field from typing import Any dataclass class Action: type: str # tool_call or finish tool_name: str arguments: dict field(default_factorydict) answer: str class AgentPlanner(ABC): abstractmethod def next_action(self, messages: list[dict]) - Action: ... class MockPlanner(AgentPlanner): 本地驗證用按 task 中配置的固定動作序列執(zhí)行。 def __init__(self, plan: list[dict]): self.plan plan self.index 0 def next_action(self, messages: list[dict]) - Action: if self.index len(self.plan): return Action(typefinish, answerNO_ANSWER) step self.plan[self.index] self.index 1 if step[type] tool_call: return Action( typetool_call, tool_namestep[tool_name], argumentsstep[arguments], ) return Action(typefinish, answerstep[answer])真實項目里替換next_action時只需要把messages發(fā)給大模型解析模型返回的 tool_calls 和最終文本轉(zhuǎn)成Action。這個替換對 Runner 的其他部分完全透明。4.3 客戶端封裝連接 Server、列出工具、調(diào)用工具下面封裝一個 MCPClient負(fù)責(zé)與 Server 通信。如果使用官方 SDK可以直接用客戶端類這里為了展示原理寫一個基于 requests 的簡潔版本方便閱讀和調(diào)試。# runner/mcp_client.py import requests class MCPClient: def __init__(self, endpoint: str): self.endpoint endpoint self.tools: dict {} def list_tools(self) - dict: payload { jsonrpc: 2.0, id: 1, method: tools/list, params: {}, } resp requests.post(self.endpoint, jsonpayload, timeout10) resp.raise_for_status() data resp.json() tools data[result][tools] self.tools {t[name]: t for t in tools} return self.tools def call_tool(self, name: str, arguments: dict) - dict: payload { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: name, arguments: arguments, }, } resp requests.post(self.endpoint, jsonpayload, timeout15) resp.raise_for_status() data resp.json() if error in data: return {ok: False, error: data[error]} content data[result][content] text for item in content: if item.get(type) text: text item.get(text, ) return {ok: True, text: text}代碼里把tools/list的結(jié)果緩存到self.tools后續(xù)評分統(tǒng)計可以知道模型調(diào)用的工具是否真實存在。call_tool返回統(tǒng)一結(jié)構(gòu)無論成功失敗都包含可觀測的結(jié)果字段。4.4 任務(wù)執(zhí)行循環(huán)與結(jié)果收集主執(zhí)行循環(huán)記錄每一步動作、工具返回值和異常信息最后把完整軌跡交給評分函數(shù)。# runner/bench_runner.py import json from agent_planner import MockPlanner from mcp_client import MCPClient def run_single_task(client: MCPClient, task: dict, planner: AgentPlanner): max_steps task.get(max_steps, 5) messages [{role: user, content: task[prompt]}] trace { task_id: task[id], steps: [], final_answer: , tool_calls: 0, errors: [], } for step_index in range(max_steps): try: action planner.next_action(messages) except Exception as exc: trace[errors].append(fplanner_error: {exc}) break if action.type finish: trace[final_answer] action.answer return trace if action.type tool_call: trace[tool_calls] 1 result client.call_tool(action.tool_name, action.arguments) step_record { step: step_index 1, action: tool_call, tool_name: action.tool_name, arguments: action.arguments, result: result, } trace[steps].append(step_record) if not result.get(ok): trace[errors].append( ftool_error: {action.tool_name} - {result.get(error)} ) messages.append({ role: tool, content: json.dumps(result, ensure_asciiFalse), }) trace[errors].append(max_steps_exceeded) return trace注意這里把每一步的工具結(jié)果放進(jìn)了messages目的和真實 MCP 鏈路一致模型需要看到工具返回結(jié)果才能決定下一步。評測框架也應(yīng)該保留這些消息便于后續(xù)分析模型決策邏輯。4.5 評分函數(shù)與運行輸出評分函數(shù)需要平衡“完成正確性”和“過程效率”。下面是一個簡單但可擴展的版本def score_trace(task: dict, trace: dict) - float: score 0.0 expected task.get(expected) actual trace.get(final_answer, ).strip() if actual expected: score 1.0 elif expected in actual: score 0.6 else: score 0.0 tool_calls trace.get(tool_calls, 0) max_steps task.get(max_steps, 5) efficiency_penalty min(tool_calls / (max_steps * 2), 0.3) score - efficiency_penalty if trace.get(errors): score - 0.2 return round(max(score, 0.0), 2) def run_all(tasks_path: str, endpoint: str): with open(tasks_path, r, encodingutf-8) as f: tasks json.load(f)[tasks] client MCPClient(endpoint) client.list_tools() report [] for task in tasks: plan [ {type: tool_call, tool_name: count_keyword, arguments: {log_path: logs/app.log, keyword: ERROR}}, {type: finish, answer: 17}, ] if task[id] task-002: plan [ {type: tool_call, tool_name: get_user_region, arguments: {user_id: u-1001}}, {type: tool_call, tool_name: get_weather, arguments: {city: shenzhen}}, {type: finish, answer: sunny, 28c}, ] planner MockPlanner(plan) trace run_single_task(client, task, planner) score score_trace(task, trace) report.append({task_id: task[id], score: score, trace: trace}) for item in report: print(json.dumps({ task_id: item[task_id], score: item[score], tool_calls: item[trace][tool_calls], final_answer: item[trace][final_answer], }, ensure_asciiFalse)) if __name__ __main__: run_all(tasks/tasks.json, http://127.0.0.1:8000/mcp)運行后預(yù)期輸出{task_id: task-001, score: 1.0, tool_calls: 1, final_answer: 17} {task_id: task-002, score: 1.0, tool_calls: 2, final_answer: sunny, 28c}當(dāng)模型規(guī)劃正確、工具實現(xiàn)正確時兩個任務(wù)都能拿滿分。真實評測中MockPlanner 會被替換成 LLM分?jǐn)?shù)就會出現(xiàn)差異這時候就需要看 trace 里的每一步判斷是規(guī)劃錯誤還是工具錯誤。5. 評測指標(biāo)、參數(shù)與任務(wù)梯度結(jié)果不是跑出分?jǐn)?shù)就結(jié)束5.1 核心指標(biāo)怎么算、怎么用MCP-Bench 類評測不能只看一個總分建議把指標(biāo)拆開每個指標(biāo)對應(yīng)一類能力問題指標(biāo)計算方式反映的問題任務(wù)成功率完全正確任務(wù)數(shù) / 總?cè)蝿?wù)數(shù)基礎(chǔ)完成能力任務(wù)完成度各任務(wù)得分加權(quán)平均部分完成能力平均工具調(diào)用數(shù)工具調(diào)用總次數(shù) / 任務(wù)數(shù)規(guī)劃效率無效調(diào)用率返回錯誤或空結(jié)果的調(diào)用次數(shù) / 總調(diào)用次數(shù)工具描述和模型理解質(zhì)量異?；謴?fù)率出錯后仍完成任務(wù)數(shù) / 出錯任務(wù)數(shù)魯棒性最終答案命中率最終答案包含預(yù)期關(guān)鍵內(nèi)容的任務(wù)占比結(jié)果可靠性單一成功率會掩蓋過程問題。比如一個 Agent 靠亂猜答案碰巧命中成功率很高但工具基本沒用這就不是合格的工具調(diào)用 Agent。所以評測一定要結(jié)合動作軌跡查看不能只看最終分?jǐn)?shù)。5.2 任務(wù)梯度決定評測區(qū)分度評測任務(wù)不能全是“讀一個文件返回數(shù)字”這種簡單任務(wù)也不建議一上來就是十幾個工具的長鏈路任務(wù)。建議劃分難度梯度基礎(chǔ)層單工具調(diào)用直接返回結(jié)果例如統(tǒng)計關(guān)鍵字。鏈?zhǔn)綄觾蓚€或以上工具串聯(lián)后一個工具依賴前一個結(jié)果。條件層根據(jù)工具返回內(nèi)容決定調(diào)用哪個分支工具。異常層工具會返回空值、錯誤碼或超時考察模型恢復(fù)能力。并行層多個獨立工具需要分批調(diào)用再把結(jié)果匯總。配置任務(wù)時每層至少 3 到 5 個任務(wù)。如果某個模型在基礎(chǔ)層滿分、鏈?zhǔn)綄拥梅值驼f明它工具理解能力沒問題但多步規(guī)劃能力弱如果在鏈?zhǔn)綄右部梢?、異常層下降明顯說明它對錯誤處理缺少兜底策略。這種梯度化分析比一個總分?jǐn)?shù)更有診斷價值。5.3 影響評測結(jié)果的四個關(guān)鍵參數(shù)評測時容易忽略參數(shù)對結(jié)果的干擾。下面四個參數(shù)對結(jié)果影響最大建議統(tǒng)一記錄參數(shù)默認(rèn)值參考調(diào)大影響調(diào)小影響溫度 temperature0 到 0.2動作更多樣但更容易出現(xiàn)無效調(diào)用結(jié)果更穩(wěn)定但可能缺少探索最大步數(shù) max_steps5 到 10給長鏈路任務(wù)更多機會但掩蓋低效問題對長任務(wù)不友好容易截斷工具描述長度一到三句模型更好理解但會占用上下文描述過短時模型容易選錯工具上下文窗口模型按模型實際支持配置能容納更多中間結(jié)果但成本上升長鏈路任務(wù)容易截斷歷史評測報告里應(yīng)該記錄這些參數(shù)否則兩個團隊跑同一個任務(wù)集因為溫度或最大步數(shù)不同分?jǐn)?shù)完全不同結(jié)果無法對比。MCP-Bench 風(fēng)格評測對可復(fù)現(xiàn)性要求很高參數(shù)和模型版本都要寫進(jìn)報告。5.4 讓評測結(jié)果可復(fù)現(xiàn)的隔離策略為了讓結(jié)果可復(fù)現(xiàn)建議從四個方面做隔離。一是數(shù)據(jù)隔離。任務(wù)里的日志、用戶表、天氣數(shù)據(jù)都要用固定測試數(shù)據(jù)不用生產(chǎn)實時數(shù)據(jù)避免外部變化導(dǎo)致結(jié)果不穩(wěn)定。二是環(huán)境隔離。MCP Server 和 Runner 跑在固定容器或虛擬環(huán)境中依賴版本鎖定。至少把requirements.txt和 Python 版本寫入報告。三是隨機性隔離。LLM 采樣有隨機性建議同一任務(wù)跑多次取平均或取最低分并記錄每次結(jié)果。四是緩存隔離。如果工具內(nèi)部訪問數(shù)據(jù)庫或 API要在測試環(huán)境把這些依賴 Mock 掉保證每次調(diào)用返回相同結(jié)果。上面的天氣和用戶數(shù)據(jù)用字典模擬就是這個目的。6. 評測過程中的常見故障定位6.1 排查順序從環(huán)境到代碼再到模型策略評測跑出低分或直接報錯時不要第一時間懷疑模型能力按下面的順序排查MCP Server 是否啟動端口是否正確。tools/list是否能返回工具列表。工具描述和 Schema 是否合理。tools/call是否能正常返回。Runner 是否正確解析返回值。MockPlanner 或真實 LLM 是否輸出預(yù)期動作。評分規(guī)則是否符合任務(wù)語義。這里面有 60% 以上問題出在前四步屬于環(huán)境或工具實現(xiàn)問題而不是模型問題。直接懷疑模型只會讓排查變慢。6.2 高頻問題速查表問題現(xiàn)象常見原因檢查方式處理建議Server 啟動后端口連不上啟動模式不是 HTTP或配置了 stdio看啟動日志確認(rèn)監(jiān)聽地址顯式配置 HTTP endpointtools/list 返回空列表工具裝飾器未注冊或文件沒加載打印 server 日志調(diào)用方法名確認(rèn) import 路徑正確tools/call 返回 -32603工具函數(shù)內(nèi)部拋異常查看 Server stderr 堆棧修復(fù)工具函數(shù)增加異常兜底模型不調(diào)用工具直接給答案工具描述不清晰或 prompt 未說明可用工具查看模型消息歷史補全工具描述在 prompt 中強調(diào)必須調(diào)用工具同一任務(wù)多次跑分?jǐn)?shù)不同模型采樣隨機或數(shù)據(jù)不是固定測試集固定 temperature核對測試數(shù)據(jù)設(shè)置 temperature0固定 seed評分結(jié)果與預(yù)期不符expected 字段寫法不規(guī)范手動跑一次工具返回結(jié)果統(tǒng)一 expected 的類型和格式6.3 一個典型案例tools/list 正常但 tools/call 報錯現(xiàn)象是tools/list能列出get_user_region但調(diào)用時報內(nèi)部錯誤錯誤碼類似-32603。常見原因是工具函數(shù)里讀取的數(shù)據(jù)不存在比如mcp.tool() def get_user_region(user_id: str) - str: user mock_users[user_id] # 直接下標(biāo)訪問key 不存在會拋 KeyError return user[region]當(dāng)模型傳入一個不在 mock 數(shù)據(jù)里的用戶 ID 時函數(shù)直接拋異常錯誤被 MCP 包裝成-32603返回。解決方式是改成mock_users.get(user_id, unknown)并在函數(shù)說明里寫清楚支持的取值范圍。這個案例說明工具函數(shù)本身要有健壯性。評測工具不等于生產(chǎn)工具但它的容錯程度直接影響評測結(jié)果一個不夠健壯的工具會讓模型即使規(guī)劃正確也會失敗。6.4 分?jǐn)?shù)偏低時怎么從日志歸因分?jǐn)?shù)偏低時先看 trace按以下路徑歸因如果動作序列正確但最終答案錯誤檢查工具返回格式和評分邏輯。如果動作序列從一開始就跑偏檢查工具描述、prompt 和模型規(guī)劃能力。如果模型在第 N 步出現(xiàn)重復(fù)調(diào)用同一個工具檢查上下文是否展示了工具結(jié)果。如果出現(xiàn)大量max_steps_exceeded檢查任務(wù)最大步數(shù)設(shè)置是否合理。評測框架最好把 trace 導(dǎo)出成 JSON 文件包含 prompt、每一步模型輸出、工具結(jié)果、最終答案。這樣排查時可以直接回放整個過程而不是憑記憶猜。7. 從本地 Demo 到生產(chǎn)級 Agent 評測最佳實踐與擴展方向7.1 一套可直接使用的評測準(zhǔn)備清單在正式跑一組評測前建議逐項確認(rèn)下面這些內(nèi)容任務(wù)集是否覆蓋不同難度梯度每層至少 3 個任務(wù)。每個任務(wù)的 expected 字段是否唯一、可比較、可自動判斷。MCP Server 是否能穩(wěn)定啟動工具是否都有異常兜底。工具描述是否包含輸入含義、取值范圍、返回值格式。Runner 是否正確記錄動作序列、工具結(jié)果、最終答案和錯誤信息。是否固定模型版本、temperature、max_steps 和隨機種子。是否使用固定測試數(shù)據(jù)避免外部依賴波動。評分規(guī)則是否區(qū)分完全正確、部分正確和錯誤恢復(fù)。是否導(dǎo)出 JSON 軌跡方便失敗歸因。這份清單在發(fā)布評測報告前過一遍能避免大部分“分?jǐn)?shù)不可信”的問題。7.2 生產(chǎn)級評測與本地評測的差異本地 Demo 跑通后進(jìn)入生產(chǎn)環(huán)境差異主要在五個方面一是并發(fā)。真實評測通常同時跑幾十個模型實例MCP Server 要能支持并發(fā)請求不能只用本地單進(jìn)程。二是資源隔離。每個評測任務(wù)使用獨立沙箱數(shù)據(jù)避免任務(wù)間相互污染。三是回歸閾值。模型或 Agent 框架升級后要設(shè)定分?jǐn)?shù)下降閾值比如整體分?jǐn)?shù)下降超過 2% 就阻止發(fā)布。四是版本追蹤。模型版本、工具代碼版本、任務(wù)集版本都要記錄否則無法定位是模型變了還是工具變了。五是安全與審計。工具可能訪問敏感數(shù)據(jù)評測環(huán)境要用完全模擬數(shù)據(jù)并對工具調(diào)用做權(quán)限控制。7.3 可以繼續(xù)深入的方向MCP-Bench 風(fēng)格的評測框架本身還有不少擴展空間。后續(xù)可以加入多輪對話評測讓 Agent 在澄清需求后再行動可以加入多 Agent 協(xié)作場景評測多個 Agent 通過 MCP 工具分工完成復(fù)雜任務(wù)可以在評分中加入語義相似度允許模型用不同表達(dá)給出正確結(jié)果還可以引入人類偏好評估對 Agent 的步驟順序和解釋質(zhì)量做主觀打分。對正在做 Agent 應(yīng)用的團隊來說最值得投入的方向是先把“任務(wù)集 指標(biāo) 軌跡回放”三件套建立起來。任務(wù)集保證有標(biāo)準(zhǔn)可測指標(biāo)保證有量化結(jié)果軌跡回放保證失敗可排查。只要這三件事落地?zé)o論后續(xù)更換模型、增加工具還是調(diào)整 Agent 框架都能用一套穩(wěn)定的評測體系保障質(zhì)量?；氐?MCP-Bench 的核心判斷工具調(diào)用型 Agent 的能力不能靠感覺衡量必須放在復(fù)雜真實任務(wù)里用統(tǒng)一協(xié)議、標(biāo)準(zhǔn)任務(wù)、可復(fù)用指標(biāo)去約束。先跑通最小閉環(huán)再把任務(wù)集做厚、把指標(biāo)做細(xì)這比一開始追求上百個工具的大規(guī)模評測更實際。對剛接觸這個方向的開發(fā)者建議從本文的最小 Runner 開始替換成真實 LLM錄入自己的業(yè)務(wù)任務(wù)再用 trace 分析第一次失敗原因這會比閱讀大量評測論文更快建立手感。