1. 先搞清楚 LangChain Agent、MCP 和 Skills 到底能幫你解決什么如果你正在用 Claude、GPT 這類大模型但總覺得它們像個“萬事通萬事松”——什么都知道一點但一到具體操作比如查數據庫、調 API、操作本地文件就只會說“我無法直接操作”那你現在遇到的問題LangChain Agent 加上 MCP 和 Skills 這套組合就是目前最主流的工程化解決方案。簡單來說它的核心價值是讓大模型從一個“聊天顧問”變成一個能真正“動手執行”的智能助手。你不再需要手動復制模型輸出的代碼或命令去執行而是告訴 Agent 你的目標它就能自主規劃、調用工具Skills、完成任務并把最終結果返回給你。這里涉及三個關鍵角色LangChain Agent 你可以把它理解為一個“大腦”或“調度中心”。它負責理解你的指令比如“幫我分析一下上個月的銷售數據”然后決定先做什么、后做什么調用哪個工具并解析工具返回的結果。MCP 全稱是 Model Context Protocol你可以把它看作一套“工具接入標準”或“通信協議”。它定義了工具Skills如何以一種統一、標準化的方式把自己“能干什么”、“需要什么參數”告訴給 Agent。有了 MCPAgent 就能動態發現和調用各種工具而無需為每個工具寫死代碼。Skills 這就是具體的“工具”或“技能”。一個 Skill 就是一個具體的能力比如“讀取數據庫”、“發送郵件”、“查詢天氣”、“操作 Excel 文件”。通過 MCP 協議這些 Skills 被封裝成 Agent 可以理解和調用的格式。所以當有人討論“Claude 接入 Skills”、“Agent 開發”時他們本質上是在做同一件事構建一個能自動使用外部工具的大模型應用。這對于需要將 AI 能力嵌入到具體工作流如數據分析、自動化辦公、智能客服的場景來說是效率提升的關鍵。2. 環境準備與核心依賴別在第一步就卡住在開始寫代碼之前先把環境理順。很多“跑不起來”的問題都出在環境配置和依賴版本上。這里我按實際落地的順序帶你過一遍。2.1 基礎 Python 環境與關鍵包首先你需要一個 Python 環境建議 3.8 以上。我強烈建議使用虛擬環境venv或conda來隔離項目依賴。核心的 Python 包主要有以下幾個pip install langchain langchain-communitylangchain是核心框架langchain-community包含了大量社區貢獻的工具、集成和工具。版本注意LangChain 迭代很快API 可能有變動。如果遇到某些類或函數找不到第一反應是去查對應版本的官方文檔而不是盲目搜索。這是新手最容易踩的坑。2.2 大模型 API 密鑰Agent 的“大腦”需要一個大模型來驅動。你需要準備一個 LLM 提供商的 API Key。OpenAI / Azure OpenAI 最常用生態最成熟。你需要OPENAI_API_KEY。Anthropic Claude 在長上下文和復雜指令遵循上表現很好。你需要ANTHROPIC_API_KEY。其他如DeepSeek、智譜、月之暗面等國內外的模型只要 LangChain 支持都可以。將 API Key 設置為環境變量這是最安全、最方便的做法# Linux/macOS export OPENAI_API_KEYyour-api-key-here # Windows (PowerShell) $env:OPENAI_API_KEYyour-api-key-here或者在代碼中通過os.environ[“OPENAI_API_KEY”] “your-key”設置不推薦用于生產環境。2.3 關于 MCP Server 和 Skills這是概念上最容易混淆的地方。MCP 是一個協議要實現它你需要一個MCP Server。這個 Server 負責管理一個或多個Skills并以標準格式向 Agent 暴露這些 Skills 的功能。目前你有幾種選擇來獲得 MCP Server 和 Skills使用現成的 MCP Server 一些項目或公司提供了開箱即用的 MCP Server里面集成了很多常用 Skills如文件操作、SQL查詢等。你需要運行這個 Server。自己實現 MCP Server 如果你有自定義的工具需要接入就需要按照 MCP 協議規范自己編寫 Server 端代碼。這涉及到定義工具Tools的 Schema名稱、描述、參數。使用 LangChain 內置工具 對于快速驗證LangChain 的langchain.tools和langchain-community中已經有很多預定義的工具如WikipediaQueryRun,ShellTool。你可以先用這些工具構建一個簡單的 Agent理解流程再考慮接入更復雜的 MCP。對于初次嘗試我建議路線是先忽略“純 MCP”的實現復雜度直接用 LangChain 內置工具跑通一個 Agent。這能讓你快速建立對 Agent 工作流的直覺。理解了 Agent 如何調用 Tools 之后再去研究 MCP Server 的部署和連接會順暢很多。3. 從零構建你的第一個 LangChain Agent我們從一個最簡單的例子開始創建一個能使用搜索引擎和計算器的 Agent。這個例子不涉及 MCP Server但完整展示了 Agent 的核心工作流。3.1 定義工具Skills首先我們創建兩個工具一個用于網絡搜索一個用于數學計算。from langchain.tools import Tool, DuckDuckGoSearchRun from langchain.utilities import ArxivAPIWrapper import math # 工具1 網絡搜索使用 DuckDuckGo search DuckDuckGoSearchRun() search_tool Tool( nameWeb Search, funcsearch.run, descriptionUseful for when you need to answer questions about current events or general knowledge. Input should be a search query. ) # 工具2 計算器 def calculator_func(expression: str) - str: Evaluate a mathematical expression. Use only , -, *, /, **, ( ). try: # 警告直接使用 eval 有安全風險僅用于演示。生產環境應使用安全評估庫如 asteval。 result eval(expression, {__builtins__: None}, {math: math}) return str(result) except Exception as e: return fError evaluating expression: {e} calc_tool Tool( nameCalculator, funccalculator_func, descriptionUseful for performing arithmetic calculations. Input should be a valid mathematical expression as a string, e.g., 3 * 4 5. ) # 將工具放入列表 tools [search_tool, calc_tool]關鍵點每個Tool對象都必須有清晰的name、func執行函數和description。description至關重要因為 Agent大模型就是靠閱讀這些描述來決定在什么情況下使用哪個工具。3.2 初始化大模型和 Agent接下來我們選擇一個 LLM并用它和工具列表來創建 Agent。from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 1. 初始化 LLM llm ChatOpenAI(modelgpt-4o, temperature0) # 使用 gpt-4o溫度設為0保證穩定性 # 2. 獲取一個預設的提示詞模板。ReAct 是一個經典的 Agent 推理框架。 prompt hub.pull(hwchase17/react) # 3. 創建 Agent agent create_react_agent(llm, tools, prompt) # 4. 創建 Agent 執行器它負責運行 Agent 的循環思考 - 選擇工具 - 執行 - 觀察 - 再思考... agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue)verboseTrue會讓整個執行過程打印出來非常適合調試和學習。handle_parsing_errorsTrue很重要當模型輸出格式不符合 Agent 預期時它能防止程序直接崩潰而是嘗試讓模型重試。3.3 運行并觀察 Agent 思考過程現在讓我們問一個需要結合搜索和計算的問題。question “What was the GDP of the United States in 2023? If it grew by 2.5% in 2024, what would the projected GDP be?” result agent_executor.invoke({input: question}) print(f\n最終答案: {result[output]})當你運行這段代碼時在控制臺會看到類似以下的輸出verboseTrue的效果 Entering new AgentExecutor chain... I need to find the US GDP for 2023 first, then calculate the projected GDP for 2024 with a 2.5% growth. Action: Web Search Action Input: “United States GDP 2023” Observation: [Search result: The GDP of the United States in 2023 was approximately $27.36 trillion.] Thought: Now I have the 2023 GDP. I need to calculate 2.5% of that and add it to get the 2024 projection. Action: Calculator Action Input: “27360 * 0.025” Observation: 684 Thought: So the growth is $684 billion. Now add it to the 2023 GDP. Action: Calculator Action Input: “27360 684” Observation: 28044 Thought: The projected GDP for 2024 would be approximately $28.044 trillion. Final Answer: The GDP of the United States in 2023 was about $27.36 trillion. With a 2.5% growth in 2024, the projected GDP would be approximately $28.044 trillion. Finished chain. 最終答案: The GDP of the United States in 2023 was about $27.36 trillion. With a 2.5% growth in 2024, the projected GDP would be approximately $28.044 trillion.這就是 Agent 的核心魔力它自動完成了“規劃-執行-推理”的循環。你不需要告訴它先去搜索再去計算。你只給了最終目標它自己拆解了步驟。4. 進階接入真正的 MCP Server 與自定義 Skills當你理解了基礎 Agent 的工作流后就可以探索更工程化的 MCP 模式了。這里的核心變化是工具Skills不再直接寫在 Python 代碼里而是由一個獨立的 MCP Server 提供。4.1 理解 MCP 通信模型在 MCP 架構下你的應用Client通常是 LangChain Agent和工具提供方Server是分離的。它們通過標準化的 JSON-RPC 消息進行通信。Client 初始化 連接到 MCP Server。Server 宣告 Server 向 Client 發送它提供的所有 Tools 的列表及其 Schema。Agent 工作 當 Agent 決定使用某個工具時Client 會向 Server 發送一個call_tool請求。Server 執行 Server 執行對應的工具函數并將結果返回給 Client。Client 接收 Client 將結果交給 Agent 進行下一步推理。這種分離的好處是解耦 Skill 的開發者后端和 Agent 的開發者前端/應用層可以獨立工作。安全 敏感操作如數據庫訪問、服務器命令可以封裝在受控的 Server 環境中而不是在調用 LLM 的客戶端環境中。動態性 Server 可以隨時更新或添加新的 SkillsClient 無需修改代碼即可發現和使用。4.2 部署并連接一個簡單的 MCP Server假設我們已經有一個運行在http://localhost:8080的 MCP Server它提供了一個read_file的技能。我們需要讓 LangChain Agent 能調用它。LangChain 社區通常通過MCPClient來橋接。雖然 LangChain 核心庫對 MCP 的原生支持在演進中但一個常見的實踐模式是將 MCP Server 提供的工具“轉換”為 LangChain 能識別的Tool對象。下面是一個概念性的代碼示例展示了如何連接并封裝 MCP 工具# 假設我們有一個能與 MCP Server 通信的客戶端類 # 注意以下是一個示意流程具體實現取決于你使用的 MCP 客戶端庫。 import requests import json class SimpleMCPClient: def __init__(self, server_urlhttp://localhost:8080): self.server_url server_url self.tools self._list_tools() def _list_tools(self): 向 MCP Server 請求可用的工具列表 response requests.post(f{self.server_url}/list_tools) # MCP 協議有標準端點 return response.json() # 返回工具 schema 列表 def call_tool(self, tool_name, arguments): 調用指定的 MCP 工具 payload { jsonrpc: 2.0, method: call_tool, params: {name: tool_name, arguments: arguments}, id: 1 } response requests.post(f{self.server_url}/rpc, jsonpayload) result response.json() if error in result: raise Exception(fMCP Tool error: {result[error]}) return result[result] # 使用這個客戶端創建 LangChain Tool mcp_client SimpleMCPClient() def read_file_wrapper(file_path: str) - str: Wrapper function that calls the MCP servers read_file tool. return mcp_client.call_tool(read_file, {path: file_path}) mcp_file_tool Tool( nameread_file, funcread_file_wrapper, descriptionReads the contents of a file from the local filesystem. Input should be a valid file path string. ) # 現在你可以像使用普通工具一樣將 mcp_file_tool 加入到你的 Agent 工具列表中 tools.append(mcp_file_tool) # 然后用新的 tools 列表重新創建 agent_executor關鍵點 你需要一個實際的 MCP Server 在運行。你可以尋找開源實現例如一些項目提供的示例 Server或者根據 MCP 協議規范自己實現一個。連接的核心是將 MCP Server 的 RPC 調用封裝成 LangChainTool對象。4.3 開發一個自定義 SkillMCP Server 端如果你想自己提供 Skill就需要實現 MCP Server。這通常涉及以下步驟以 Python 為例選擇 MCP SDK 使用官方或社區提供的 MCP SDK例如mcp-sdk-python來簡化協議通信。定義工具函數 編寫實際執行操作的函數如數據庫查詢、調用外部 API。注冊工具 使用 SDK 將你的函數注冊為 MCP 工具并定義好輸入輸出的 JSON Schema。啟動 Server 啟動一個 HTTP 或 stdio 服務器等待 Client 連接。一個極簡的偽代碼示例# server.py (概念示例) from mcp_sdk import Server, Tool server Server(my-skills-server) server.tool( nameget_weather, descriptionGet current weather for a city., args_schema{“city”: {“type”: “string”, “description”: “City name”}} ) async def get_weather(city: str) - str: # 這里實現真正的天氣 API 調用 return f“The weather in {city} is sunny.” if __name__ __main__: server.run(transportstdio) # 或 “http”端口 8080運行這個 Server 后任何兼容 MCP 的 Client包括未來可能直接支持 MCP 的 Claude Desktop 等應用都能發現并調用get_weather這個技能。5. 生產環境實踐穩定性、成本與調試當你的 Agent 從 Demo 走向實際應用時以下幾個點必須重點關注。5.1 控制成本與穩定性Token 消耗Agent 的“思考”過程ReAct 格式會產生大量的 Token 消耗尤其是它反復輸出Thought、Action、Observation時。選擇性價比模型 對于工具調用邏輯簡單的任務可以考慮使用gpt-3.5-turbo而非gpt-4來驅動 Agent以大幅降低成本。復雜任務再切換回更強的模型。設置最大迭代次數AgentExecutor可以設置max_iterations和max_execution_time參數防止 Agent 陷入無限循環或處理過于復雜的任務。agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations10, early_stopping_methodgenerate, # 當達到限制時讓模型直接給出最終答案 handle_parsing_errorsTrue )優化工具描述 工具的description要精準、簡潔。模糊的描述會導致模型錯誤調用或需要更多輪次來理解。5.2 錯誤處理與魯棒性工具調用失敗 網絡超時、API 限流、文件不存在等都會導致工具調用失敗。確保你的工具函數有良好的異常捕獲并返回對 Agent 友好的錯誤信息例如“Failed to fetch data: Network timeout”而不是讓程序崩潰。解析錯誤handle_parsing_errorsTrue是基礎。你還可以自定義一個output_parser來更優雅地處理模型輸出格式不符合預期的情況。驗證輸入 在工具函數內部對輸入參數進行驗證。例如文件路徑工具要檢查路徑是否在允許的目錄內防止路徑遍歷攻擊。5.3 調試與監控充分利用verboseTrue 開發階段一定要打開這是理解 Agent 決策過程的最直接窗口。記錄日志 將AgentExecutor的運行日志包括所有的 Thoughts, Actions, Observations結構化的記錄到文件或日志系統便于事后分析。使用 LangSmith 如果你在開發嚴肅的應用強烈建議集成 LangSmith。它能可視化追蹤每一次 Agent 運行的完整鏈條精確看到每個步驟的輸入輸出、耗時和 Token 使用量是調試和優化的神器。5.4 與 LangGraph 的區別與選擇搜索熱詞中出現了langgraph。簡單來說LangChain Agent 更適合單一目標、線性或簡單分支的任務流程。你給一個指令它自動規劃執行。LangGraph 是一個基于圖狀態機的框架用于構建復雜、有狀態、多輪、循環或并行的工作流。例如一個客服機器人需要管理多輪對話狀態并根據不同狀態跳轉到不同的處理節點。如何選 如果你的任務主要是“調用工具完成一件事”用 Agent。如果你的任務涉及復雜的業務流程、狀態維護和節點路由比如一個涵蓋用戶查詢、數據庫檢索、生成報告、發送郵件、等待用戶反饋的完整自動化流程則應該用 LangGraph。兩者可以結合例如在 LangGraph 的一個節點里運行一個 Agent。6. 典型應用場景與避坑指南最后結合常見搜索詞看看這套技術能用在哪兒以及有哪些“坑”。6.1 應用場景智能數據分析助手 用戶用自然語言提問“上個月銷售額最高的產品是什么”Agent 自動調用“數據庫查詢”Skill 獲取數據再調用“圖表生成”Skill 畫出趨勢圖最后總結。自動化辦公 “將本周項目會議紀要的關鍵任務提取出來生成一個TODO列表發到我的郵箱。” Agent 調用“讀取文檔”Skill - “文本摘要/提取”Skill - “發送郵件”Skill。內部知識庫問答 結合 RAG檢索增強生成Agent 可以先調用“向量庫搜索”Skill 找到相關文檔片段再讓 LLM 生成精準答案。代碼生成與操作 “在src/utils/目錄下幫我創建一個名為formatDate.js的函數文件內容是按‘YYYY-MM-DD’格式化日期。” Agent 需要調用“文件系統操作”Skill。6.2 常見“坑”與解決方案坑1Agent 亂用或不用工具現象 模型要么不調用工具直接瞎猜要么調用錯誤的工具。排查檢查工具description是否清晰、無歧義。用人類能看懂的話描述工具的功能和適用場景。檢查給模型的系統提示詞prompt。hwchase17/react這個 prompt 是經過優化的。如果你自定義 prompt必須包含清晰的工具使用說明。嘗試換用更強的模型如從 gpt-3.5 切換到 gpt-4推理能力更強的模型在工具選擇上更準確。坑2任務陷入循環或超時現象 Agent 反復調用同一個工具或者一直在“思考”不出結果。排查首先設置max_iterations如5-10次。檢查工具返回的結果是否清晰。如果工具返回“未找到”或錯誤信息Agent 可能無法理解并陷入困惑。確保工具返回對后續決策有用的信息。在 prompt 中強調“如果你無法通過現有工具完成任務請直接告知用戶并停止嘗試”。坑3處理復雜、多步驟任務效果差現象 任務稍微復雜點Agent 的規劃就亂了。解決方案 這可能是單一 Agent 的局限。考慮使用Plan-and-Execute模式或LangGraph。即先用一個“規劃者”LLM 將大任務拆解成明確的子任務列表再由一個“執行者”Agent 或工作流依次執行每個子任務。這比讓一個 Agent 自己動態規劃要穩定得多。坑4MCP Server 連接或調用失敗現象 Client 無法連接到 Server或調用工具時超時。排查網絡與端口 確認 Server 進程是否在運行ps aux | grep mcp端口是否被占用或被防火墻攔截。協議兼容性 確認 Client 和 Server 使用的 MCP 協議版本是否兼容。查看 Server 日志。參數格式 確保調用工具時傳入的參數嚴格符合 Server 端定義的 JSON Schema。一個字段類型不匹配就可能導致調用失敗。最后的核心建議 不要一開始就追求接入復雜的 MCP 和一大堆 Skills。從最簡單的 LangChain Agent 兩個內置工具開始徹底理解Thought - Action - Observation這個循環。然后嘗試為自己寫一個自定義的 Python Tool比如一個查詢數據庫的函數。當你能熟練駕馭這個流程后再去研究如何將你的工具改造成 MCP Server或者如何連接別人提供的 MCP Server。這樣由簡入繁的路徑能幫你避開大部分概念和工程上的陷阱。