戰(zhàn)：大模型工具接入原理、選型與避坑指南)
大模型的工具調(diào)用Function Calling和MCPModel Context Protocol是這兩年做AI應(yīng)用繞不開(kāi)的兩個(gè)詞。很多人花了不少時(shí)間把API文檔翻了個(gè)遍可真到自己寫(xiě)代碼的時(shí)候還是會(huì)卡在幾個(gè)關(guān)鍵問(wèn)題上工具描述到底怎么寫(xiě)模型才不犯迷糊MCP服務(wù)器和普通工具注冊(cè)到底有什么區(qū)別兩套方案到底什么時(shí)候選哪個(gè)這篇文章我打算把這些年實(shí)際踩過(guò)的坑、驗(yàn)證過(guò)的方法連同原理一起拆開(kāi)講清楚。這篇文章適合正在做智能體Agent、AI助手、自動(dòng)化流程的同學(xué)參考也適合那些剛把大模型API調(diào)通、準(zhǔn)備給模型裝上“手腳”的開(kāi)發(fā)者。里面不會(huì)只丟概念而是給出能直接抄作業(yè)的結(jié)構(gòu)、代碼思路和排查方案。1. 工具調(diào)用的整體思路為什么模型需要“手腳”1.1 模型不是只會(huì)聊天但它確實(shí)做不了“動(dòng)作”先想一個(gè)基本問(wèn)題大模型本身能做什么它能理解語(yǔ)義、生成文本、總結(jié)信息、改寫(xiě)代碼但本質(zhì)上它只是一個(gè)“預(yù)測(cè)下一個(gè)詞”的機(jī)器。你說(shuō)“幫我查一下這周的天氣順便訂個(gè)會(huì)議室”模型即使理解這句話也沒(méi)辦法自己去訪問(wèn)天氣接口更不可能去操作你的會(huì)議系統(tǒng)。要讓模型具備行動(dòng)能力就得在模型外面掛一層“工具層”。我們定義好一批函數(shù)或接口然后讓模型在需要的時(shí)候主動(dòng)選擇調(diào)用哪個(gè)、傳什么參數(shù)再把工具返回的結(jié)果交給模型繼續(xù)處理。這整個(gè)鏈路就是大家常說(shuō)的工具調(diào)用。最早的做法非常簡(jiǎn)單粗暴把工具的描述連同一個(gè)“輸出JSON格式”的指令硬塞進(jìn)提示詞里讓模型把“想調(diào)用的函數(shù)名參數(shù)”以JSON文本吐出來(lái)然后我們自己去解析。這套方案最大的問(wèn)題是模型經(jīng)常輸出格式不穩(wěn)定的JSON函數(shù)名偶爾會(huì)憑空捏造參數(shù)類(lèi)型也可能對(duì)不上。后來(lái)主流大模型API陸續(xù)推出了結(jié)構(gòu)化的函數(shù)調(diào)用能力也就是Function Calling模型不再輸出“看起來(lái)像JSON的字符串”而是直接返回結(jié)構(gòu)化的工具調(diào)用對(duì)象從協(xié)議層面解決了格式問(wèn)題。1.2 MCP想解決的是另一個(gè)問(wèn)題Function Calling解決的是“模型和工具之間的通信格式”但它沒(méi)解決“工具怎么接入”的問(wèn)題。每個(gè)工具都要單獨(dú)適配每個(gè)應(yīng)用都要自己寫(xiě)一套工具注冊(cè)、鑒權(quán)、參數(shù)校驗(yàn)的代碼。做過(guò)三四個(gè)Agent項(xiàng)目就會(huì)發(fā)現(xiàn)光是把不同的內(nèi)部系統(tǒng)、外部API一個(gè)個(gè)接進(jìn)來(lái)就夠?qū)憥浊心z水代碼。MCP的定位就是一個(gè)標(biāo)準(zhǔn)化的“工具接入層”。它定義了應(yīng)用Host、客戶(hù)端Client和工具服務(wù)端Server之間的通信協(xié)議。你把一個(gè)數(shù)據(jù)源或工具封裝成一個(gè)MCP Server任何支持MCP的客戶(hù)端都能直接發(fā)現(xiàn)它、調(diào)用它不需要為每個(gè)應(yīng)用重復(fù)改代碼。類(lèi)比一下如果Function Calling是“統(tǒng)一了打電話的接線術(shù)語(yǔ)”MCP就是“統(tǒng)一了電話線接口、撥號(hào)規(guī)則和電話號(hào)碼簿格式還制定了電話亭的尺寸”。兩者解決的問(wèn)題層次不同。從實(shí)際選型來(lái)看目前比較合理的思路是這樣的方案解決的問(wèn)題適配場(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)于你把工具的“說(shuō)明書(shū)”喂給模型看。一個(gè)典型的工具定義長(zhǎng)這樣{ type: function, function: { name: get_weather, description: 查詢(xún)指定城市的實(shí)時(shí)天氣和未來(lái)三天的預(yù)報(bào)參數(shù)city為城市名稱(chēng)例如北京、上海、廣州, parameters: { type: object, properties: { city: { type: string, description: 要查詢(xún)的城市名稱(chēng) } }, required: [city] } } }第二件事是模型“做決定”。你把用戶(hù)消息和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é)果后才能生成最終的自然語(yǔ)言回答。整個(gè)過(guò)程需要兩次或更多次請(qǐng)求通常叫“兩輪往返”。2.2 一個(gè)完整的調(diào)用流程示例我用一段接近真實(shí)項(xiàng)目的代碼來(lái)展示這個(gè)流程。為了不依賴(lài)某個(gè)特定SDK這里用最通用的HTTP請(qǐng)求結(jié)構(gòu)說(shuō)明import json import requests # 第一步構(gòu)造請(qǐng)求帶上工具定義和用戶(hù)問(wèn)題 payload { model: your-model-name, messages: [ {role: user, content: 北京今天適合出門(mén)嗎我想知道明天會(huì)不會(huì)下雨} ], tools: [ { type: function, function: { name: get_weather, description: 查詢(xún)指定城市的實(shí)時(shí)天氣和未來(lái)三天的預(yù)報(bào), parameters: { type: object, properties: { city: {type: string, description: 城市名稱(chēng)} }, 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)這段代碼看起來(lái)簡(jiǎn)單但實(shí)際項(xiàng)目里需要處理的細(xì)節(jié)比這個(gè)多得多多個(gè)工具并行調(diào)用、工具執(zhí)行異常、超時(shí)、結(jié)果太長(zhǎng)、參數(shù)校驗(yàn)失敗……我后面匯到問(wèn)題清單里統(tǒng)一講。2.3 工具描述怎么寫(xiě)模型才不會(huì)亂調(diào)這是Function Calling里最容易出問(wèn)題的地方。很多同學(xué)把description寫(xiě)得特別簡(jiǎn)單類(lèi)似“查詢(xún)天氣”結(jié)果模型經(jīng)常搞不清楚要填什么參數(shù)、返回什么格式。我總結(jié)出了一套描述寫(xiě)法核心是“四個(gè)說(shuō)清”說(shuō)清工具用途不要只寫(xiě)“獲取庫(kù)存”要寫(xiě)“查詢(xún)指定SKU在當(dāng)前倉(cāng)位的實(shí)時(shí)庫(kù)存數(shù)量返回在庫(kù)數(shù)和可售數(shù)”說(shuō)清每個(gè)參數(shù)的含義city這個(gè)字段要說(shuō)明格式比如“城市中文名例如杭州、成都”說(shuō)清參數(shù)的限制條件比如“日期格式為YYYY-MM-DD不得早于今天”說(shuō)清返回結(jié)果的格式比如“返回JSON包含字段temperature和humidity溫度單位為攝氏度”打個(gè)比方工具描述就是給模型看的“產(chǎn)品說(shuō)明書(shū)”說(shuō)明書(shū)寫(xiě)得越清楚模型這個(gè)“用戶(hù)”就越不會(huì)用錯(cuò)。而且描述文字本身也會(huì)參與模型token計(jì)算太長(zhǎng)浪費(fèi)太短誤事需要反復(fù)打磨到一個(gè)平衡點(diǎn)。2.4 工具調(diào)用的幾個(gè)關(guān)鍵參數(shù)和進(jìn)階玩法在實(shí)際項(xiàng)目里有下面幾個(gè)參數(shù)值得專(zhuān)門(mén)研究。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è)置提醒”這類(lèi)沒(méi)有依賴(lài)關(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是用戶(hù)正在使用的AI應(yīng)用比如一個(gè)桌面客戶(hù)端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ì)于沒(méi)有接觸過(guò)MCP的人來(lái)說(shuō)可以把它想象成一個(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類(lèi)。下面是一個(gè)包含兩個(gè)工具的迷你服務(wù)器能在五分鐘內(nèi)跑起來(lái)from mcp.server.fastmcp import FastMCP import json # 創(chuàng)建一個(gè)MCP服務(wù)器實(shí)例名稱(chēng)會(huì)顯示在客戶(hù)端列表里 mcp FastMCP(namedemo-tools-server) mcp.tool() def get_stock_price(symbol: str) - str: 查詢(xún)指定股票代碼的最新價(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)容長(zhǎng)度不超過(guò)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ù)的類(lèi)型注解和函數(shù)文檔里生成JSON Schema。也就是說(shuō)函數(shù)簽名里的symbol: str和文檔字符串的Args說(shuō)明最終會(huì)變成tools/list返回的inputSchema。這意味著寫(xiě)好一個(gè)函數(shù)就相當(dāng)于定義好了一個(gè)工具不需要像Function Calling那樣單獨(dú)維護(hù)一份JSON Schema。不過(guò)這也帶來(lái)一個(gè)隱藏問(wèn)題很多Python函數(shù)用Union、Literal、List這些類(lèi)型時(shí)FastMCP能智能轉(zhuǎn)化但如果函數(shù)里有復(fù)雜自定義類(lèi)型它會(huì)自動(dòng)把類(lèi)型轉(zhuǎn)成object參數(shù)描述就丟失了。遇到這種情況可以用Pydantic的Field來(lái)補(bǔ)充字段描述保持工具定義的質(zhì)量。3.3 傳輸方式的選擇stdio還是Streamable HTTPMCP支持不同的傳輸通道最常見(jiàn)的兩種是本地場(chǎng)景的stdio和跨服務(wù)的Streamable HTTP。mcp.run()默認(rèn)走stdio模式。在這種方式下Client啟動(dòng)一個(gè)子進(jìn)程來(lái)運(yùn)行Server腳本通過(guò)標(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)程客戶(hù)端使用就得走Streamable HTTP模式。通常做法是用一個(gè)Web框架比如FastAPI包一層或者直接用SDK提供的StreamableHTTPTransport。這種模式需要額外處理鑒權(quán)、跨域和并發(fā)問(wèn)題但好處是服務(wù)可以復(fù)用、集中部署、統(tǒng)一升級(jí)。我自己在項(xiàng)目里一般按這個(gè)規(guī)則選只在本地給某個(gè)單一工具用選stdio如果Server要給多個(gè)不同應(yīng)用共享或者要部署到服務(wù)器上直接上HTTP模式。3.4 客戶(hù)端接入MCP Server的完整步驟接入MCP的客戶(hù)端端目前主流做法是用不同語(yǔ)言的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)工具的過(guò)程標(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è)問(wèn)題如果你在MCP Server里封裝了一個(gè)“執(zhí)行SQL”的工具任何鏈接到這個(gè)Server的客戶(hù)端都等于拿到了數(shù)據(jù)庫(kù)執(zhí)行權(quán)限。我見(jiàn)過(guò)一些開(kāi)發(fā)者在本地MCP服務(wù)器里放了刪除數(shù)據(jù)的工具當(dāng)時(shí)的場(chǎng)景是自用調(diào)試但如果哪天被其他應(yīng)用連進(jìn)來(lái)風(fēng)險(xiǎn)非常大。效率方面一個(gè)常見(jiàn)的坑是Server在tools/list里注冊(cè)了大量工具而每次請(qǐng)求模型都需要處理全部工具描述。MCP本身的工具發(fā)現(xiàn)機(jī)制會(huì)讓任何支持MCP的客戶(hù)端自動(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)常被問(wèn)到一句話既然Function Calling這么好用為什么還要折騰MCP反過(guò)來(lái)也有人問(wèn)MCP這么標(biāo)準(zhǔn)是不是以后不用寫(xiě)Function Calling了我的看法是這兩個(gè)東西不是同一個(gè)層次的問(wèn)題與其糾結(jié)誰(shuí)取代誰(shuí)不如看它們?cè)陧?xiàng)目里的落點(diǎn)。從工具定義方式看Function Calling的工具是“注冊(cè)”到每次API請(qǐng)求里的你調(diào)一次Model API就要把工具定義帶一次。MCP的工具是“掛”在一個(gè)獨(dú)立Server上的客戶(hù)端通過(guò)協(xié)議發(fā)現(xiàn)工具。這意味著MCP的工具天然可以被多個(gè)應(yīng)用復(fù)用而Function Calling的工具更像是單次會(huì)話內(nèi)的臨時(shí)配置。從生態(tài)兼容看Function Calling強(qiáng)依賴(lài)模型廠商對(duì)協(xié)議的支持你換一家模型可能要檢查參數(shù)細(xì)節(jié)是否一致。MCP則偏模型無(wú)關(guān)客戶(hù)端只面向標(biāo)準(zhǔn)的MCP協(xié)議模型怎么接進(jìn)去是客戶(hù)端內(nèi)部的事。從靈活程度看Function Calling的處理鏈條更短流程控制更容易。MCP多了一層Server進(jìn)程或遠(yuǎn)程服務(wù)多一個(gè)環(huán)節(jié)就多一分故障可能性排查鏈路更長(zhǎng)。我在實(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包一層避開(kāi)了每個(gè)項(xiàng)目重復(fù)寫(xiě)服務(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讓模型通過(guò)這個(gè)“通用工具”去間接使用MCP里的工具。這種“網(wǎng)關(guān)模式”有一種很直觀的好處模型每次只需要看一個(gè)工具定義不需要把幾十個(gè)MCP工具全塞進(jìn)上下文省token。同時(shí)MCP Server端新增工具時(shí)不用改模型側(cè)的tools配置因?yàn)槟Ｐ椭恍枰馈巴ㄟ^(guò)通用調(diào)用器去訪問(wèn)任何MCP工具”這一個(gè)入口。但模式也有明顯的副作用模型可能不知道某個(gè)具體工具的存在和使用規(guī)則因?yàn)镸CP里的工具描述沒(méi)有被模型看到。解決的辦法是在MCP Server的工具命名和描述上下狠功夫盡量讓工具名自解釋同時(shí)在mcp_call_tool的描述里把常用工具體驗(yàn)寫(xiě)成“使用指南”。簡(jiǎn)單說(shuō)這種方案的成敗取決于你寫(xiě)工具描述的能力比單純的Function Calling更依賴(lài)文案功底。4.3 從“能用”到“好用”還要補(bǔ)齊三塊配置不管選了哪條路想跑出一個(gè)穩(wěn)定可靠的Agent光有工具調(diào)用還不夠。以下三塊配置是經(jīng)驗(yàn)之談缺了某一塊后面很容易出問(wèn)題。第一塊是工具的統(tǒng)一錯(cuò)誤碼規(guī)范。工具執(zhí)行失敗時(shí)返回給模型的信息不能是一堆Python異常堆棧而應(yīng)該是一段結(jié)構(gòu)化的錯(cuò)誤描述包括錯(cuò)誤類(lèi)型、可修復(fù)建議、重試次數(shù)限制。比如查不到數(shù)據(jù)返回{error: NOT_FOUND, message: 未查詢(xún)到該城市的天氣數(shù)據(jù)}模型能理解并產(chǎn)生合適的回復(fù)。如果直接把KeyError堆棧丟過(guò)去模型也只能干瞪眼。第二塊是全局的“最大重試和最大步數(shù)”控制。Agent調(diào)用工具的時(shí)候很容易陷入死循環(huán)模型不斷調(diào)用同一個(gè)失敗的工具或者來(lái)回調(diào)兩個(gè)相互依賴(lài)的工具。建議在Agent循環(huán)外面加一個(gè)計(jì)數(shù)器超過(guò)5輪后強(qiáng)制停止并觸發(fā)一個(gè)“請(qǐng)直接回復(fù)用戶(hù)當(dāng)前拿到的信息不要再調(diào)用工具”的系統(tǒng)指令。第三塊是完整請(qǐng)求日志。每次入?yún)?、工具調(diào)用、返回結(jié)果、token計(jì)數(shù)全部記錄成結(jié)構(gòu)化日志。我見(jiàn)過(guò)太多項(xiàng)目模型行為異常時(shí)只能靠猜。有了完整鏈路日志你能快速定位是模型選錯(cuò)工具還是工具返回?cái)?shù)據(jù)異常還是上下文被撐爆。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄寫(xiě)到這里我把實(shí)際開(kāi)發(fā)中踩過(guò)的高頻問(wèn)題整理成一張速查表按癥狀、原因、解法三條線來(lái)描述。癥狀原因解法模型反復(fù)調(diào)用同一個(gè)工具陷入死循環(huán)工具返回的結(jié)果讓模型覺(jué)得沒(méi)拿到信息檢查工具返回結(jié)構(gòu)是否清晰錯(cuò)誤信息是否包含建議動(dòng)作模型完全不調(diào)用工具直接編答案工具描述不具體模型沒(méi)意識(shí)到該調(diào)用重寫(xiě)description明確“不調(diào)用工具無(wú)法回答”的場(chǎng)景工具返回JSON模型卻理解錯(cuò)返回內(nèi)容不是JSON或字段含義模糊統(tǒng)一返回JSON并在工具描述中說(shuō)明字段單位與取值多工具并行調(diào)用時(shí)結(jié)果對(duì)不上忽略了tool_call_id的一一匹配逐個(gè)遍歷tool_calls按tool_call_id回傳MCP客戶(hù)端連不上stdio ServerServer啟動(dòng)報(bào)錯(cuò)或依賴(lài)包沒(méi)裝先把Server腳本單獨(dú)跑一遍確認(rèn)能正常啟動(dòng)再連客戶(hù)端MCP工具列表為空Server加載了模塊但沒(méi)注冊(cè)任何tool檢查是否用mcp.tool()裝飾確認(rèn)裝飾器作用范圍上下文塞滿(mǎn)導(dǎo)致后續(xù)回答錯(cuò)亂每次請(qǐng)求都帶完整工具描述和歷史消息用“網(wǎng)關(guān)模式”精簡(jiǎn)工具描述或?qū)v史消息做裁剪總結(jié)模型調(diào)用了不存在的工具名工具定義與模型內(nèi)置知識(shí)沖突在描述里加上“如無(wú)此工具請(qǐng)不要假設(shè)其存在”的說(shuō)明或檢查工具命名是否有歧義這里面有兩個(gè)問(wèn)題我想特別展開(kāi)因?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ù)庫(kù)表的所有記錄如果是海量數(shù)據(jù)直接把原始內(nèi)容喂回給模型光token費(fèi)用就足夠嚇人。正確做法是在工具端做“結(jié)果精簡(jiǎn)”只返回模型判斷所需要的摘要信息。比如要查詢(xún)用戶(hù)訂單工具端可以先做分頁(yè)或只返回最近五條。這個(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ī)劃下周三北京到上海的行程天氣不好就改訂高鐵”這類(lèi)任務(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)用是無(wú)狀態(tài)的但Agent必須是有狀態(tài)的。建議在工具調(diào)用之外增加一個(gè)“狀態(tài)槽”機(jī)制每次模型完成一步操作就把結(jié)果摘要寫(xiě)入狀態(tài)槽后續(xù)步驟直接讀取狀態(tài)槽而不是重新把全部歷史消息一股腦帶回模型。這個(gè)方法有兩個(gè)好處。一是省token長(zhǎng)對(duì)話場(chǎng)景下效果非常明顯二是隔離噪聲早期環(huán)節(jié)的信息如果對(duì)當(dāng)前環(huán)節(jié)沒(méi)有幫助就不用再浪費(fèi)模型注意力。最簡(jiǎn)單的實(shí)現(xiàn)是用一個(gè)全局字典存狀態(tài)字段復(fù)雜一點(diǎn)則可以用向量數(shù)據(jù)庫(kù)做記憶檢索。6.3 最后分享一個(gè)讓我少踩很多坑的習(xí)慣從一開(kāi)始做工具調(diào)用到現(xiàn)在我最大的感受是不要試圖一次性把工具調(diào)用鏈路調(diào)通再全部上線這樣做太容易炸。我的習(xí)慣是永遠(yuǎn)先跑通“一個(gè)工具的最小閉環(huán)”用最簡(jiǎn)單的查詢(xún)工具從用戶(hù)提問(wèn)到模型返回結(jié)果整個(gè)過(guò)程只調(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)用繞不開(kāi)的兩個(gè)詞。很多人花了不少時(shí)間把API文檔翻了個(gè)遍可真到自己寫(xiě)代碼的時(shí)候還是會(huì)卡在幾個(gè)關(guān)鍵問(wèn)題上工具描述到底怎么寫(xiě)模型才不犯迷糊MCP服務(wù)器和普通工具注冊(cè)到底有什么區(qū)別兩套方案到底什么時(shí)候選哪個(gè)這篇文章我打算把這些年實(shí)際踩過(guò)的坑、驗(yàn)證過(guò)的方法連同原理一起拆開(kāi)講清楚。這篇文章適合正在做智能體Agent、AI助手、自動(dòng)化流程的同學(xué)參考也適合那些剛把大模型API調(diào)通、準(zhǔn)備給模型裝上“手腳”的開(kāi)發(fā)者。里面不會(huì)只丟概念而是給出能直接抄作業(yè)的結(jié)構(gòu)、代碼思路和排查方案。1. 工具調(diào)用的整體思路為什么模型需要“手腳”1.1 模型不是只會(huì)聊天但它確實(shí)做不了“動(dòng)作”先想一個(gè)基本問(wèn)題大模型本身能做什么它能理解語(yǔ)義、生成文本、總結(jié)信息、改寫(xiě)代碼但本質(zhì)上它只是一個(gè)“預(yù)測(cè)下一個(gè)詞”的機(jī)器。你說(shuō)“幫我查一下這周的天氣順便訂個(gè)會(huì)議室”模型即使理解這句話也沒(méi)辦法自己去訪問(wèn)天氣接口更不可能去操作你的會(huì)議系統(tǒng)。要讓模型具備行動(dòng)能力就得在模型外面掛一層“工具層”。我們定義好一批函數(shù)或接口然后讓模型在需要的時(shí)候主動(dòng)選擇調(diào)用哪個(gè)、傳什么參數(shù)再把工具返回的結(jié)果交給模型繼續(xù)處理。這整個(gè)鏈路就是大家常說(shuō)的工具調(diào)用。最早的做法非常簡(jiǎn)單粗暴把工具的描述連同一個(gè)“輸出JSON格式”的指令硬塞進(jìn)提示詞里讓模型把“想調(diào)用的函數(shù)名參數(shù)”以JSON文本吐出來(lái)然后我們自己去解析。這套方案最大的問(wèn)題是模型經(jīng)常輸出格式不穩(wěn)定的JSON函數(shù)名偶爾會(huì)憑空捏造參數(shù)類(lèi)型也可能對(duì)不上。后來(lái)主流大模型API陸續(xù)推出了結(jié)構(gòu)化的函數(shù)調(diào)用能力也就是Function Calling模型不再輸出“看起來(lái)像JSON的字符串”而是直接返回結(jié)構(gòu)化的工具調(diào)用對(duì)象從協(xié)議層面解決了格式問(wèn)題。1.2 MCP想解決的是另一個(gè)問(wèn)題Function Calling解決的是“模型和工具之間的通信格式”但它沒(méi)解決“工具怎么接入”的問(wèn)題。每個(gè)工具都要單獨(dú)適配每個(gè)應(yīng)用都要自己寫(xiě)一套工具注冊(cè)、鑒權(quán)、參數(shù)校驗(yàn)的代碼。做過(guò)三四個(gè)Agent項(xiàng)目就會(huì)發(fā)現(xiàn)光是把不同的內(nèi)部系統(tǒng)、外部API一個(gè)個(gè)接進(jìn)來(lái)就夠?qū)憥浊心z水代碼。MCP的定位就是一個(gè)標(biāo)準(zhǔn)化的“工具接入層”。它定義了應(yīng)用Host、客戶(hù)端Client和工具服務(wù)端Server之間的通信協(xié)議。你把一個(gè)數(shù)據(jù)源或工具封裝成一個(gè)MCP Server任何支持MCP的客戶(hù)端都能直接發(fā)現(xiàn)它、調(diào)用它不需要為每個(gè)應(yīng)用重復(fù)改代碼。類(lèi)比一下如果Function Calling是“統(tǒng)一了打電話的接線術(shù)語(yǔ)”MCP就是“統(tǒng)一了電話線接口、撥號(hào)規(guī)則和電話號(hào)碼簿格式還制定了電話亭的尺寸”。兩者解決的問(wèn)題層次不同。從實(shí)際選型來(lái)看目前比較合理的思路是這樣的方案解決的問(wèn)題適配場(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)于你把工具的“說(shuō)明書(shū)”喂給模型看。一個(gè)典型的工具定義長(zhǎng)這樣{ type: function, function: { name: get_weather, description: 查詢(xún)指定城市的實(shí)時(shí)天氣和未來(lái)三天的預(yù)報(bào)參數(shù)city為城市名稱(chēng)例如北京、上海、廣州, parameters: { type: object, properties: { city: { type: string, description: 要查詢(xún)的城市名稱(chēng) } }, required: [city] } } }第二件事是模型“做決定”。你把用戶(hù)消息和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é)果后才能生成最終的自然語(yǔ)言回答。整個(gè)過(guò)程需要兩次或更多次請(qǐng)求通常叫“兩輪往返”。2.2 一個(gè)完整的調(diào)用流程示例我用一段接近真實(shí)項(xiàng)目的代碼來(lái)展示這個(gè)流程。為了不依賴(lài)某個(gè)特定SDK這里用最通用的HTTP請(qǐng)求結(jié)構(gòu)說(shuō)明import json import requests # 第一步構(gòu)造請(qǐng)求帶上工具定義和用戶(hù)問(wèn)題 payload { model: your-model-name, messages: [ {role: user, content: 北京今天適合出門(mén)嗎我想知道明天會(huì)不會(huì)下雨} ], tools: [ { type: function, function: { name: get_weather, description: 查詢(xún)指定城市的實(shí)時(shí)天氣和未來(lái)三天的預(yù)報(bào), parameters: { type: object, properties: { city: {type: string, description: 城市名稱(chēng)} }, 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)這段代碼看起來(lái)簡(jiǎn)單但實(shí)際項(xiàng)目里需要處理的細(xì)節(jié)比這個(gè)多得多多個(gè)工具并行調(diào)用、工具執(zhí)行異常、超時(shí)、結(jié)果太長(zhǎng)、參數(shù)校驗(yàn)失敗……我后面匯到問(wèn)題清單里統(tǒng)一講。2.3 工具描述怎么寫(xiě)模型才不會(huì)亂調(diào)這是Function Calling里最容易出問(wèn)題的地方。很多同學(xué)把description寫(xiě)得特別簡(jiǎn)單類(lèi)似“查詢(xún)天氣”結(jié)果模型經(jīng)常搞不清楚要填什么參數(shù)、返回什么格式。我總結(jié)出了一套描述寫(xiě)法核心是“四個(gè)說(shuō)清”說(shuō)清工具用途不要只寫(xiě)“獲取庫(kù)存”要寫(xiě)“查詢(xún)指定SKU在當(dāng)前倉(cāng)位的實(shí)時(shí)庫(kù)存數(shù)量返回在庫(kù)數(shù)和可售數(shù)”說(shuō)清每個(gè)參數(shù)的含義city這個(gè)字段要說(shuō)明格式比如“城市中文名例如杭州、成都”說(shuō)清參數(shù)的限制條件比如“日期格式為YYYY-MM-DD不得早于今天”說(shuō)清返回結(jié)果的格式比如“返回JSON包含字段temperature和humidity溫度單位為攝氏度”打個(gè)比方工具描述就是給模型看的“產(chǎn)品說(shuō)明書(shū)”說(shuō)明書(shū)寫(xiě)得越清楚模型這個(gè)“用戶(hù)”就越不會(huì)用錯(cuò)。而且描述文字本身也會(huì)參與模型token計(jì)算太長(zhǎng)浪費(fèi)太短誤事需要反復(fù)打磨到一個(gè)平衡點(diǎn)。2.4 工具調(diào)用的幾個(gè)關(guān)鍵參數(shù)和進(jìn)階玩法在實(shí)際項(xiàng)目里有下面幾個(gè)參數(shù)值得專(zhuān)門(mén)研究。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è)置提醒”這類(lèi)沒(méi)有依賴(lài)關(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是用戶(hù)正在使用的AI應(yīng)用比如一個(gè)桌面客戶(hù)端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ì)于沒(méi)有接觸過(guò)MCP的人來(lái)說(shuō)可以把它想象成一個(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類(lèi)。下面是一個(gè)包含兩個(gè)工具的迷你服務(wù)器能在五分鐘內(nèi)跑起來(lái)from mcp.server.fastmcp import FastMCP import json # 創(chuàng)建一個(gè)MCP服務(wù)器實(shí)例名稱(chēng)會(huì)顯示在客戶(hù)端列表里 mcp FastMCP(namedemo-tools-server) mcp.tool() def get_stock_price(symbol: str) - str: 查詢(xún)指定股票代碼的最新價(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)容長(zhǎng)度不超過(guò)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ù)的類(lèi)型注解和函數(shù)文檔里生成JSON Schema。也就是說(shuō)函數(shù)簽名里的symbol: str和文檔字符串的Args說(shuō)明最終會(huì)變成tools/list返回的inputSchema。這意味著寫(xiě)好一個(gè)函數(shù)就相當(dāng)于定義好了一個(gè)工具不需要像Function Calling那樣單獨(dú)維護(hù)一份JSON Schema。不過(guò)這也帶來(lái)一個(gè)隱藏問(wèn)題很多Python函數(shù)用Union、Literal、List這些類(lèi)型時(shí)FastMCP能智能轉(zhuǎn)化但如果函數(shù)里有復(fù)雜自定義類(lèi)型它會(huì)自動(dòng)把類(lèi)型轉(zhuǎn)成object參數(shù)描述就丟失了。遇到這種情況可以用Pydantic的Field來(lái)補(bǔ)充字段描述保持工具定義的質(zhì)量。3.3 傳輸方式的選擇stdio還是Streamable HTTPMCP支持不同的傳輸通道最常見(jiàn)的兩種是本地場(chǎng)景的stdio和跨服務(wù)的Streamable HTTP。mcp.run()默認(rèn)走stdio模式。在這種方式下Client啟動(dòng)一個(gè)子進(jìn)程來(lái)運(yùn)行Server腳本通過(guò)標(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)程客戶(hù)端使用就得走Streamable HTTP模式。通常做法是用一個(gè)Web框架比如FastAPI包一層或者直接用SDK提供的StreamableHTTPTransport。這種模式需要額外處理鑒權(quán)、跨域和并發(fā)問(wèn)題但好處是服務(wù)可以復(fù)用、集中部署、統(tǒng)一升級(jí)。我自己在項(xiàng)目里一般按這個(gè)規(guī)則選只在本地給某個(gè)單一工具用選stdio如果Server要給多個(gè)不同應(yīng)用共享或者要部署到服務(wù)器上直接上HTTP模式。3.4 客戶(hù)端接入MCP Server的完整步驟接入MCP的客戶(hù)端端目前主流做法是用不同語(yǔ)言的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)工具的過(guò)程標(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è)問(wèn)題如果你在MCP Server里封裝了一個(gè)“執(zhí)行SQL”的工具任何鏈接到這個(gè)Server的客戶(hù)端都等于拿到了數(shù)據(jù)庫(kù)執(zhí)行權(quán)限。我見(jiàn)過(guò)一些開(kāi)發(fā)者在本地MCP服務(wù)器里放了刪除數(shù)據(jù)的工具當(dāng)時(shí)的場(chǎng)景是自用調(diào)試但如果哪天被其他應(yīng)用連進(jìn)來(lái)風(fēng)險(xiǎn)非常大。效率方面一個(gè)常見(jiàn)的坑是Server在tools/list里注冊(cè)了大量工具而每次請(qǐng)求模型都需要處理全部工具描述。MCP本身的工具發(fā)現(xiàn)機(jī)制會(huì)讓任何支持MCP的客戶(hù)端自動(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)常被問(wèn)到一句話既然Function Calling這么好用為什么還要折騰MCP反過(guò)來(lái)也有人問(wèn)MCP這么標(biāo)準(zhǔn)是不是以后不用寫(xiě)Function Calling了我的看法是這兩個(gè)東西不是同一個(gè)層次的問(wèn)題與其糾結(jié)誰(shuí)取代誰(shuí)不如看它們?cè)陧?xiàng)目里的落點(diǎn)。從工具定義方式看Function Calling的工具是“注冊(cè)”到每次API請(qǐng)求里的你調(diào)一次Model API就要把工具定義帶一次。MCP的工具是“掛”在一個(gè)獨(dú)立Server上的客戶(hù)端通過(guò)協(xié)議發(fā)現(xiàn)工具。這意味著MCP的工具天然可以被多個(gè)應(yīng)用復(fù)用而Function Calling的工具更像是單次會(huì)話內(nèi)的臨時(shí)配置。從生態(tài)兼容看Function Calling強(qiáng)依賴(lài)模型廠商對(duì)協(xié)議的支持你換一家模型可能要檢查參數(shù)細(xì)節(jié)是否一致。MCP則偏模型無(wú)關(guān)客戶(hù)端只面向標(biāo)準(zhǔn)的MCP協(xié)議模型怎么接進(jìn)去是客戶(hù)端內(nèi)部的事。從靈活程度看Function Calling的處理鏈條更短流程控制更容易。MCP多了一層Server進(jìn)程或遠(yuǎn)程服務(wù)多一個(gè)環(huán)節(jié)就多一分故障可能性排查鏈路更長(zhǎng)。我在實(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包一層避開(kāi)了每個(gè)項(xiàng)目重復(fù)寫(xiě)服務(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讓模型通過(guò)這個(gè)“通用工具”去間接使用MCP里的工具。這種“網(wǎng)關(guān)模式”有一種很直觀的好處模型每次只需要看一個(gè)工具定義不需要把幾十個(gè)MCP工具全塞進(jìn)上下文省token。同時(shí)MCP Server端新增工具時(shí)不用改模型側(cè)的tools配置因?yàn)槟Ｐ椭恍枰馈巴ㄟ^(guò)通用調(diào)用器去訪問(wèn)任何MCP工具”這一個(gè)入口。但模式也有明顯的副作用模型可能不知道某個(gè)具體工具的存在和使用規(guī)則因?yàn)镸CP里的工具描述沒(méi)有被模型看到。解決的辦法是在MCP Server的工具命名和描述上下狠功夫盡量讓工具名自解釋同時(shí)在mcp_call_tool的描述里把常用工具體驗(yàn)寫(xiě)成“使用指南”。簡(jiǎn)單說(shuō)這種方案的成敗取決于你寫(xiě)工具描述的能力比單純的Function Calling更依賴(lài)文案功底。4.3 從“能用”到“好用”還要補(bǔ)齊三塊配置不管選了哪條路想跑出一個(gè)穩(wěn)定可靠的Agent光有工具調(diào)用還不夠。以下三塊配置是經(jīng)驗(yàn)之談缺了某一塊后面很容易出問(wèn)題。第一塊是工具的統(tǒng)一錯(cuò)誤碼規(guī)范。工具執(zhí)行失敗時(shí)返回給模型的信息不能是一堆Python異常堆棧而應(yīng)該是一段結(jié)構(gòu)化的錯(cuò)誤描述包括錯(cuò)誤類(lèi)型、可修復(fù)建議、重試次數(shù)限制。比如查不到數(shù)據(jù)返回{error: NOT_FOUND, message: 未查詢(xún)到該城市的天氣數(shù)據(jù)}模型能理解并產(chǎn)生合適的回復(fù)。如果直接把KeyError堆棧丟過(guò)去模型也只能干瞪眼。第二塊是全局的“最大重試和最大步數(shù)”控制。Agent調(diào)用工具的時(shí)候很容易陷入死循環(huán)模型不斷調(diào)用同一個(gè)失敗的工具或者來(lái)回調(diào)兩個(gè)相互依賴(lài)的工具。建議在Agent循環(huán)外面加一個(gè)計(jì)數(shù)器超過(guò)5輪后強(qiáng)制停止并觸發(fā)一個(gè)“請(qǐng)直接回復(fù)用戶(hù)當(dāng)前拿到的信息不要再調(diào)用工具”的系統(tǒng)指令。第三塊是完整請(qǐng)求日志。每次入?yún)?、工具調(diào)用、返回結(jié)果、token計(jì)數(shù)全部記錄成結(jié)構(gòu)化日志。我見(jiàn)過(guò)太多項(xiàng)目模型行為異常時(shí)只能靠猜。有了完整鏈路日志你能快速定位是模型選錯(cuò)工具還是工具返回?cái)?shù)據(jù)異常還是上下文被撐爆。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄寫(xiě)到這里我把實(shí)際開(kāi)發(fā)中踩過(guò)的高頻問(wèn)題整理成一張速查表按癥狀、原因、解法三條線來(lái)描述。癥狀原因解法模型反復(fù)調(diào)用同一個(gè)工具陷入死循環(huán)工具返回的結(jié)果讓模型覺(jué)得沒(méi)拿到信息檢查工具返回結(jié)構(gòu)是否清晰錯(cuò)誤信息是否包含建議動(dòng)作模型完全不調(diào)用工具直接編答案工具描述不具體模型沒(méi)意識(shí)到該調(diào)用重寫(xiě)description明確“不調(diào)用工具無(wú)法回答”的場(chǎng)景工具返回JSON模型卻理解錯(cuò)返回內(nèi)容不是JSON或字段含義模糊統(tǒng)一返回JSON并在工具描述中說(shuō)明字段單位與取值多工具并行調(diào)用時(shí)結(jié)果對(duì)不上忽略了tool_call_id的一一匹配逐個(gè)遍歷tool_calls按tool_call_id回傳MCP客戶(hù)端連不上stdio ServerServer啟動(dòng)報(bào)錯(cuò)或依賴(lài)包沒(méi)裝先把Server腳本單獨(dú)跑一遍確認(rèn)能正常啟動(dòng)再連客戶(hù)端MCP工具列表為空Server加載了模塊但沒(méi)注冊(cè)任何tool檢查是否用mcp.tool()裝飾確認(rèn)裝飾器作用范圍上下文塞滿(mǎn)導(dǎo)致后續(xù)回答錯(cuò)亂每次請(qǐng)求都帶完整工具描述和歷史消息用“網(wǎng)關(guān)模式”精簡(jiǎn)工具描述或?qū)v史消息做裁剪總結(jié)模型調(diào)用了不存在的工具名工具定義與模型內(nèi)置知識(shí)沖突在描述里加上“如無(wú)此工具請(qǐng)不要假設(shè)其存在”的說(shuō)明或檢查工具命名是否有歧義這里面有兩個(gè)問(wèn)題我想特別展開(kāi)因?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ù)庫(kù)表的所有記錄如果是海量數(shù)據(jù)直接把原始內(nèi)容喂回給模型光token費(fèi)用就足夠嚇人。正確做法是在工具端做“結(jié)果精簡(jiǎn)”只返回模型判斷所需要的摘要信息。比如要查詢(xún)用戶(hù)訂單工具端可以先做分頁(yè)或只返回最近五條。這個(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ī)劃下周三北京到上海的行程天氣不好就改訂高鐵”這類(lèi)任務(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)用是無(wú)狀態(tài)的但Agent必須是有狀態(tài)的。建議在工具調(diào)用之外增加一個(gè)“狀態(tài)槽”機(jī)制每次模型完成一步操作就把結(jié)果摘要寫(xiě)入狀態(tài)槽后續(xù)步驟直接讀取狀態(tài)槽而不是重新把全部歷史消息一股腦帶回模型。這個(gè)方法有兩個(gè)好處。一是省token長(zhǎng)對(duì)話場(chǎng)景下效果非常明顯二是隔離噪聲早期環(huán)節(jié)的信息如果對(duì)當(dāng)前環(huán)節(jié)沒(méi)有幫助就不用再浪費(fèi)模型注意力。最簡(jiǎn)單的實(shí)現(xiàn)是用一個(gè)全局字典存狀態(tài)字段復(fù)雜一點(diǎn)則可以用向量數(shù)據(jù)庫(kù)做記憶檢索。6.3 最后分享一個(gè)讓我少踩很多坑的習(xí)慣從一開(kāi)始做工具調(diào)用到現(xiàn)在我最大的感受是不要試圖一次性把工具調(diào)用鏈路調(diào)通再全部上線這樣做太容易炸。我的習(xí)慣是永遠(yuǎn)先跑通“一個(gè)工具的最小閉環(huán)”用最簡(jiǎn)單的查詢(xún)工具從用戶(hù)提問(wèn)到模型返回結(jié)果整個(gè)過(guò)程只調(diào)用一次工具全部打通、打點(diǎn)記錄完整再往外面擴(kuò)展第二個(gè)、第三個(gè)工具。每加一個(gè)工具都回歸一遍這個(gè)最小閉環(huán)。雖然慢但穩(wěn)定性是普通項(xiàng)目很難比的。等工具數(shù)量多了再按這個(gè)思路去沉淀成通用的Agent框架后面的項(xiàng)目就能直接用這套地基去建房子了。