戰(zhàn)：大模型工具接入原理、選型與避坑指南)
大模型的工具調(diào)用Function Calling和MCPModel Context Protocol是這兩年做AI應(yīng)用繞不開的兩個(gè)詞。很多人花了不少時(shí)間把API文檔翻了個(gè)遍可真到自己寫代碼的時(shí)候還是會(huì)卡在幾個(gè)關(guān)鍵問題上工具描述到底怎么寫模型才不犯迷糊MCP服務(wù)器和普通工具注冊(cè)到底有什么區(qū)別兩套方案到底什么時(shí)候選哪個(gè)這篇文章我打算把這些年實(shí)際踩過的坑、驗(yàn)證過的方法連同原理一起拆開講清楚。這篇文章適合正在做智能體Agent、AI助手、自動(dòng)化流程的同學(xué)參考也適合那些剛把大模型API調(diào)通、準(zhǔn)備給模型裝上“手腳”的開發(fā)者。里面不會(huì)只丟概念而是給出能直接抄作業(yè)的結(jié)構(gòu)、代碼思路和排查方案。1. 工具調(diào)用的整體思路為什么模型需要“手腳”1.1 模型不是只會(huì)聊天但它確實(shí)做不了“動(dòng)作”先想一個(gè)基本問題大模型本身能做什么它能理解語義、生成文本、總結(jié)信息、改寫代碼但本質(zhì)上它只是一個(gè)“預(yù)測(cè)下一個(gè)詞”的機(jī)器。你說“幫我查一下這周的天氣順便訂個(gè)會(huì)議室”模型即使理解這句話也沒辦法自己去訪問天氣接口更不可能去操作你的會(huì)議系統(tǒng)。要讓模型具備行動(dòng)能力就得在模型外面掛一層“工具層”。我們定義好一批函數(shù)或接口然后讓模型在需要的時(shí)候主動(dòng)選擇調(diào)用哪個(gè)、傳什么參數(shù)再把工具返回的結(jié)果交給模型繼續(xù)處理。這整個(gè)鏈路就是大家常說的工具調(diào)用。最早的做法非常簡單粗暴把工具的描述連同一個(gè)“輸出JSON格式”的指令硬塞進(jìn)提示詞里讓模型把“想調(diào)用的函數(shù)名參數(shù)”以JSON文本吐出來然后我們自己去解析。這套方案最大的問題是模型經(jīng)常輸出格式不穩(wěn)定的JSON函數(shù)名偶爾會(huì)憑空捏造參數(shù)類型也可能對(duì)不上。后來主流大模型API陸續(xù)推出了結(jié)構(gòu)化的函數(shù)調(diào)用能力也就是Function Calling模型不再輸出“看起來像JSON的字符串”而是直接返回結(jié)構(gòu)化的工具調(diào)用對(duì)象從協(xié)議層面解決了格式問題。1.2 MCP想解決的是另一個(gè)問題Function Calling解決的是“模型和工具之間的通信格式”但它沒解決“工具怎么接入”的問題。每個(gè)工具都要單獨(dú)適配每個(gè)應(yīng)用都要自己寫一套工具注冊(cè)、鑒權(quán)、參數(shù)校驗(yàn)的代碼。做過三四個(gè)Agent項(xiàng)目就會(huì)發(fā)現(xiàn)光是把不同的內(nèi)部系統(tǒng)、外部API一個(gè)個(gè)接進(jìn)來就夠?qū)憥浊心z水代碼。MCP的定位就是一個(gè)標(biāo)準(zhǔn)化的“工具接入層”。它定義了應(yīng)用Host、客戶端Client和工具服務(wù)端Server之間的通信協(xié)議。你把一個(gè)數(shù)據(jù)源或工具封裝成一個(gè)MCP Server任何支持MCP的客戶端都能直接發(fā)現(xiàn)它、調(diào)用它不需要為每個(gè)應(yīng)用重復(fù)改代碼。類比一下如果Function Calling是“統(tǒng)一了打電話的接線術(shù)語”MCP就是“統(tǒng)一了電話線接口、撥號(hào)規(guī)則和電話號(hào)碼簿格式還制定了電話亭的尺寸”。兩者解決的問題層次不同。從實(shí)際選型來看目前比較合理的思路是這樣的方案解決的問題適配場(chǎng)景接入成本提示詞JSON解析模型輸出函數(shù)調(diào)用意圖臨時(shí)演示、快速驗(yàn)證、不方便改API的舊系統(tǒng)最低但穩(wěn)定性差Function Calling結(jié)構(gòu)化返回工具調(diào)用指令需要穩(wěn)定、可靠地調(diào)用少量工具的應(yīng)用低主流API都支持MCP多工具、多數(shù)據(jù)源統(tǒng)一接入與復(fù)用復(fù)雜Agent、企業(yè)數(shù)據(jù)中臺(tái)、需要生態(tài)復(fù)用的場(chǎng)景偏高需要封裝服務(wù)2. Function Calling實(shí)戰(zhàn)拆解從原理到可落地的調(diào)用流程2.1 核心三要素tools參數(shù)、工具描述、兩輪往返Function Calling的整個(gè)機(jī)制可以濃縮成三件事讓模型知道有哪些工具、讓模型決定調(diào)哪個(gè)、把結(jié)果反饋給模型。每個(gè)環(huán)節(jié)都有對(duì)應(yīng)的參數(shù)和代碼結(jié)構(gòu)。第一件事叫“工具注冊(cè)”。在API請(qǐng)求體里用tools參數(shù)列出所有可用的工具每個(gè)工具要包含type一般是function、function.name、function.description和function.parameters。這個(gè)parameters用的是JSON Schema格式相當(dāng)于你把工具的“說明書”喂給模型看。一個(gè)典型的工具定義長這樣{ type: function, function: { name: get_weather, description: 查詢指定城市的實(shí)時(shí)天氣和未來三天的預(yù)報(bào)參數(shù)city為城市名稱例如北京、上海、廣州, parameters: { type: object, properties: { city: { type: string, description: 要查詢的城市名稱 } }, required: [city] } } }第二件事是模型“做決定”。你把用戶消息和tools列表一起發(fā)給模型模型如果判斷需要調(diào)用工具返回的響應(yīng)里會(huì)帶一個(gè)tool_calls數(shù)組里面包含函數(shù)名name和參數(shù)arguments。注意這個(gè)arguments雖然是字符串但格式是可控的結(jié)構(gòu)化JSON不像早期提示詞方案那樣需要在一大段對(duì)話文本里“大海撈針”。第三件事是“結(jié)果回傳”。工具執(zhí)行完以后你要把結(jié)果以role: tool的消息返回給模型并附上對(duì)應(yīng)的tool_call_id。模型拿到工具結(jié)果后才能生成最終的自然語言回答。整個(gè)過程需要兩次或更多次請(qǐng)求通常叫“兩輪往返”。2.2 一個(gè)完整的調(diào)用流程示例我用一段接近真實(shí)項(xiàng)目的代碼來展示這個(gè)流程。為了不依賴某個(gè)特定SDK這里用最通用的HTTP請(qǐng)求結(jié)構(gòu)說明import json import requests # 第一步構(gòu)造請(qǐng)求帶上工具定義和用戶問題 payload { model: your-model-name, messages: [ {role: user, content: 北京今天適合出門嗎我想知道明天會(huì)不會(huì)下雨} ], tools: [ { type: function, function: { name: get_weather, description: 查詢指定城市的實(shí)時(shí)天氣和未來三天的預(yù)報(bào), parameters: { type: object, properties: { city: {type: string, description: 城市名稱} }, required: [city] } } } ], tool_choice: auto } resp requests.post(https://api.example.com/v1/chat/completions, headers{Authorization: Bearer YOUR_API_KEY}, jsonpayload) data resp.json() assistant_message data[choices][0][message] # 第二步判斷模型是否需要調(diào)用工具 if assistant_message.get(tool_calls): tool_calls assistant_message[tool_calls] # 這里假設(shè)只處理一個(gè)工具調(diào)用實(shí)際場(chǎng)景需要循環(huán)執(zhí)行 call tool_calls[0] fn_name call[function][name] fn_args json.loads(call[function][arguments]) if fn_name get_weather: # 執(zhí)行真實(shí)工具調(diào)用天氣接口 result real_weather_api(fn_args[city]) # 第三步把工具結(jié)果回傳給模型繼續(xù)生成回答 messages payload[messages] messages.append({ role: assistant, content: None, tool_calls: tool_calls }) messages.append({ role: tool, tool_call_id: call[id], content: json.dumps(result, ensure_asciiFalse) }) final_payload { model: your-model-name, messages: messages, tools: payload[tools] } final_resp requests.post(https://api.example.com/v1/chat/completions, headers{Authorization: Bearer YOUR_API_KEY}, jsonfinal_payload) final_data final_resp.json() answer final_data[choices][0][message][content] print(answer)這段代碼看起來簡單但實(shí)際項(xiàng)目里需要處理的細(xì)節(jié)比這個(gè)多得多多個(gè)工具并行調(diào)用、工具執(zhí)行異常、超時(shí)、結(jié)果太長、參數(shù)校驗(yàn)失敗……我后面匯到問題清單里統(tǒng)一講。2.3 工具描述怎么寫模型才不會(huì)亂調(diào)這是Function Calling里最容易出問題的地方。很多同學(xué)把description寫得特別簡單類似“查詢天氣”結(jié)果模型經(jīng)常搞不清楚要填什么參數(shù)、返回什么格式。我總結(jié)出了一套描述寫法核心是“四個(gè)說清”說清工具用途不要只寫“獲取庫存”要寫“查詢指定SKU在當(dāng)前倉位的實(shí)時(shí)庫存數(shù)量返回在庫數(shù)和可售數(shù)”說清每個(gè)參數(shù)的含義city這個(gè)字段要說明格式比如“城市中文名例如杭州、成都”說清參數(shù)的限制條件比如“日期格式為YYYY-MM-DD不得早于今天”說清返回結(jié)果的格式比如“返回JSON包含字段temperature和humidity溫度單位為攝氏度”打個(gè)比方工具描述就是給模型看的“產(chǎn)品說明書”說明書寫得越清楚模型這個(gè)“用戶”就越不會(huì)用錯(cuò)。而且描述文字本身也會(huì)參與模型token計(jì)算太長浪費(fèi)太短誤事需要反復(fù)打磨到一個(gè)平衡點(diǎn)。2.4 工具調(diào)用的幾個(gè)關(guān)鍵參數(shù)和進(jìn)階玩法在實(shí)際項(xiàng)目里有下面幾個(gè)參數(shù)值得專門研究。tool_choice參數(shù)控制模型調(diào)用工具的“自由度”。默認(rèn)auto表示模型自己決定調(diào)不調(diào)設(shè)為required可以強(qiáng)制模型必須調(diào)用至少一個(gè)工具適合那種“這一步必須操作某個(gè)系統(tǒng)”的場(chǎng)景直接指定某個(gè)函數(shù)名{type: function, function: {name: xxx}}則相當(dāng)于強(qiáng)制走某一條工具路徑。parallel_tool_calls參數(shù)控制并行調(diào)用。模型在一次回答中可以返回多個(gè)工具調(diào)用比如“查天氣設(shè)置提醒”這類沒有依賴關(guān)系的動(dòng)作可以一次性返回兩個(gè)tool_calls。對(duì)于延遲敏感的Agent應(yīng)用這個(gè)能力非常有用。需要強(qiáng)調(diào)的是并行調(diào)用不代表結(jié)果可以亂給每個(gè)tool_call要對(duì)應(yīng)一個(gè)tool_call_id返回的時(shí)候需要一一匹配。還有一個(gè)很多人忽略的點(diǎn)工具返回的content最好是結(jié)構(gòu)化的JSON字符串而不是一段人話描述。比如工具做完了“發(fā)起退款”你返回{status: success, refund_id: R12345}模型就能基于這個(gè)結(jié)果生成流暢的回復(fù)。如果你返回“退款成功了哈單號(hào)是R12345”模型雖然也能讀但遇到復(fù)雜的多步推理任務(wù)結(jié)構(gòu)化結(jié)果讓它做后續(xù)判斷更準(zhǔn)確。3. MCP實(shí)戰(zhàn)拆解把工具變成標(biāo)準(zhǔn)化的服務(wù)3.1 MCP架構(gòu)速覽Host、Client、Server各司其職MCP的架構(gòu)里主要有三個(gè)角色Host是用戶正在使用的AI應(yīng)用比如一個(gè)桌面客戶端Client在Host內(nèi)部負(fù)責(zé)與Server建立連接Server是提供工具、數(shù)據(jù)源的一方可以運(yùn)行在本地也可以部署在遠(yuǎn)程。每次工具調(diào)用的大致流程是Client啟動(dòng)時(shí)向Server發(fā)送initialize請(qǐng)求完成握手Server返回自己支持的協(xié)議版本和服務(wù)器信息接著Client調(diào)用tools/list方法拿到一批工具的定義當(dāng)Agent需要執(zhí)行某個(gè)動(dòng)作時(shí)Client調(diào)用tools/call方法傳入工具名和參數(shù)Server執(zhí)行完返回結(jié)果。這套機(jī)制和Function Calling很像區(qū)別在于它的發(fā)現(xiàn)、調(diào)用、參數(shù)傳遞全是標(biāo)準(zhǔn)化協(xié)議而且不綁定具體模型廠商。對(duì)于沒有接觸過MCP的人來說可以把它想象成一個(gè)“USB接口標(biāo)準(zhǔn)”以前每個(gè)設(shè)備都要用自己的充電線現(xiàn)在有了統(tǒng)一接口任何支持這個(gè)標(biāo)準(zhǔn)的設(shè)備插上就能用。MCP Server就是那個(gè)“設(shè)備”AI應(yīng)用就是那個(gè)“電腦”。3.2 用FastMCP實(shí)現(xiàn)一個(gè)最小可用的MCP服務(wù)器目前最順手的方式是用官方Python SDK里的FastMCP類。下面是一個(gè)包含兩個(gè)工具的迷你服務(wù)器能在五分鐘內(nèi)跑起來from mcp.server.fastmcp import FastMCP import json # 創(chuàng)建一個(gè)MCP服務(wù)器實(shí)例名稱會(huì)顯示在客戶端列表里 mcp FastMCP(namedemo-tools-server) mcp.tool() def get_stock_price(symbol: str) - str: 查詢指定股票代碼的最新價(jià)格。 Args: symbol: 股票代碼如 AAPL、MSFT、600519 # 實(shí)際項(xiàng)目里這里替換成真實(shí)的行情接口 data {symbol: symbol, price: 123.45, currency: CNY} return json.dumps(data, ensure_asciiFalse) mcp.tool() def send_message(phone_number: str, content: str) - str: 發(fā)送一條短信通知。 Args: phone_number: 接收號(hào)碼11位手機(jī)號(hào) content: 短信內(nèi)容長度不超過70字 # 實(shí)際項(xiàng)目里這里替換成真實(shí)的短信服務(wù)商接口 return json.dumps({status: ok, message_id: MSG123456}) if __name__ __main__: mcp.run()注意這里有個(gè)現(xiàn)在很多新手還不熟悉的點(diǎn)mcp.tool()裝飾器會(huì)自動(dòng)從函數(shù)的類型注解和函數(shù)文檔里生成JSON Schema。也就是說函數(shù)簽名里的symbol: str和文檔字符串的Args說明最終會(huì)變成tools/list返回的inputSchema。這意味著寫好一個(gè)函數(shù)就相當(dāng)于定義好了一個(gè)工具不需要像Function Calling那樣單獨(dú)維護(hù)一份JSON Schema。不過這也帶來一個(gè)隱藏問題很多Python函數(shù)用Union、Literal、List這些類型時(shí)FastMCP能智能轉(zhuǎn)化但如果函數(shù)里有復(fù)雜自定義類型它會(huì)自動(dòng)把類型轉(zhuǎn)成object參數(shù)描述就丟失了。遇到這種情況可以用Pydantic的Field來補(bǔ)充字段描述保持工具定義的質(zhì)量。3.3 傳輸方式的選擇stdio還是Streamable HTTPMCP支持不同的傳輸通道最常見的兩種是本地場(chǎng)景的stdio和跨服務(wù)的Streamable HTTP。mcp.run()默認(rèn)走stdio模式。在這種方式下Client啟動(dòng)一個(gè)子進(jìn)程來運(yùn)行Server腳本通過標(biāo)準(zhǔn)輸入輸出傳遞JSON-RPC消息。這種方式的好處是零網(wǎng)絡(luò)配置、啟動(dòng)快很適合桌面端應(yīng)用和本地調(diào)試。缺點(diǎn)是Server和Client必須部署在同一臺(tái)機(jī)器上跨進(jìn)程通信不好做權(quán)限隔離。如果MCP Server要提供給多個(gè)遠(yuǎn)程客戶端使用就得走Streamable HTTP模式。通常做法是用一個(gè)Web框架比如FastAPI包一層或者直接用SDK提供的StreamableHTTPTransport。這種模式需要額外處理鑒權(quán)、跨域和并發(fā)問題但好處是服務(wù)可以復(fù)用、集中部署、統(tǒng)一升級(jí)。我自己在項(xiàng)目里一般按這個(gè)規(guī)則選只在本地給某個(gè)單一工具用選stdio如果Server要給多個(gè)不同應(yīng)用共享或者要部署到服務(wù)器上直接上HTTP模式。3.4 客戶端接入MCP Server的完整步驟接入MCP的客戶端端目前主流做法是用不同語言的SDK。以Python為例連接一個(gè)stdio模式的Server大致需要四步創(chuàng)建session、初始化連接、列出工具、調(diào)用工具。import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 1. 啟動(dòng)MCP Server進(jìn)程 server_params StdioServerParameters( commandpython, args[demo_tools_server.py], envNone ) # 2. 建立stdio通信管道并創(chuàng)建會(huì)話 async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 3. 完成握手初始化 init_result await session.initialize() print(fConnected to: {init_result.serverInfo}) # 4. 列出所有工具 tools await session.list_tools() print(Available tools:, [tool.name for tool in tools.tools]) # 5. 調(diào)用指定工具 result await session.call_tool( nameget_stock_price, arguments{symbol: 600519} ) print(result.content) asyncio.run(main())在這個(gè)例子里initialize()對(duì)應(yīng)協(xié)議里的初始化握手list_tools()拿到的是工具元數(shù)據(jù)call_tool()則是真正執(zhí)行。你如果把這些方法名和Function Calling的三段式流程對(duì)照會(huì)發(fā)現(xiàn)思路完全一致區(qū)別只在于MCP把發(fā)現(xiàn)工具的過程標(biāo)準(zhǔn)化了而且Client不需要提前知道Server定義了哪些工具。3.5 MCP調(diào)試中的安全與性能注意點(diǎn)MCP服務(wù)器不能只圖能用就行接入真實(shí)業(yè)務(wù)的時(shí)候還有兩件事務(wù)必考慮權(quán)限和效率。權(quán)限方面MCP協(xié)議本身不負(fù)責(zé)鑒權(quán)。HTTP模式下Server暴露在網(wǎng)絡(luò)上任何人都可以嘗試調(diào)用tools/list和tools/call因此必須在Server層自己實(shí)現(xiàn)鑒權(quán)比如用API Key、OAuth令牌或服務(wù)間調(diào)用的簽名機(jī)制。即便本地stdio模式也要思考一個(gè)問題如果你在MCP Server里封裝了一個(gè)“執(zhí)行SQL”的工具任何鏈接到這個(gè)Server的客戶端都等于拿到了數(shù)據(jù)庫執(zhí)行權(quán)限。我見過一些開發(fā)者在本地MCP服務(wù)器里放了刪除數(shù)據(jù)的工具當(dāng)時(shí)的場(chǎng)景是自用調(diào)試但如果哪天被其他應(yīng)用連進(jìn)來風(fēng)險(xiǎn)非常大。效率方面一個(gè)常見的坑是Server在tools/list里注冊(cè)了大量工具而每次請(qǐng)求模型都需要處理全部工具描述。MCP本身的工具發(fā)現(xiàn)機(jī)制會(huì)讓任何支持MCP的客戶端自動(dòng)獲取所有工具這對(duì)Agent的上下文窗口是個(gè)不小的負(fù)擔(dān)。后面我可以給個(gè)小建議不要把幾十個(gè)工具一股腦塞進(jìn)一個(gè)Server按業(yè)務(wù)域拆成多個(gè)Server讓Agent按需連接。4. Function Calling與MCP的對(duì)比取舍到底該選哪條路4.1 兩條路線的能力邊界對(duì)比我經(jīng)常被問到一句話既然Function Calling這么好用為什么還要折騰MCP反過來也有人問MCP這么標(biāo)準(zhǔn)是不是以后不用寫Function Calling了我的看法是這兩個(gè)東西不是同一個(gè)層次的問題與其糾結(jié)誰取代誰不如看它們?cè)陧?xiàng)目里的落點(diǎn)。從工具定義方式看Function Calling的工具是“注冊(cè)”到每次API請(qǐng)求里的你調(diào)一次Model API就要把工具定義帶一次。MCP的工具是“掛”在一個(gè)獨(dú)立Server上的客戶端通過協(xié)議發(fā)現(xiàn)工具。這意味著MCP的工具天然可以被多個(gè)應(yīng)用復(fù)用而Function Calling的工具更像是單次會(huì)話內(nèi)的臨時(shí)配置。從生態(tài)兼容看Function Calling強(qiáng)依賴模型廠商對(duì)協(xié)議的支持你換一家模型可能要檢查參數(shù)細(xì)節(jié)是否一致。MCP則偏模型無關(guān)客戶端只面向標(biāo)準(zhǔn)的MCP協(xié)議模型怎么接進(jìn)去是客戶端內(nèi)部的事。從靈活程度看Function Calling的處理鏈條更短流程控制更容易。MCP多了一層Server進(jìn)程或遠(yuǎn)程服務(wù)多一個(gè)環(huán)節(jié)就多一分故障可能性排查鏈路更長。我在實(shí)際項(xiàng)目里通常按這樣決策如果項(xiàng)目是單模型應(yīng)用工具數(shù)量少少于10個(gè)而且不打算給其他應(yīng)用復(fù)用直接用Function Calling最省事。如果工具數(shù)量大、有多個(gè)前端應(yīng)用共用同一套數(shù)據(jù)工具、或者需要讓Agent動(dòng)態(tài)探索外部系統(tǒng)的能力上MCP。還有一種情況也會(huì)選MCP某團(tuán)隊(duì)內(nèi)部已經(jīng)封裝好了一批數(shù)據(jù)服務(wù)用MCP包一層避開了每個(gè)項(xiàng)目重復(fù)寫服務(wù)對(duì)接代碼。4.2 兩者不是非此即彼組合拳往往更順手真正成熟的Agent架構(gòu)里兩種方式經(jīng)常同時(shí)出現(xiàn)。比如外層用Function Calling驅(qū)動(dòng)模型的基礎(chǔ)動(dòng)作內(nèi)層再把那些復(fù)雜的、重復(fù)的工具封裝成一個(gè)MCP Server然后在Function Calling的工具定義里注冊(cè)一個(gè)名叫mcp_call_tool的工具參數(shù)是server_name和tool_name讓模型通過這個(gè)“通用工具”去間接使用MCP里的工具。這種“網(wǎng)關(guān)模式”有一種很直觀的好處模型每次只需要看一個(gè)工具定義不需要把幾十個(gè)MCP工具全塞進(jìn)上下文省token。同時(shí)MCP Server端新增工具時(shí)不用改模型側(cè)的tools配置因?yàn)槟Ｐ椭恍枰馈巴ㄟ^通用調(diào)用器去訪問任何MCP工具”這一個(gè)入口。但模式也有明顯的副作用模型可能不知道某個(gè)具體工具的存在和使用規(guī)則因?yàn)镸CP里的工具描述沒有被模型看到。解決的辦法是在MCP Server的工具命名和描述上下狠功夫盡量讓工具名自解釋同時(shí)在mcp_call_tool的描述里把常用工具體驗(yàn)寫成“使用指南”。簡單說這種方案的成敗取決于你寫工具描述的能力比單純的Function Calling更依賴文案功底。4.3 從“能用”到“好用”還要補(bǔ)齊三塊配置不管選了哪條路想跑出一個(gè)穩(wěn)定可靠的Agent光有工具調(diào)用還不夠。以下三塊配置是經(jīng)驗(yàn)之談缺了某一塊后面很容易出問題。第一塊是工具的統(tǒng)一錯(cuò)誤碼規(guī)范。工具執(zhí)行失敗時(shí)返回給模型的信息不能是一堆Python異常堆棧而應(yīng)該是一段結(jié)構(gòu)化的錯(cuò)誤描述包括錯(cuò)誤類型、可修復(fù)建議、重試次數(shù)限制。比如查不到數(shù)據(jù)返回{error: NOT_FOUND, message: 未查詢到該城市的天氣數(shù)據(jù)}模型能理解并產(chǎn)生合適的回復(fù)。如果直接把KeyError堆棧丟過去模型也只能干瞪眼。第二塊是全局的“最大重試和最大步數(shù)”控制。Agent調(diào)用工具的時(shí)候很容易陷入死循環(huán)模型不斷調(diào)用同一個(gè)失敗的工具或者來回調(diào)兩個(gè)相互依賴的工具。建議在Agent循環(huán)外面加一個(gè)計(jì)數(shù)器超過5輪后強(qiáng)制停止并觸發(fā)一個(gè)“請(qǐng)直接回復(fù)用戶當(dāng)前拿到的信息不要再調(diào)用工具”的系統(tǒng)指令。第三塊是完整請(qǐng)求日志。每次入?yún)?、工具調(diào)用、返回結(jié)果、token計(jì)數(shù)全部記錄成結(jié)構(gòu)化日志。我見過太多項(xiàng)目模型行為異常時(shí)只能靠猜。有了完整鏈路日志你能快速定位是模型選錯(cuò)工具還是工具返回?cái)?shù)據(jù)異常還是上下文被撐爆。5. 常見問題與排查技巧實(shí)錄寫到這里我把實(shí)際開發(fā)中踩過的高頻問題整理成一張速查表按癥狀、原因、解法三條線來描述。癥狀原因解法模型反復(fù)調(diào)用同一個(gè)工具陷入死循環(huán)工具返回的結(jié)果讓模型覺得沒拿到信息檢查工具返回結(jié)構(gòu)是否清晰錯(cuò)誤信息是否包含建議動(dòng)作模型完全不調(diào)用工具直接編答案工具描述不具體模型沒意識(shí)到該調(diào)用重寫description明確“不調(diào)用工具無法回答”的場(chǎng)景工具返回JSON模型卻理解錯(cuò)返回內(nèi)容不是JSON或字段含義模糊統(tǒng)一返回JSON并在工具描述中說明字段單位與取值多工具并行調(diào)用時(shí)結(jié)果對(duì)不上忽略了tool_call_id的一一匹配逐個(gè)遍歷tool_calls按tool_call_id回傳MCP客戶端連不上stdio ServerServer啟動(dòng)報(bào)錯(cuò)或依賴包沒裝先把Server腳本單獨(dú)跑一遍確認(rèn)能正常啟動(dòng)再連客戶端MCP工具列表為空Server加載了模塊但沒注冊(cè)任何tool檢查是否用mcp.tool()裝飾確認(rèn)裝飾器作用范圍上下文塞滿導(dǎo)致后續(xù)回答錯(cuò)亂每次請(qǐng)求都帶完整工具描述和歷史消息用“網(wǎng)關(guān)模式”精簡工具描述或?qū)v史消息做裁剪總結(jié)模型調(diào)用了不存在的工具名工具定義與模型內(nèi)置知識(shí)沖突在描述里加上“如無此工具請(qǐng)不要假設(shè)其存在”的說明或檢查工具命名是否有歧義這里面有兩個(gè)問題我想特別展開因?yàn)樗鼈兲菀妆缓雎?。第一個(gè)是“模型調(diào)用了一個(gè)你能提供的工具但參數(shù)總是不規(guī)范”。比如你定義了get_weather要求參數(shù)是city但模型偶爾會(huì)傳location。排查思路不是改工具而是改描述。把description改成“city是唯一合法參數(shù)其他字段一律不接受”然后讓工具端做參數(shù)校驗(yàn)不合法參數(shù)返回統(tǒng)一錯(cuò)誤。這樣可以倒逼模型按規(guī)范傳參也方便日志追蹤。第二個(gè)是“工具返回?cái)?shù)據(jù)特別大”。比如你讓模型查一個(gè)數(shù)據(jù)庫表的所有記錄如果是海量數(shù)據(jù)直接把原始內(nèi)容喂回給模型光token費(fèi)用就足夠嚇人。正確做法是在工具端做“結(jié)果精簡”只返回模型判斷所需要的摘要信息。比如要查詢用戶訂單工具端可以先做分頁或只返回最近五條。這個(gè)必須在工具設(shè)計(jì)階段想好否則上線后要返工。6. 從工具調(diào)用到Agent再往后走一步的思考6.1 工具調(diào)用是能力基礎(chǔ)Agent才是上層建筑聊了很多工具調(diào)用的細(xì)節(jié)最后把視線往上拉一層。工具調(diào)用只是讓模型“能用”工具Agent則是讓模型“會(huì)用”工具。兩者之間還夾著規(guī)劃能力模型需要分解任務(wù)、確定調(diào)用順序、觀察中間結(jié)果、動(dòng)態(tài)調(diào)整計(jì)劃。比如“幫我規(guī)劃下周三北京到上海的行程天氣不好就改訂高鐵”這類任務(wù)會(huì)涉及到一系列工具調(diào)用先查天氣、再查高鐵票、再查酒店、再?zèng)Q定是否調(diào)整時(shí)間。這個(gè)流程里模型需要自己判斷調(diào)用順序甚至要回退重試。目前的實(shí)現(xiàn)方式主要靠“ReAct式循環(huán)”思考Thought→調(diào)用工具Action→觀察結(jié)果Observation→再思考直到完成。6.2 給Agent增加記憶和狀態(tài)管理的建議工具調(diào)用是無狀態(tài)的但Agent必須是有狀態(tài)的。建議在工具調(diào)用之外增加一個(gè)“狀態(tài)槽”機(jī)制每次模型完成一步操作就把結(jié)果摘要寫入狀態(tài)槽后續(xù)步驟直接讀取狀態(tài)槽而不是重新把全部歷史消息一股腦帶回模型。這個(gè)方法有兩個(gè)好處。一是省token長對(duì)話場(chǎng)景下效果非常明顯二是隔離噪聲早期環(huán)節(jié)的信息如果對(duì)當(dāng)前環(huán)節(jié)沒有幫助就不用再浪費(fèi)模型注意力。最簡單的實(shí)現(xiàn)是用一個(gè)全局字典存狀態(tài)字段復(fù)雜一點(diǎn)則可以用向量數(shù)據(jù)庫做記憶檢索。6.3 最后分享一個(gè)讓我少踩很多坑的習(xí)慣從一開始做工具調(diào)用到現(xiàn)在我最大的感受是不要試圖一次性把工具調(diào)用鏈路調(diào)通再全部上線這樣做太容易炸。我的習(xí)慣是永遠(yuǎn)先跑通“一個(gè)工具的最小閉環(huán)”用最簡單的查詢工具從用戶提問到模型返回結(jié)果整個(gè)過程只調(diào)用一次工具全部打通、打點(diǎn)記錄完整再往外面擴(kuò)展第二個(gè)、第三個(gè)工具。每加一個(gè)工具都回歸一遍這個(gè)最小閉環(huán)。雖然慢但穩(wěn)定性是普通項(xiàng)目很難比的。等工具數(shù)量多了再按這個(gè)思路去沉淀成通用的Agent框架后面的項(xiàng)目就能直接用這套地基去建房子了。 Function Calling與MCP實(shí)戰(zhàn)：大模型工具接入原理、選型與避坑指南
大模型的工具調(diào)用Function Calling和MCPModel Context Protocol是這兩年做AI應(yīng)用繞不開的兩個(gè)詞。很多人花了不少時(shí)間把API文檔翻了個(gè)遍可真到自己寫代碼的時(shí)候還是會(huì)卡在幾個(gè)關(guān)鍵問題上工具描述到底怎么寫模型才不犯迷糊MCP服務(wù)器和普通工具注冊(cè)到底有什么區(qū)別兩套方案到底什么時(shí)候選哪個(gè)這篇文章我打算把這些年實(shí)際踩過的坑、驗(yàn)證過的方法連同原理一起拆開講清楚。這篇文章適合正在做智能體Agent、AI助手、自動(dòng)化流程的同學(xué)參考也適合那些剛把大模型API調(diào)通、準(zhǔn)備給模型裝上“手腳”的開發(fā)者。里面不會(huì)只丟概念而是給出能直接抄作業(yè)的結(jié)構(gòu)、代碼思路和排查方案。1. 工具調(diào)用的整體思路為什么模型需要“手腳”1.1 模型不是只會(huì)聊天但它確實(shí)做不了“動(dòng)作”先想一個(gè)基本問題大模型本身能做什么它能理解語義、生成文本、總結(jié)信息、改寫代碼但本質(zhì)上它只是一個(gè)“預(yù)測(cè)下一個(gè)詞”的機(jī)器。你說“幫我查一下這周的天氣順便訂個(gè)會(huì)議室”模型即使理解這句話也沒辦法自己去訪問天氣接口更不可能去操作你的會(huì)議系統(tǒng)。要讓模型具備行動(dòng)能力就得在模型外面掛一層“工具層”。我們定義好一批函數(shù)或接口然后讓模型在需要的時(shí)候主動(dòng)選擇調(diào)用哪個(gè)、傳什么參數(shù)再把工具返回的結(jié)果交給模型繼續(xù)處理。這整個(gè)鏈路就是大家常說的工具調(diào)用。最早的做法非常簡單粗暴把工具的描述連同一個(gè)“輸出JSON格式”的指令硬塞進(jìn)提示詞里讓模型把“想調(diào)用的函數(shù)名參數(shù)”以JSON文本吐出來然后我們自己去解析。這套方案最大的問題是模型經(jīng)常輸出格式不穩(wěn)定的JSON函數(shù)名偶爾會(huì)憑空捏造參數(shù)類型也可能對(duì)不上。后來主流大模型API陸續(xù)推出了結(jié)構(gòu)化的函數(shù)調(diào)用能力也就是Function Calling模型不再輸出“看起來像JSON的字符串”而是直接返回結(jié)構(gòu)化的工具調(diào)用對(duì)象從協(xié)議層面解決了格式問題。1.2 MCP想解決的是另一個(gè)問題Function Calling解決的是“模型和工具之間的通信格式”但它沒解決“工具怎么接入”的問題。每個(gè)工具都要單獨(dú)適配每個(gè)應(yīng)用都要自己寫一套工具注冊(cè)、鑒權(quán)、參數(shù)校驗(yàn)的代碼。做過三四個(gè)Agent項(xiàng)目就會(huì)發(fā)現(xiàn)光是把不同的內(nèi)部系統(tǒng)、外部API一個(gè)個(gè)接進(jìn)來就夠?qū)憥浊心z水代碼。MCP的定位就是一個(gè)標(biāo)準(zhǔn)化的“工具接入層”。它定義了應(yīng)用Host、客戶端Client和工具服務(wù)端Server之間的通信協(xié)議。你把一個(gè)數(shù)據(jù)源或工具封裝成一個(gè)MCP Server任何支持MCP的客戶端都能直接發(fā)現(xiàn)它、調(diào)用它不需要為每個(gè)應(yīng)用重復(fù)改代碼。類比一下如果Function Calling是“統(tǒng)一了打電話的接線術(shù)語”MCP就是“統(tǒng)一了電話線接口、撥號(hào)規(guī)則和電話號(hào)碼簿格式還制定了電話亭的尺寸”。兩者解決的問題層次不同。從實(shí)際選型來看目前比較合理的思路是這樣的方案解決的問題適配場(chǎng)景接入成本提示詞JSON解析模型輸出函數(shù)調(diào)用意圖臨時(shí)演示、快速驗(yàn)證、不方便改API的舊系統(tǒng)最低但穩(wěn)定性差Function Calling結(jié)構(gòu)化返回工具調(diào)用指令需要穩(wěn)定、可靠地調(diào)用少量工具的應(yīng)用低主流API都支持MCP多工具、多數(shù)據(jù)源統(tǒng)一接入與復(fù)用復(fù)雜Agent、企業(yè)數(shù)據(jù)中臺(tái)、需要生態(tài)復(fù)用的場(chǎng)景偏高需要封裝服務(wù)2. Function Calling實(shí)戰(zhàn)拆解從原理到可落地的調(diào)用流程2.1 核心三要素tools參數(shù)、工具描述、兩輪往返Function Calling的整個(gè)機(jī)制可以濃縮成三件事讓模型知道有哪些工具、讓模型決定調(diào)哪個(gè)、把結(jié)果反饋給模型。每個(gè)環(huán)節(jié)都有對(duì)應(yīng)的參數(shù)和代碼結(jié)構(gòu)。第一件事叫“工具注冊(cè)”。在API請(qǐng)求體里用tools參數(shù)列出所有可用的工具每個(gè)工具要包含type一般是function、function.name、function.description和function.parameters。這個(gè)parameters用的是JSON Schema格式相當(dāng)于你把工具的“說明書”喂給模型看。一個(gè)典型的工具定義長這樣{ type: function, function: { name: get_weather, description: 查詢指定城市的實(shí)時(shí)天氣和未來三天的預(yù)報(bào)參數(shù)city為城市名稱例如北京、上海、廣州, parameters: { type: object, properties: { city: { type: string, description: 要查詢的城市名稱 } }, required: [city] } } }第二件事是模型“做決定”。你把用戶消息和tools列表一起發(fā)給模型模型如果判斷需要調(diào)用工具返回的響應(yīng)里會(huì)帶一個(gè)tool_calls數(shù)組里面包含函數(shù)名name和參數(shù)arguments。注意這個(gè)arguments雖然是字符串但格式是可控的結(jié)構(gòu)化JSON不像早期提示詞方案那樣需要在一大段對(duì)話文本里“大海撈針”。第三件事是“結(jié)果回傳”。工具執(zhí)行完以后你要把結(jié)果以role: tool的消息返回給模型并附上對(duì)應(yīng)的tool_call_id。模型拿到工具結(jié)果后才能生成最終的自然語言回答。整個(gè)過程需要兩次或更多次請(qǐng)求通常叫“兩輪往返”。2.2 一個(gè)完整的調(diào)用流程示例我用一段接近真實(shí)項(xiàng)目的代碼來展示這個(gè)流程。為了不依賴某個(gè)特定SDK這里用最通用的HTTP請(qǐng)求結(jié)構(gòu)說明import json import requests # 第一步構(gòu)造請(qǐng)求帶上工具定義和用戶問題 payload { model: your-model-name, messages: [ {role: user, content: 北京今天適合出門嗎我想知道明天會(huì)不會(huì)下雨} ], tools: [ { type: function, function: { name: get_weather, description: 查詢指定城市的實(shí)時(shí)天氣和未來三天的預(yù)報(bào), parameters: { type: object, properties: { city: {type: string, description: 城市名稱} }, required: [city] } } } ], tool_choice: auto } resp requests.post(https://api.example.com/v1/chat/completions, headers{Authorization: Bearer YOUR_API_KEY}, jsonpayload) data resp.json() assistant_message data[choices][0][message] # 第二步判斷模型是否需要調(diào)用工具 if assistant_message.get(tool_calls): tool_calls assistant_message[tool_calls] # 這里假設(shè)只處理一個(gè)工具調(diào)用實(shí)際場(chǎng)景需要循環(huán)執(zhí)行 call tool_calls[0] fn_name call[function][name] fn_args json.loads(call[function][arguments]) if fn_name get_weather: # 執(zhí)行真實(shí)工具調(diào)用天氣接口 result real_weather_api(fn_args[city]) # 第三步把工具結(jié)果回傳給模型繼續(xù)生成回答 messages payload[messages] messages.append({ role: assistant, content: None, tool_calls: tool_calls }) messages.append({ role: tool, tool_call_id: call[id], content: json.dumps(result, ensure_asciiFalse) }) final_payload { model: your-model-name, messages: messages, tools: payload[tools] } final_resp requests.post(https://api.example.com/v1/chat/completions, headers{Authorization: Bearer YOUR_API_KEY}, jsonfinal_payload) final_data final_resp.json() answer final_data[choices][0][message][content] print(answer)這段代碼看起來簡單但實(shí)際項(xiàng)目里需要處理的細(xì)節(jié)比這個(gè)多得多多個(gè)工具并行調(diào)用、工具執(zhí)行異常、超時(shí)、結(jié)果太長、參數(shù)校驗(yàn)失敗……我后面匯到問題清單里統(tǒng)一講。2.3 工具描述怎么寫模型才不會(huì)亂調(diào)這是Function Calling里最容易出問題的地方。很多同學(xué)把description寫得特別簡單類似“查詢天氣”結(jié)果模型經(jīng)常搞不清楚要填什么參數(shù)、返回什么格式。我總結(jié)出了一套描述寫法核心是“四個(gè)說清”說清工具用途不要只寫“獲取庫存”要寫“查詢指定SKU在當(dāng)前倉位的實(shí)時(shí)庫存數(shù)量返回在庫數(shù)和可售數(shù)”說清每個(gè)參數(shù)的含義city這個(gè)字段要說明格式比如“城市中文名例如杭州、成都”說清參數(shù)的限制條件比如“日期格式為YYYY-MM-DD不得早于今天”說清返回結(jié)果的格式比如“返回JSON包含字段temperature和humidity溫度單位為攝氏度”打個(gè)比方工具描述就是給模型看的“產(chǎn)品說明書”說明書寫得越清楚模型這個(gè)“用戶”就越不會(huì)用錯(cuò)。而且描述文字本身也會(huì)參與模型token計(jì)算太長浪費(fèi)太短誤事需要反復(fù)打磨到一個(gè)平衡點(diǎn)。2.4 工具調(diào)用的幾個(gè)關(guān)鍵參數(shù)和進(jìn)階玩法在實(shí)際項(xiàng)目里有下面幾個(gè)參數(shù)值得專門研究。tool_choice參數(shù)控制模型調(diào)用工具的“自由度”。默認(rèn)auto表示模型自己決定調(diào)不調(diào)設(shè)為required可以強(qiáng)制模型必須調(diào)用至少一個(gè)工具適合那種“這一步必須操作某個(gè)系統(tǒng)”的場(chǎng)景直接指定某個(gè)函數(shù)名{type: function, function: {name: xxx}}則相當(dāng)于強(qiáng)制走某一條工具路徑。parallel_tool_calls參數(shù)控制并行調(diào)用。模型在一次回答中可以返回多個(gè)工具調(diào)用比如“查天氣設(shè)置提醒”這類沒有依賴關(guān)系的動(dòng)作可以一次性返回兩個(gè)tool_calls。對(duì)于延遲敏感的Agent應(yīng)用這個(gè)能力非常有用。需要強(qiáng)調(diào)的是并行調(diào)用不代表結(jié)果可以亂給每個(gè)tool_call要對(duì)應(yīng)一個(gè)tool_call_id返回的時(shí)候需要一一匹配。還有一個(gè)很多人忽略的點(diǎn)工具返回的content最好是結(jié)構(gòu)化的JSON字符串而不是一段人話描述。比如工具做完了“發(fā)起退款”你返回{status: success, refund_id: R12345}模型就能基于這個(gè)結(jié)果生成流暢的回復(fù)。如果你返回“退款成功了哈單號(hào)是R12345”模型雖然也能讀但遇到復(fù)雜的多步推理任務(wù)結(jié)構(gòu)化結(jié)果讓它做后續(xù)判斷更準(zhǔn)確。3. MCP實(shí)戰(zhàn)拆解把工具變成標(biāo)準(zhǔn)化的服務(wù)3.1 MCP架構(gòu)速覽Host、Client、Server各司其職MCP的架構(gòu)里主要有三個(gè)角色Host是用戶正在使用的AI應(yīng)用比如一個(gè)桌面客戶端Client在Host內(nèi)部負(fù)責(zé)與Server建立連接Server是提供工具、數(shù)據(jù)源的一方可以運(yùn)行在本地也可以部署在遠(yuǎn)程。每次工具調(diào)用的大致流程是Client啟動(dòng)時(shí)向Server發(fā)送initialize請(qǐng)求完成握手Server返回自己支持的協(xié)議版本和服務(wù)器信息接著Client調(diào)用tools/list方法拿到一批工具的定義當(dāng)Agent需要執(zhí)行某個(gè)動(dòng)作時(shí)Client調(diào)用tools/call方法傳入工具名和參數(shù)Server執(zhí)行完返回結(jié)果。這套機(jī)制和Function Calling很像區(qū)別在于它的發(fā)現(xiàn)、調(diào)用、參數(shù)傳遞全是標(biāo)準(zhǔn)化協(xié)議而且不綁定具體模型廠商。對(duì)于沒有接觸過MCP的人來說可以把它想象成一個(gè)“USB接口標(biāo)準(zhǔn)”以前每個(gè)設(shè)備都要用自己的充電線現(xiàn)在有了統(tǒng)一接口任何支持這個(gè)標(biāo)準(zhǔn)的設(shè)備插上就能用。MCP Server就是那個(gè)“設(shè)備”AI應(yīng)用就是那個(gè)“電腦”。3.2 用FastMCP實(shí)現(xiàn)一個(gè)最小可用的MCP服務(wù)器目前最順手的方式是用官方Python SDK里的FastMCP類。下面是一個(gè)包含兩個(gè)工具的迷你服務(wù)器能在五分鐘內(nèi)跑起來from mcp.server.fastmcp import FastMCP import json # 創(chuàng)建一個(gè)MCP服務(wù)器實(shí)例名稱會(huì)顯示在客戶端列表里 mcp FastMCP(namedemo-tools-server) mcp.tool() def get_stock_price(symbol: str) - str: 查詢指定股票代碼的最新價(jià)格。 Args: symbol: 股票代碼如 AAPL、MSFT、600519 # 實(shí)際項(xiàng)目里這里替換成真實(shí)的行情接口 data {symbol: symbol, price: 123.45, currency: CNY} return json.dumps(data, ensure_asciiFalse) mcp.tool() def send_message(phone_number: str, content: str) - str: 發(fā)送一條短信通知。 Args: phone_number: 接收號(hào)碼11位手機(jī)號(hào) content: 短信內(nèi)容長度不超過70字 # 實(shí)際項(xiàng)目里這里替換成真實(shí)的短信服務(wù)商接口 return json.dumps({status: ok, message_id: MSG123456}) if __name__ __main__: mcp.run()注意這里有個(gè)現(xiàn)在很多新手還不熟悉的點(diǎn)mcp.tool()裝飾器會(huì)自動(dòng)從函數(shù)的類型注解和函數(shù)文檔里生成JSON Schema。也就是說函數(shù)簽名里的symbol: str和文檔字符串的Args說明最終會(huì)變成tools/list返回的inputSchema。這意味著寫好一個(gè)函數(shù)就相當(dāng)于定義好了一個(gè)工具不需要像Function Calling那樣單獨(dú)維護(hù)一份JSON Schema。不過這也帶來一個(gè)隱藏問題很多Python函數(shù)用Union、Literal、List這些類型時(shí)FastMCP能智能轉(zhuǎn)化但如果函數(shù)里有復(fù)雜自定義類型它會(huì)自動(dòng)把類型轉(zhuǎn)成object參數(shù)描述就丟失了。遇到這種情況可以用Pydantic的Field來補(bǔ)充字段描述保持工具定義的質(zhì)量。3.3 傳輸方式的選擇stdio還是Streamable HTTPMCP支持不同的傳輸通道最常見的兩種是本地場(chǎng)景的stdio和跨服務(wù)的Streamable HTTP。mcp.run()默認(rèn)走stdio模式。在這種方式下Client啟動(dòng)一個(gè)子進(jìn)程來運(yùn)行Server腳本通過標(biāo)準(zhǔn)輸入輸出傳遞JSON-RPC消息。這種方式的好處是零網(wǎng)絡(luò)配置、啟動(dòng)快很適合桌面端應(yīng)用和本地調(diào)試。缺點(diǎn)是Server和Client必須部署在同一臺(tái)機(jī)器上跨進(jìn)程通信不好做權(quán)限隔離。如果MCP Server要提供給多個(gè)遠(yuǎn)程客戶端使用就得走Streamable HTTP模式。通常做法是用一個(gè)Web框架比如FastAPI包一層或者直接用SDK提供的StreamableHTTPTransport。這種模式需要額外處理鑒權(quán)、跨域和并發(fā)問題但好處是服務(wù)可以復(fù)用、集中部署、統(tǒng)一升級(jí)。我自己在項(xiàng)目里一般按這個(gè)規(guī)則選只在本地給某個(gè)單一工具用選stdio如果Server要給多個(gè)不同應(yīng)用共享或者要部署到服務(wù)器上直接上HTTP模式。3.4 客戶端接入MCP Server的完整步驟接入MCP的客戶端端目前主流做法是用不同語言的SDK。以Python為例連接一個(gè)stdio模式的Server大致需要四步創(chuàng)建session、初始化連接、列出工具、調(diào)用工具。import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def main(): # 1. 啟動(dòng)MCP Server進(jìn)程 server_params StdioServerParameters( commandpython, args[demo_tools_server.py], envNone ) # 2. 建立stdio通信管道并創(chuàng)建會(huì)話 async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: # 3. 完成握手初始化 init_result await session.initialize() print(fConnected to: {init_result.serverInfo}) # 4. 列出所有工具 tools await session.list_tools() print(Available tools:, [tool.name for tool in tools.tools]) # 5. 調(diào)用指定工具 result await session.call_tool( nameget_stock_price, arguments{symbol: 600519} ) print(result.content) asyncio.run(main())在這個(gè)例子里initialize()對(duì)應(yīng)協(xié)議里的初始化握手list_tools()拿到的是工具元數(shù)據(jù)call_tool()則是真正執(zhí)行。你如果把這些方法名和Function Calling的三段式流程對(duì)照會(huì)發(fā)現(xiàn)思路完全一致區(qū)別只在于MCP把發(fā)現(xiàn)工具的過程標(biāo)準(zhǔn)化了而且Client不需要提前知道Server定義了哪些工具。3.5 MCP調(diào)試中的安全與性能注意點(diǎn)MCP服務(wù)器不能只圖能用就行接入真實(shí)業(yè)務(wù)的時(shí)候還有兩件事務(wù)必考慮權(quán)限和效率。權(quán)限方面MCP協(xié)議本身不負(fù)責(zé)鑒權(quán)。HTTP模式下Server暴露在網(wǎng)絡(luò)上任何人都可以嘗試調(diào)用tools/list和tools/call因此必須在Server層自己實(shí)現(xiàn)鑒權(quán)比如用API Key、OAuth令牌或服務(wù)間調(diào)用的簽名機(jī)制。即便本地stdio模式也要思考一個(gè)問題如果你在MCP Server里封裝了一個(gè)“執(zhí)行SQL”的工具任何鏈接到這個(gè)Server的客戶端都等于拿到了數(shù)據(jù)庫執(zhí)行權(quán)限。我見過一些開發(fā)者在本地MCP服務(wù)器里放了刪除數(shù)據(jù)的工具當(dāng)時(shí)的場(chǎng)景是自用調(diào)試但如果哪天被其他應(yīng)用連進(jìn)來風(fēng)險(xiǎn)非常大。效率方面一個(gè)常見的坑是Server在tools/list里注冊(cè)了大量工具而每次請(qǐng)求模型都需要處理全部工具描述。MCP本身的工具發(fā)現(xiàn)機(jī)制會(huì)讓任何支持MCP的客戶端自動(dòng)獲取所有工具這對(duì)Agent的上下文窗口是個(gè)不小的負(fù)擔(dān)。后面我可以給個(gè)小建議不要把幾十個(gè)工具一股腦塞進(jìn)一個(gè)Server按業(yè)務(wù)域拆成多個(gè)Server讓Agent按需連接。4. Function Calling與MCP的對(duì)比取舍到底該選哪條路4.1 兩條路線的能力邊界對(duì)比我經(jīng)常被問到一句話既然Function Calling這么好用為什么還要折騰MCP反過來也有人問MCP這么標(biāo)準(zhǔn)是不是以后不用寫Function Calling了我的看法是這兩個(gè)東西不是同一個(gè)層次的問題與其糾結(jié)誰取代誰不如看它們?cè)陧?xiàng)目里的落點(diǎn)。從工具定義方式看Function Calling的工具是“注冊(cè)”到每次API請(qǐng)求里的你調(diào)一次Model API就要把工具定義帶一次。MCP的工具是“掛”在一個(gè)獨(dú)立Server上的客戶端通過協(xié)議發(fā)現(xiàn)工具。這意味著MCP的工具天然可以被多個(gè)應(yīng)用復(fù)用而Function Calling的工具更像是單次會(huì)話內(nèi)的臨時(shí)配置。從生態(tài)兼容看Function Calling強(qiáng)依賴模型廠商對(duì)協(xié)議的支持你換一家模型可能要檢查參數(shù)細(xì)節(jié)是否一致。MCP則偏模型無關(guān)客戶端只面向標(biāo)準(zhǔn)的MCP協(xié)議模型怎么接進(jìn)去是客戶端內(nèi)部的事。從靈活程度看Function Calling的處理鏈條更短流程控制更容易。MCP多了一層Server進(jìn)程或遠(yuǎn)程服務(wù)多一個(gè)環(huán)節(jié)就多一分故障可能性排查鏈路更長。我在實(shí)際項(xiàng)目里通常按這樣決策如果項(xiàng)目是單模型應(yīng)用工具數(shù)量少少于10個(gè)而且不打算給其他應(yīng)用復(fù)用直接用Function Calling最省事。如果工具數(shù)量大、有多個(gè)前端應(yīng)用共用同一套數(shù)據(jù)工具、或者需要讓Agent動(dòng)態(tài)探索外部系統(tǒng)的能力上MCP。還有一種情況也會(huì)選MCP某團(tuán)隊(duì)內(nèi)部已經(jīng)封裝好了一批數(shù)據(jù)服務(wù)用MCP包一層避開了每個(gè)項(xiàng)目重復(fù)寫服務(wù)對(duì)接代碼。4.2 兩者不是非此即彼組合拳往往更順手真正成熟的Agent架構(gòu)里兩種方式經(jīng)常同時(shí)出現(xiàn)。比如外層用Function Calling驅(qū)動(dòng)模型的基礎(chǔ)動(dòng)作內(nèi)層再把那些復(fù)雜的、重復(fù)的工具封裝成一個(gè)MCP Server然后在Function Calling的工具定義里注冊(cè)一個(gè)名叫mcp_call_tool的工具參數(shù)是server_name和tool_name讓模型通過這個(gè)“通用工具”去間接使用MCP里的工具。這種“網(wǎng)關(guān)模式”有一種很直觀的好處模型每次只需要看一個(gè)工具定義不需要把幾十個(gè)MCP工具全塞進(jìn)上下文省token。同時(shí)MCP Server端新增工具時(shí)不用改模型側(cè)的tools配置因?yàn)槟Ｐ椭恍枰馈巴ㄟ^通用調(diào)用器去訪問任何MCP工具”這一個(gè)入口。但模式也有明顯的副作用模型可能不知道某個(gè)具體工具的存在和使用規(guī)則因?yàn)镸CP里的工具描述沒有被模型看到。解決的辦法是在MCP Server的工具命名和描述上下狠功夫盡量讓工具名自解釋同時(shí)在mcp_call_tool的描述里把常用工具體驗(yàn)寫成“使用指南”。簡單說這種方案的成敗取決于你寫工具描述的能力比單純的Function Calling更依賴文案功底。4.3 從“能用”到“好用”還要補(bǔ)齊三塊配置不管選了哪條路想跑出一個(gè)穩(wěn)定可靠的Agent光有工具調(diào)用還不夠。以下三塊配置是經(jīng)驗(yàn)之談缺了某一塊后面很容易出問題。第一塊是工具的統(tǒng)一錯(cuò)誤碼規(guī)范。工具執(zhí)行失敗時(shí)返回給模型的信息不能是一堆Python異常堆棧而應(yīng)該是一段結(jié)構(gòu)化的錯(cuò)誤描述包括錯(cuò)誤類型、可修復(fù)建議、重試次數(shù)限制。比如查不到數(shù)據(jù)返回{error: NOT_FOUND, message: 未查詢到該城市的天氣數(shù)據(jù)}模型能理解并產(chǎn)生合適的回復(fù)。如果直接把KeyError堆棧丟過去模型也只能干瞪眼。第二塊是全局的“最大重試和最大步數(shù)”控制。Agent調(diào)用工具的時(shí)候很容易陷入死循環(huán)模型不斷調(diào)用同一個(gè)失敗的工具或者來回調(diào)兩個(gè)相互依賴的工具。建議在Agent循環(huán)外面加一個(gè)計(jì)數(shù)器超過5輪后強(qiáng)制停止并觸發(fā)一個(gè)“請(qǐng)直接回復(fù)用戶當(dāng)前拿到的信息不要再調(diào)用工具”的系統(tǒng)指令。第三塊是完整請(qǐng)求日志。每次入?yún)?、工具調(diào)用、返回結(jié)果、token計(jì)數(shù)全部記錄成結(jié)構(gòu)化日志。我見過太多項(xiàng)目模型行為異常時(shí)只能靠猜。有了完整鏈路日志你能快速定位是模型選錯(cuò)工具還是工具返回?cái)?shù)據(jù)異常還是上下文被撐爆。5. 常見問題與排查技巧實(shí)錄寫到這里我把實(shí)際開發(fā)中踩過的高頻問題整理成一張速查表按癥狀、原因、解法三條線來描述。癥狀原因解法模型反復(fù)調(diào)用同一個(gè)工具陷入死循環(huán)工具返回的結(jié)果讓模型覺得沒拿到信息檢查工具返回結(jié)構(gòu)是否清晰錯(cuò)誤信息是否包含建議動(dòng)作模型完全不調(diào)用工具直接編答案工具描述不具體模型沒意識(shí)到該調(diào)用重寫description明確“不調(diào)用工具無法回答”的場(chǎng)景工具返回JSON模型卻理解錯(cuò)返回內(nèi)容不是JSON或字段含義模糊統(tǒng)一返回JSON并在工具描述中說明字段單位與取值多工具并行調(diào)用時(shí)結(jié)果對(duì)不上忽略了tool_call_id的一一匹配逐個(gè)遍歷tool_calls按tool_call_id回傳MCP客戶端連不上stdio ServerServer啟動(dòng)報(bào)錯(cuò)或依賴包沒裝先把Server腳本單獨(dú)跑一遍確認(rèn)能正常啟動(dòng)再連客戶端MCP工具列表為空Server加載了模塊但沒注冊(cè)任何tool檢查是否用mcp.tool()裝飾確認(rèn)裝飾器作用范圍上下文塞滿導(dǎo)致后續(xù)回答錯(cuò)亂每次請(qǐng)求都帶完整工具描述和歷史消息用“網(wǎng)關(guān)模式”精簡工具描述或?qū)v史消息做裁剪總結(jié)模型調(diào)用了不存在的工具名工具定義與模型內(nèi)置知識(shí)沖突在描述里加上“如無此工具請(qǐng)不要假設(shè)其存在”的說明或檢查工具命名是否有歧義這里面有兩個(gè)問題我想特別展開因?yàn)樗鼈兲菀妆缓雎?。第一個(gè)是“模型調(diào)用了一個(gè)你能提供的工具但參數(shù)總是不規(guī)范”。比如你定義了get_weather要求參數(shù)是city但模型偶爾會(huì)傳location。排查思路不是改工具而是改描述。把description改成“city是唯一合法參數(shù)其他字段一律不接受”然后讓工具端做參數(shù)校驗(yàn)不合法參數(shù)返回統(tǒng)一錯(cuò)誤。這樣可以倒逼模型按規(guī)范傳參也方便日志追蹤。第二個(gè)是“工具返回?cái)?shù)據(jù)特別大”。比如你讓模型查一個(gè)數(shù)據(jù)庫表的所有記錄如果是海量數(shù)據(jù)直接把原始內(nèi)容喂回給模型光token費(fèi)用就足夠嚇人。正確做法是在工具端做“結(jié)果精簡”只返回模型判斷所需要的摘要信息。比如要查詢用戶訂單工具端可以先做分頁或只返回最近五條。這個(gè)必須在工具設(shè)計(jì)階段想好否則上線后要返工。6. 從工具調(diào)用到Agent再往后走一步的思考6.1 工具調(diào)用是能力基礎(chǔ)Agent才是上層建筑聊了很多工具調(diào)用的細(xì)節(jié)最后把視線往上拉一層。工具調(diào)用只是讓模型“能用”工具Agent則是讓模型“會(huì)用”工具。兩者之間還夾著規(guī)劃能力模型需要分解任務(wù)、確定調(diào)用順序、觀察中間結(jié)果、動(dòng)態(tài)調(diào)整計(jì)劃。比如“幫我規(guī)劃下周三北京到上海的行程天氣不好就改訂高鐵”這類任務(wù)會(huì)涉及到一系列工具調(diào)用先查天氣、再查高鐵票、再查酒店、再?zèng)Q定是否調(diào)整時(shí)間。這個(gè)流程里模型需要自己判斷調(diào)用順序甚至要回退重試。目前的實(shí)現(xiàn)方式主要靠“ReAct式循環(huán)”思考Thought→調(diào)用工具Action→觀察結(jié)果Observation→再思考直到完成。6.2 給Agent增加記憶和狀態(tài)管理的建議工具調(diào)用是無狀態(tài)的但Agent必須是有狀態(tài)的。建議在工具調(diào)用之外增加一個(gè)“狀態(tài)槽”機(jī)制每次模型完成一步操作就把結(jié)果摘要寫入狀態(tài)槽后續(xù)步驟直接讀取狀態(tài)槽而不是重新把全部歷史消息一股腦帶回模型。這個(gè)方法有兩個(gè)好處。一是省token長對(duì)話場(chǎng)景下效果非常明顯二是隔離噪聲早期環(huán)節(jié)的信息如果對(duì)當(dāng)前環(huán)節(jié)沒有幫助就不用再浪費(fèi)模型注意力。最簡單的實(shí)現(xiàn)是用一個(gè)全局字典存狀態(tài)字段復(fù)雜一點(diǎn)則可以用向量數(shù)據(jù)庫做記憶檢索。6.3 最后分享一個(gè)讓我少踩很多坑的習(xí)慣從一開始做工具調(diào)用到現(xiàn)在我最大的感受是不要試圖一次性把工具調(diào)用鏈路調(diào)通再全部上線這樣做太容易炸。我的習(xí)慣是永遠(yuǎn)先跑通“一個(gè)工具的最小閉環(huán)”用最簡單的查詢工具從用戶提問到模型返回結(jié)果整個(gè)過程只調(diào)用一次工具全部打通、打點(diǎn)記錄完整再往外面擴(kuò)展第二個(gè)、第三個(gè)工具。每加一個(gè)工具都回歸一遍這個(gè)最小閉環(huán)。雖然慢但穩(wěn)定性是普通項(xiàng)目很難比的。等工具數(shù)量多了再按這個(gè)思路去沉淀成通用的Agent框架后面的項(xiàng)目就能直接用這套地基去建房子了。