行器：深入理解ReAct范式與LangChain核心原理)
1. 項(xiàng)目概述從“玩具”到“利器”的Agent實(shí)戰(zhàn)最近在折騰LangChain發(fā)現(xiàn)很多教程都在講概念一上手實(shí)操就懵。特別是Agent這塊感覺像在用一個黑盒子出了問題都不知道從哪查起。于是我決定反向操作不直接用現(xiàn)成的AgentExecutor而是從零開始手寫一個最精簡、功能完整的Agent運(yùn)行器我把它叫做mini-cursor。這個項(xiàng)目的目標(biāo)不是造一個比LangChain更好的輪子而是通過“拆輪子”的過程徹底搞懂Agent內(nèi)部的工作流、狀態(tài)管理和錯誤處理機(jī)制。當(dāng)你自己實(shí)現(xiàn)一遍agent.run(“查詢今天的天氣”)背后發(fā)生的一切再回頭去看LangChain的源碼那種豁然開朗的感覺才是真正的“完全實(shí)戰(zhàn)”。這個mini-cursor麻雀雖小五臟俱全。它能理解你的自然語言指令自動規(guī)劃、調(diào)用工具比如搜索、計算并根據(jù)結(jié)果決定下一步是繼續(xù)執(zhí)行還是給出最終答案。整個過程完全透明你可以看到每一步的思考Thought、行動Action、觀察Observation。無論你是想深入理解Agent原理的開發(fā)者還是希望定制獨(dú)特Agent工作流的項(xiàng)目負(fù)責(zé)人這個實(shí)戰(zhàn)過程都能給你帶來遠(yuǎn)超閱讀文檔的收獲。接下來我就帶你一步步拆解如何用幾百行代碼構(gòu)建這個智能的“迷你光標(biāo)”。2. 核心設(shè)計構(gòu)建一個自驅(qū)動的智能循環(huán)2.1 理解Agent的核心運(yùn)行范式Agent的本質(zhì)是一個自主決策循環(huán)。它不像普通的函數(shù)調(diào)用輸入輸出一次完成。相反它處在一個持續(xù)感知、思考、行動、再感知的循環(huán)中。我們設(shè)計的mini-cursor必須完美封裝這個循環(huán)。其核心狀態(tài)機(jī)非常簡單卻極其重要接收輸入用戶提出一個問題或指令。思考與分析基于當(dāng)前對話歷史和問題決定下一步該做什么。是調(diào)用某個工具還是直接給出答案執(zhí)行行動如果決定調(diào)用工具則以正確的參數(shù)執(zhí)行該工具。觀察結(jié)果獲取工具執(zhí)行后的輸出。評估與循環(huán)判斷這個結(jié)果是否足以回答問題。如果可以則跳出循環(huán)返回最終答案如果不行則帶著新的觀察結(jié)果回到第2步繼續(xù)思考。這個循環(huán)的驅(qū)動力來自于一個大語言模型LLM。在每一步“思考”中我們都需要將當(dāng)前的狀態(tài)用戶問題、對話歷史、之前的工具執(zhí)行結(jié)果組織成合適的提示詞Prompt送給LLM讓它來做出決策。因此我們的mini-cursor架構(gòu)必須清晰地區(qū)分控制流循環(huán)邏輯、狀態(tài)判斷和推理層與LLM的交互。2.2 定義關(guān)鍵組件與接口為了讓代碼清晰且易于擴(kuò)展我們需要先定義幾個核心的類。這是模仿LangChain但極度簡化的設(shè)計Tool工具Agent可以調(diào)用的外部能力單元。每個工具必須有明確的名稱name、描述description和一個執(zhí)行函數(shù)_run。描述至關(guān)重要因?yàn)長LM就是靠描述來決定在什么情況下使用這個工具。class Tool: def __init__(self, name, description, func): self.name name self.description description self.func func def run(self, input_str): return self.func(input_str)例如一個計算器工具其描述可能是“當(dāng)需要對數(shù)學(xué)表達(dá)式進(jìn)行計算時使用此工具。輸入應(yīng)為一個可計算的數(shù)學(xué)表達(dá)式字符串。”AgentState代理狀態(tài)這是一個數(shù)據(jù)容器用于在循環(huán)中傳遞和保存所有必要信息。通常包括input: 用戶原始問題。chat_history: 對話歷史對于多輪對話很重要。intermediate_steps: 一個列表記錄已經(jīng)執(zhí)行過的(Action, Observation)對。這是Agent“記憶”的核心。agent_scratchpad: 一個臨時字符串用于將之前的步驟格式化成提示詞的一部分供LLM在下一步思考時參考。OutputParser輸出解析器LLM返回的是自然語言文本我們需要從中精確地解析出結(jié)構(gòu)化信息它到底是想執(zhí)行一個動作Action還是想直接回答FinalAnswer一個動作又包含工具名tool和輸入?yún)?shù)tool_input。解析器的魯棒性直接決定了Agent的穩(wěn)定性。2.3 設(shè)計決策為什么選擇ReAct范式在眾多Agent范式中如Plan-and-Execute, ReAct, AutoGPT我為mini-cursor選擇了ReActReasoning Acting。原因有三點(diǎn)都是實(shí)戰(zhàn)中總結(jié)出來的透明可調(diào)試ReAct要求LLM顯式地輸出“Thought:”、“Action:”、“Observation:”等關(guān)鍵詞。這就像給Agent的運(yùn)行過程加上了調(diào)試日志每一步的推理和決策都清晰可見。當(dāng)Agent出錯時你可以精準(zhǔn)定位是“思考”錯了還是“行動”的參數(shù)錯了或是“觀察”的結(jié)果沒理解對。實(shí)現(xiàn)簡單直觀其提示詞模板和解析邏輯相對固定非常適合教學(xué)和作為理解更復(fù)雜Agent的基礎(chǔ)。我們不需要引入額外的規(guī)劃模塊或復(fù)雜的任務(wù)分解邏輯。廣泛的適用性ReAct范式被證明在多種需要多步工具調(diào)用的任務(wù)上都非常有效如復(fù)雜問答、數(shù)據(jù)分析等是一個很好的通用起點(diǎn)。注意選擇ReAct也意味著我們將決策壓力完全交給了LLM的單步推理能力。對于極其復(fù)雜、需要長鏈條規(guī)劃的任務(wù)這可能不是最優(yōu)解。但在mini-cursor的目標(biāo)——理解和掌握基礎(chǔ)Agent循環(huán)——上它是完美的選擇。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 提示詞工程驅(qū)動智能的“燃料”提示詞是Agent的“大腦指令集”。一個糟糕的提示詞會讓最強(qiáng)大的LLM也表現(xiàn)得像個傻瓜。我們的提示詞需要精心組裝以下幾個部分系統(tǒng)指令定義Agent的角色、能力和行為規(guī)范。例如“你是一個樂于助人的助手可以調(diào)用工具來回答問題。如果你不知道答案就說不知道不要編造信息?！惫ぞ呙枋鲞@是最關(guān)鍵的部分。必須清晰、無歧義地列出所有可用工具的名稱和描述。LLM完全依靠這些描述來匹配用戶意圖和工具功能。描述應(yīng)該以“Useful for...”開頭并說明輸入格式。格式指令強(qiáng)制要求LLM以嚴(yán)格的格式輸出。對于ReAct就是Thought: 我需要分析用戶的問題并決定第一步做什么。 Action: 搜索工具 Action Input: “今天北京的天氣”或者當(dāng)答案明確時Thought: 我已經(jīng)通過工具獲得了足夠信息。 Final Answer: 今天北京晴氣溫20-25度。歷史與臨時便簽將agent_scratchpad即之前的步驟記錄和當(dāng)前的input插入到提示詞中為LLM提供完整的上下文。實(shí)操心得在組裝提示詞時我習(xí)慣使用f-string或Jinja2模板將變量部分清晰地標(biāo)記出來。一定要在開發(fā)初期多打印幾次生成的完整提示詞確保格式正確、信息完整沒有多余的換行或空格導(dǎo)致LLM解析混亂。3.2 輸出解析從自由文本到結(jié)構(gòu)化動作LLM的輸出是自由的但我們的程序需要結(jié)構(gòu)化的數(shù)據(jù)。輸出解析器是連接兩者的橋梁也是最容易出錯的環(huán)節(jié)之一。一個健壯的解析器需要處理以下情況正常情況輸出嚴(yán)格符合“Thought:...\nAction:...\nAction Input:...”或“Thought:...\nFinal Answer:...”的格式。格式微調(diào)LLM可能在關(guān)鍵詞后多加了個空格或者用了中文冒號或者“Action”寫成了“Action”。我們需要用正則表達(dá)式進(jìn)行靈活的匹配。提前結(jié)束LLM可能在沒有調(diào)用任何工具的情況下直接輸出了“Final Answer”。解析器需要能識別這種情況。解析失敗當(dāng)完全無法匹配任何模式時不能直接崩潰。最好的策略是將整個輸出視為一個“思考”并設(shè)計一個默認(rèn)的“回退動作”比如調(diào)用一個“請求澄清”的工具或者直接返回一個包含錯誤信息的最終答案提示用戶重新表述。我實(shí)現(xiàn)的解析器核心是一個基于正則表達(dá)式的函數(shù)import re def parse_llm_output(text: str) - dict: thought_pattern rThought:\s*(.*?)(?\nAction:|\nFinal Answer:|\nThought:|\Z) action_pattern rAction:\s*(.*?)(?\nAction Input:|\Z) action_input_pattern rAction Input:\s*(.*?)(?\nThought:|\nFinal Answer:|\Z) final_answer_pattern rFinal Answer:\s*(.*?)(?\nThought:|\nAction:|\Z) # 嘗試匹配各種模式... # 如果匹配到Action返回 {type: action, thought: ..., tool: ..., input: ...} # 如果匹配到Final Answer返回 {type: answer, thought: ..., answer: ...} # 如果都匹配不到返回 {type: error, raw: text}踩坑記錄最初我用了過于嚴(yán)格的正則比如r“Thought:(.*)\nAction:(.*)\nAction Input:(.*)”一旦LLM的輸出稍有偏差比如多一個空行整個解析就失敗了。后來改用非貪婪匹配(.*?)和更靈活的邊界條件(?...)容錯性大大增強(qiáng)。3.3 工具的設(shè)計與注冊工具是Agent能力的延伸。設(shè)計工具時有以下幾個要點(diǎn)單一職責(zé)一個工具只做一件事。不要設(shè)計一個“萬能搜索”工具而應(yīng)該拆分成“網(wǎng)頁搜索”、“學(xué)術(shù)搜索”、“本地文件搜索”等。描述精準(zhǔn)工具描述是給LLM看的“說明書”。要寫明用途、輸入格式和輸出示例。例如“當(dāng)需要計算數(shù)學(xué)表達(dá)式時使用此工具。輸入應(yīng)該是一個像‘23*4’或‘sin(30度)’的字符串。輸出是一個數(shù)字或計算結(jié)果?！卞e誤處理工具的執(zhí)行函數(shù)內(nèi)部必須有完善的try-except。如果工具執(zhí)行失敗如網(wǎng)絡(luò)超時、API錯誤應(yīng)該返回一個清晰的錯誤信息例如“調(diào)用天氣API失敗請檢查網(wǎng)絡(luò)或稍后重試”而不是拋出異常導(dǎo)致整個Agent崩潰。這個錯誤信息會成為Observation讓LLM知道行動失敗了它可能需要嘗試其他工具或告知用戶。注冊與管理我們需要一個ToolRegistry來集中管理所有工具方便Agent在運(yùn)行時根據(jù)名稱快速查找和調(diào)用。4. 實(shí)操過程一步步實(shí)現(xiàn)mini-cursor4.1 環(huán)境準(zhǔn)備與基礎(chǔ)架構(gòu)搭建首先確保你的Python環(huán)境建議3.8以上并安裝核心依賴。我們主要需要LLM的調(diào)用庫這里以O(shè)penAI API為例但你完全可以替換為任何兼容OpenAI接口的本地模型或其它云服務(wù)。pip install openai接下來創(chuàng)建項(xiàng)目結(jié)構(gòu)。我們主要需要以下幾個文件mini_cursor.py: 主邏輯文件包含Agent核心循環(huán)。tools.py: 定義所有工具。prompts.py: 定義提示詞模板。parsers.py: 定義輸出解析器。我們從定義最基礎(chǔ)的MiniCursorAgent類開始# mini_cursor.py class MiniCursorAgent: def __init__(self, llm, tools, max_iterations10): self.llm llm # 一個可調(diào)用的LLM對象需要實(shí)現(xiàn) generate(prompt) 方法 self.tools {tool.name: tool for tool in tools} # 工具字典 self.max_iterations max_iterations # 防止無限循環(huán) def run(self, user_input, chat_historyNone): 運(yùn)行Agent的主入口。 # 初始化狀態(tài) state { “input”: user_input, “chat_history”: chat_history or [], “intermediate_steps”: [], “agent_scratchpad”: “” } for i in range(self.max_iterations): # 1. 組裝當(dāng)前提示詞 prompt self._construct_prompt(state) # 2. 調(diào)用LLM llm_output self.llm.generate(prompt) # 3. 解析LLM輸出 parsed self._parse_output(llm_output) if parsed[“type”] “answer”: # 獲得最終答案結(jié)束循環(huán) return parsed[“answer”] elif parsed[“type”] “action”: # 執(zhí)行工具調(diào)用 tool_name parsed[“tool”] tool_input parsed[“tool_input”] if tool_name not in self.tools: observation f“錯誤工具 ‘{tool_name}’ 不存在。” else: observation self.tools[tool_name].run(tool_input) # 更新狀態(tài)記錄這一步 state[“intermediate_steps”].append(((tool_name, tool_input), observation)) # 更新臨時便簽供下一輪思考使用 state[“agent_scratchpad”] f“\nThought: {parsed[‘thought’]}\nAction: {tool_name}\nAction Input: {tool_input}\nObservation: {observation}” else: # 解析出錯處理錯誤 observation f“解析LLM輸出時出錯{parsed[‘raw’]}” state[“agent_scratchpad”] f“\nObservation: {observation}” # 可以選擇直接返回錯誤或者讓Agent繼續(xù)嘗試 if i 2: # 連續(xù)出錯多次后放棄 return “抱歉在處理您的請求時遇到了困難請稍后再試或重新表述您的問題?！?# 達(dá)到最大迭代次數(shù) return f“經(jīng)過{self.max_iterations}輪嘗試仍未完成請求。最后的狀態(tài)是{state[‘a(chǎn)gent_scratchpad’][-500:]}” # 返回最后一部分日志供調(diào)試4.2 實(shí)現(xiàn)LLM調(diào)用層與提示詞構(gòu)造為了讓代碼更靈活我們抽象一個簡單的LLM包裝器。這里以O(shè)penAI為例# llm_client.py import openai class OpenAIClient: def __init__(self, model“gpt-3.5-turbo”, api_keyNone): self.model model openai.api_key api_key or os.getenv(“OPENAI_API_KEY”) def generate(self, prompt): try: response openai.ChatCompletion.create( modelself.model, messages[{“role”: “user”, “content”: prompt}], temperature0, # 為了穩(wěn)定性溫度設(shè)為0 max_tokens500 ) return response.choices[0].message.content.strip() except Exception as e: return f“LLM調(diào)用失敗{str(e)}”接下來是提示詞模板這是Agent的“靈魂”。我們將它單獨(dú)放在prompts.py中# prompts.py REACT_PROMPT_TEMPLATE “”” 你是一個智能助手可以使用以下工具 {tools} 使用格式如下 問題用戶輸入的問題 思考你需要思考當(dāng)前情況決定使用哪個工具或直接回答 行動要調(diào)用的工具名稱必須是[{tool_names}]中的一個 行動輸入工具的輸入 觀察工具返回的結(jié)果 … (這個“思考/行動/行動輸入/觀察”的循環(huán)可以重復(fù)多次) 當(dāng)你有了最終答案時必須使用以下格式 思考我已經(jīng)獲得了足夠的信息。 最終答案你的最終回答 開始 之前的對話歷史 {history} 當(dāng)前問題{input} 這是你之前的操作和結(jié)果 {agent_scratchpad} 思考 “”” def construct_react_prompt(tools, state): tool_descriptions “\n”.join([f“- {t.name}: {t.description}” for t in tools]) tool_names “, “.join([t.name for t in tools]) history “\n”.join([f“Human: {h[0]}\nAssistant: {h[1]}” for h in state.get(“chat_history”, [])]) prompt REACT_PROMPT_TEMPLATE.format( toolstool_descriptions, tool_namestool_names, historyhistory, inputstate[“input”], agent_scratchpadstate.get(“agent_scratchpad”, “”) ) return prompt在MiniCursorAgent的_construct_prompt方法中調(diào)用這個函數(shù)即可。4.3 實(shí)現(xiàn)工具與解析器我們先實(shí)現(xiàn)兩個簡單的工具一個計算器一個模擬的搜索工具。# tools.py import math import re class CalculatorTool: name “計算器” description “用于計算數(shù)學(xué)表達(dá)式。輸入應(yīng)為一個包含數(shù)字和運(yùn)算符 -, *, /, **, sqrt等的字符串。例如‘(23)*4’ 或 ‘sqrt(16)’?！?staticmethod def _run(expression: str) - str: try: # 安全警告這里使用eval有安全風(fēng)險僅用于演示。生產(chǎn)環(huán)境應(yīng)用安全的評估庫如asteval。 # 替換一些常用數(shù)學(xué)函數(shù)和常量 expression expression.replace(“^”, “**”).replace(“sqrt”, “math.sqrt”).replace(“pi”, “math.pi”) # 限制可用的命名空間增加安全性 allowed_names {“math”: math} result eval(expression, {“__builtins__”: {}}, allowed_names) return str(result) except Exception as e: return f“計算錯誤{e}” class MockSearchTool: name “搜索” description “用于獲取關(guān)于通用知識、事實(shí)或當(dāng)前事件的信息。輸入應(yīng)為一個搜索查詢字符串?！?staticmethod def _run(query: str) - str: # 模擬一個簡單的搜索返回 mock_knowledge_base { “今天的天氣”: “根據(jù)模擬數(shù)據(jù)今天全國大部分地區(qū)晴間多云氣溫在15-25攝氏度之間。”, “Python的作者”: “Python編程語言由吉多·范羅蘇姆Guido van Rossum創(chuàng)造?！? “地球周長”: “地球的赤道周長約為40075公里?！?} for key, value in mock_knowledge_base.items(): if key in query: return value return “未找到相關(guān)信息。請嘗試更具體或不同的查詢詞。” # 工具工廠函數(shù) def get_tools(): return [ Tool(nameCalculatorTool.name, descriptionCalculatorTool.description, funcCalculatorTool._run), Tool(nameMockSearchTool.name, descriptionMockSearchTool.description, funcMockSearchTool._run), ]然后是解析器我們實(shí)現(xiàn)一個健壯的版本# parsers.py import re def parse_react_output(text: str) - dict: text text.strip() # 嘗試匹配最終答案 final_answer_match re.search(r“Final Answer[:]\s*(.*?)(?\n|$)”, text, re.IGNORECASE | re.DOTALL) if final_answer_match: # 嘗試提取最終答案前的思考 thought_before re.search(r“Thought[:]\s*(.*?)(?\nFinal Answer|\nAction:|$)”, text, re.IGNORECASE | re.DOTALL) thought thought_before.group(1).strip() if thought_before else “” return { “type”: “answer”, “thought”: thought, “answer”: final_answer_match.group(1).strip() } # 嘗試匹配行動 action_match re.search(r“Action[:]\s*(.*?)(?\nAction Input:|$)”, text, re.IGNORECASE | re.DOTALL) action_input_match re.search(r“Action Input[:]\s*(.*?)(?\nThought:|\nFinal Answer:|$)”, text, re.IGNORECASE | re.DOTALL) thought_match re.search(r“Thought[:]\s*(.*?)(?\nAction:|\nFinal Answer:|$)”, text, re.IGNORECASE | re.DOTALL) if action_match and action_input_match: thought thought_match.group(1).strip() if thought_match else “” return { “type”: “action”, “thought”: thought, “tool”: action_match.group(1).strip(), “tool_input”: action_input_match.group(1).strip() } # 如果都不匹配可能是LLM輸出了非標(biāo)準(zhǔn)格式或者直接給出了答案 # 這里做一個簡單的啟發(fā)式判斷如果文本較短且沒有明顯的行動指令視為最終答案 if len(text) 150 and not re.search(r“Action|工具|調(diào)用”, text): return {“type”: “answer”, “thought”: “”, “answer”: text} # 否則視為解析錯誤 return {“type”: “error”, “raw”: text}4.4 組裝與運(yùn)行測試現(xiàn)在把所有部分組裝起來進(jìn)行端到端測試。# main.py from llm_client import OpenAIClient from tools import get_tools from mini_cursor import MiniCursorAgent def main(): # 1. 初始化LLM客戶端請?zhí)鎿Q為你自己的API KEY llm_client OpenAIClient(model“gpt-3.5-turbo”, api_key“your-api-key-here”) # 2. 獲取工具列表 tools get_tools() # 3. 創(chuàng)建Agent agent MiniCursorAgent(llmllm_client.generate, toolstools, max_iterations5) # 4. 運(yùn)行測試 test_queries [ “計算一下 (15 7) * 3 等于多少”, “Python是誰發(fā)明的”, “先告訴我地球的周長再計算這個數(shù)字除以1000是多少。” ] for query in test_queries: print(f“\n 用戶問題{query} “) answer agent.run(query) print(f“助手回答{answer}”) print(“ 結(jié)束 \n”) if __name__ “__main__”: main()運(yùn)行這個腳本你應(yīng)該能看到類似以下的輸出清晰地展示了Agent的思考過程 用戶問題先告訴我地球的周長再計算這個數(shù)字除以1000是多少。 助手回答地球的赤道周長約為40075公里。40075除以1000等于40.075。 結(jié)束 在后臺Agent的agent_scratchpad會記錄下完整的軌跡Thought: 用戶需要兩個信息地球周長和該數(shù)字除以1000的結(jié)果。我需要先獲取地球周長。 Action: 搜索 Action Input: 地球周長 Observation: 地球的赤道周長約為40075公里。 Thought: 我已經(jīng)獲得了地球周長的數(shù)據(jù)現(xiàn)在需要計算40075除以1000。 Action: 計算器 Action Input: 40075 / 1000 Observation: 40.075 Thought: 我已經(jīng)獲得了足夠的信息。 Final Answer: 地球的赤道周長約為40075公里。40075除以1000等于40.075。5. 常見問題與排查技巧實(shí)錄在開發(fā)和測試mini-cursor的過程中我遇到了不少典型問題。這里把它們整理成排查清單希望能幫你快速定位問題。5.1 Agent陷入無限循環(huán)或重復(fù)調(diào)用同一工具癥狀A(yù)gent不停地調(diào)用同一個工具或者來回執(zhí)行幾個動作始終無法輸出最終答案。排查步驟檢查工具描述這是最常見的原因。工具描述是否清晰、無歧義LLM是否誤解了工具的用途嘗試修改描述使其更精確。檢查觀察結(jié)果工具返回的Observation是否清晰、完整如果工具返回了錯誤信息或模糊的結(jié)果LLM可能無法理解從而反復(fù)嘗試。確保工具的錯誤信息對人類和LLM都友好。查看思考鏈打印出每一輪的agent_scratchpad。觀察LLM的“Thought”部分看它的推理邏輯是否合理。有時LLM的思考會陷入死胡同。調(diào)整提示詞在系統(tǒng)指令中增加約束例如“如果同一個工具連續(xù)調(diào)用三次仍未獲得有效信息請嘗試其他方法或承認(rèn)無法解決?！痹O(shè)置迭代上限就像我們代碼中的max_iterations這是一個必要的安全閥。5.2 LLM輸出格式不符合預(yù)期解析失敗癥狀解析器頻繁返回error類型或者解析出的工具名、輸入?yún)?shù)是錯的。排查步驟打印原始輸出第一時間將LLM返回的原始文本打印出來。99%的問題可以通過肉眼發(fā)現(xiàn)比如多了奇怪的換行、使用了中文標(biāo)點(diǎn)、關(guān)鍵詞拼寫錯誤等。強(qiáng)化提示詞格式指令在提示詞中用更醒目的方式如括起來強(qiáng)調(diào)輸出格式并給出多個清晰的正反面示例。優(yōu)化解析器正則使用更寬松、容錯性更強(qiáng)的正則表達(dá)式如使用re.IGNORECASE忽略大小寫用.*?非貪婪匹配處理好可能存在的空格和換行變體。后處理LLM輸出在解析前可以對LLM輸出進(jìn)行簡單的清洗比如去除首尾空行將中文冒號統(tǒng)一替換為英文冒號等。5.3 工具調(diào)用結(jié)果不佳導(dǎo)致任務(wù)失敗癥狀A(yù)gent調(diào)用了正確的工具但任務(wù)還是失敗了因?yàn)楣ぞ叻祷氐慕Y(jié)果質(zhì)量不高。排查與優(yōu)化工具輸入預(yù)處理LLM給出的tool_input可能包含多余的自然語言描述。例如對于計算器它可能輸出“請計算一下sin(30)的值”。你的工具_(dá)run函數(shù)開頭應(yīng)該有一層預(yù)處理嘗試從字符串中提取出純粹的數(shù)學(xué)表達(dá)式“sin(30)”。工具結(jié)果后處理工具返回的結(jié)果可能過于冗長或包含無關(guān)信息。設(shè)計一個精簡或格式化的步驟提取出核心信息作為Observation。例如一個網(wǎng)頁搜索工具返回整個HTML你需要從中提取出文本摘要。引入驗(yàn)證工具對于一些關(guān)鍵操作可以設(shè)計一個“驗(yàn)證”工具。例如在調(diào)用“發(fā)送郵件”工具前先調(diào)用“確認(rèn)郵件內(nèi)容”工具讓LLM二次確認(rèn)減少錯誤。5.4 性能與成本優(yōu)化上下文長度agent_scratchpad會隨著循環(huán)輪次增長可能很快觸及LLM的上下文長度限制。需要設(shè)計截斷策略例如只保留最近3-4輪的交互或者將更早的歷史總結(jié)成一段摘要。LLM調(diào)用延遲每一輪思考都是一次LLM API調(diào)用延遲累加可能很可觀。對于簡單任務(wù)可以嘗試在提示詞中鼓勵LLM“一步到位”減少不必要的工具調(diào)用。Token消耗長上下文意味著高Token消耗。除了截斷歷史還可以考慮使用更便宜的模型進(jìn)行部分輪次的思考例如用gpt-3.5-turbo代替gpt-4或者對工具描述進(jìn)行壓縮。一個高級技巧讓Agent學(xué)會“反思”。你可以在agent_scratchpad的組裝中不僅記錄步驟還在每輪之后讓LLM自己對當(dāng)前進(jìn)展做一個小結(jié)。這有時能幫助它在后續(xù)步驟中做出更連貫的決策。實(shí)現(xiàn)起來就是在更新scratchpad時不僅拼接原始記錄還可以問LLM一句“基于以上步驟我們目前取得了什么進(jìn)展下一步最應(yīng)該關(guān)注什么”并將這個小結(jié)也放入上下文。這稍微增加了復(fù)雜度但對于復(fù)雜任務(wù)非常有效。通過這個從零構(gòu)建mini-cursor的完整過程我們不僅實(shí)現(xiàn)了一個可運(yùn)行的Agent更重要的是我們親手觸摸了Agent每一個組件的脈搏理解了它們?nèi)绾螀f(xié)同工作。下次當(dāng)你使用LangChain的initialize_agent時你看到的將不再是一個魔法函數(shù)而是一個由清晰的數(shù)據(jù)流和控制邏輯構(gòu)成的、你可以預(yù)測和調(diào)試的系統(tǒng)。這才是“完全實(shí)戰(zhàn)”帶來的真正力量——從知其然到知其所以然最終到創(chuàng)造屬于你自己的“然”。 從零手寫Agent運(yùn)行器：深入理解ReAct范式與LangChain核心原理
1. 項(xiàng)目概述從“玩具”到“利器”的Agent實(shí)戰(zhàn)最近在折騰LangChain發(fā)現(xiàn)很多教程都在講概念一上手實(shí)操就懵。特別是Agent這塊感覺像在用一個黑盒子出了問題都不知道從哪查起。于是我決定反向操作不直接用現(xiàn)成的AgentExecutor而是從零開始手寫一個最精簡、功能完整的Agent運(yùn)行器我把它叫做mini-cursor。這個項(xiàng)目的目標(biāo)不是造一個比LangChain更好的輪子而是通過“拆輪子”的過程徹底搞懂Agent內(nèi)部的工作流、狀態(tài)管理和錯誤處理機(jī)制。當(dāng)你自己實(shí)現(xiàn)一遍agent.run(“查詢今天的天氣”)背后發(fā)生的一切再回頭去看LangChain的源碼那種豁然開朗的感覺才是真正的“完全實(shí)戰(zhàn)”。這個mini-cursor麻雀雖小五臟俱全。它能理解你的自然語言指令自動規(guī)劃、調(diào)用工具比如搜索、計算并根據(jù)結(jié)果決定下一步是繼續(xù)執(zhí)行還是給出最終答案。整個過程完全透明你可以看到每一步的思考Thought、行動Action、觀察Observation。無論你是想深入理解Agent原理的開發(fā)者還是希望定制獨(dú)特Agent工作流的項(xiàng)目負(fù)責(zé)人這個實(shí)戰(zhàn)過程都能給你帶來遠(yuǎn)超閱讀文檔的收獲。接下來我就帶你一步步拆解如何用幾百行代碼構(gòu)建這個智能的“迷你光標(biāo)”。2. 核心設(shè)計構(gòu)建一個自驅(qū)動的智能循環(huán)2.1 理解Agent的核心運(yùn)行范式Agent的本質(zhì)是一個自主決策循環(huán)。它不像普通的函數(shù)調(diào)用輸入輸出一次完成。相反它處在一個持續(xù)感知、思考、行動、再感知的循環(huán)中。我們設(shè)計的mini-cursor必須完美封裝這個循環(huán)。其核心狀態(tài)機(jī)非常簡單卻極其重要接收輸入用戶提出一個問題或指令。思考與分析基于當(dāng)前對話歷史和問題決定下一步該做什么。是調(diào)用某個工具還是直接給出答案執(zhí)行行動如果決定調(diào)用工具則以正確的參數(shù)執(zhí)行該工具。觀察結(jié)果獲取工具執(zhí)行后的輸出。評估與循環(huán)判斷這個結(jié)果是否足以回答問題。如果可以則跳出循環(huán)返回最終答案如果不行則帶著新的觀察結(jié)果回到第2步繼續(xù)思考。這個循環(huán)的驅(qū)動力來自于一個大語言模型LLM。在每一步“思考”中我們都需要將當(dāng)前的狀態(tài)用戶問題、對話歷史、之前的工具執(zhí)行結(jié)果組織成合適的提示詞Prompt送給LLM讓它來做出決策。因此我們的mini-cursor架構(gòu)必須清晰地區(qū)分控制流循環(huán)邏輯、狀態(tài)判斷和推理層與LLM的交互。2.2 定義關(guān)鍵組件與接口為了讓代碼清晰且易于擴(kuò)展我們需要先定義幾個核心的類。這是模仿LangChain但極度簡化的設(shè)計Tool工具Agent可以調(diào)用的外部能力單元。每個工具必須有明確的名稱name、描述description和一個執(zhí)行函數(shù)_run。描述至關(guān)重要因?yàn)長LM就是靠描述來決定在什么情況下使用這個工具。class Tool: def __init__(self, name, description, func): self.name name self.description description self.func func def run(self, input_str): return self.func(input_str)例如一個計算器工具其描述可能是“當(dāng)需要對數(shù)學(xué)表達(dá)式進(jìn)行計算時使用此工具。輸入應(yīng)為一個可計算的數(shù)學(xué)表達(dá)式字符串。”AgentState代理狀態(tài)這是一個數(shù)據(jù)容器用于在循環(huán)中傳遞和保存所有必要信息。通常包括input: 用戶原始問題。chat_history: 對話歷史對于多輪對話很重要。intermediate_steps: 一個列表記錄已經(jīng)執(zhí)行過的(Action, Observation)對。這是Agent“記憶”的核心。agent_scratchpad: 一個臨時字符串用于將之前的步驟格式化成提示詞的一部分供LLM在下一步思考時參考。OutputParser輸出解析器LLM返回的是自然語言文本我們需要從中精確地解析出結(jié)構(gòu)化信息它到底是想執(zhí)行一個動作Action還是想直接回答FinalAnswer一個動作又包含工具名tool和輸入?yún)?shù)tool_input。解析器的魯棒性直接決定了Agent的穩(wěn)定性。2.3 設(shè)計決策為什么選擇ReAct范式在眾多Agent范式中如Plan-and-Execute, ReAct, AutoGPT我為mini-cursor選擇了ReActReasoning Acting。原因有三點(diǎn)都是實(shí)戰(zhàn)中總結(jié)出來的透明可調(diào)試ReAct要求LLM顯式地輸出“Thought:”、“Action:”、“Observation:”等關(guān)鍵詞。這就像給Agent的運(yùn)行過程加上了調(diào)試日志每一步的推理和決策都清晰可見。當(dāng)Agent出錯時你可以精準(zhǔn)定位是“思考”錯了還是“行動”的參數(shù)錯了或是“觀察”的結(jié)果沒理解對。實(shí)現(xiàn)簡單直觀其提示詞模板和解析邏輯相對固定非常適合教學(xué)和作為理解更復(fù)雜Agent的基礎(chǔ)。我們不需要引入額外的規(guī)劃模塊或復(fù)雜的任務(wù)分解邏輯。廣泛的適用性ReAct范式被證明在多種需要多步工具調(diào)用的任務(wù)上都非常有效如復(fù)雜問答、數(shù)據(jù)分析等是一個很好的通用起點(diǎn)。注意選擇ReAct也意味著我們將決策壓力完全交給了LLM的單步推理能力。對于極其復(fù)雜、需要長鏈條規(guī)劃的任務(wù)這可能不是最優(yōu)解。但在mini-cursor的目標(biāo)——理解和掌握基礎(chǔ)Agent循環(huán)——上它是完美的選擇。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 提示詞工程驅(qū)動智能的“燃料”提示詞是Agent的“大腦指令集”。一個糟糕的提示詞會讓最強(qiáng)大的LLM也表現(xiàn)得像個傻瓜。我們的提示詞需要精心組裝以下幾個部分系統(tǒng)指令定義Agent的角色、能力和行為規(guī)范。例如“你是一個樂于助人的助手可以調(diào)用工具來回答問題。如果你不知道答案就說不知道不要編造信息?！惫ぞ呙枋鲞@是最關(guān)鍵的部分。必須清晰、無歧義地列出所有可用工具的名稱和描述。LLM完全依靠這些描述來匹配用戶意圖和工具功能。描述應(yīng)該以“Useful for...”開頭并說明輸入格式。格式指令強(qiáng)制要求LLM以嚴(yán)格的格式輸出。對于ReAct就是Thought: 我需要分析用戶的問題并決定第一步做什么。 Action: 搜索工具 Action Input: “今天北京的天氣”或者當(dāng)答案明確時Thought: 我已經(jīng)通過工具獲得了足夠信息。 Final Answer: 今天北京晴氣溫20-25度。歷史與臨時便簽將agent_scratchpad即之前的步驟記錄和當(dāng)前的input插入到提示詞中為LLM提供完整的上下文。實(shí)操心得在組裝提示詞時我習(xí)慣使用f-string或Jinja2模板將變量部分清晰地標(biāo)記出來。一定要在開發(fā)初期多打印幾次生成的完整提示詞確保格式正確、信息完整沒有多余的換行或空格導(dǎo)致LLM解析混亂。3.2 輸出解析從自由文本到結(jié)構(gòu)化動作LLM的輸出是自由的但我們的程序需要結(jié)構(gòu)化的數(shù)據(jù)。輸出解析器是連接兩者的橋梁也是最容易出錯的環(huán)節(jié)之一。一個健壯的解析器需要處理以下情況正常情況輸出嚴(yán)格符合“Thought:...\nAction:...\nAction Input:...”或“Thought:...\nFinal Answer:...”的格式。格式微調(diào)LLM可能在關(guān)鍵詞后多加了個空格或者用了中文冒號或者“Action”寫成了“Action”。我們需要用正則表達(dá)式進(jìn)行靈活的匹配。提前結(jié)束LLM可能在沒有調(diào)用任何工具的情況下直接輸出了“Final Answer”。解析器需要能識別這種情況。解析失敗當(dāng)完全無法匹配任何模式時不能直接崩潰。最好的策略是將整個輸出視為一個“思考”并設(shè)計一個默認(rèn)的“回退動作”比如調(diào)用一個“請求澄清”的工具或者直接返回一個包含錯誤信息的最終答案提示用戶重新表述。我實(shí)現(xiàn)的解析器核心是一個基于正則表達(dá)式的函數(shù)import re def parse_llm_output(text: str) - dict: thought_pattern rThought:\s*(.*?)(?\nAction:|\nFinal Answer:|\nThought:|\Z) action_pattern rAction:\s*(.*?)(?\nAction Input:|\Z) action_input_pattern rAction Input:\s*(.*?)(?\nThought:|\nFinal Answer:|\Z) final_answer_pattern rFinal Answer:\s*(.*?)(?\nThought:|\nAction:|\Z) # 嘗試匹配各種模式... # 如果匹配到Action返回 {type: action, thought: ..., tool: ..., input: ...} # 如果匹配到Final Answer返回 {type: answer, thought: ..., answer: ...} # 如果都匹配不到返回 {type: error, raw: text}踩坑記錄最初我用了過于嚴(yán)格的正則比如r“Thought:(.*)\nAction:(.*)\nAction Input:(.*)”一旦LLM的輸出稍有偏差比如多一個空行整個解析就失敗了。后來改用非貪婪匹配(.*?)和更靈活的邊界條件(?...)容錯性大大增強(qiáng)。3.3 工具的設(shè)計與注冊工具是Agent能力的延伸。設(shè)計工具時有以下幾個要點(diǎn)單一職責(zé)一個工具只做一件事。不要設(shè)計一個“萬能搜索”工具而應(yīng)該拆分成“網(wǎng)頁搜索”、“學(xué)術(shù)搜索”、“本地文件搜索”等。描述精準(zhǔn)工具描述是給LLM看的“說明書”。要寫明用途、輸入格式和輸出示例。例如“當(dāng)需要計算數(shù)學(xué)表達(dá)式時使用此工具。輸入應(yīng)該是一個像‘23*4’或‘sin(30度)’的字符串。輸出是一個數(shù)字或計算結(jié)果?！卞e誤處理工具的執(zhí)行函數(shù)內(nèi)部必須有完善的try-except。如果工具執(zhí)行失敗如網(wǎng)絡(luò)超時、API錯誤應(yīng)該返回一個清晰的錯誤信息例如“調(diào)用天氣API失敗請檢查網(wǎng)絡(luò)或稍后重試”而不是拋出異常導(dǎo)致整個Agent崩潰。這個錯誤信息會成為Observation讓LLM知道行動失敗了它可能需要嘗試其他工具或告知用戶。注冊與管理我們需要一個ToolRegistry來集中管理所有工具方便Agent在運(yùn)行時根據(jù)名稱快速查找和調(diào)用。4. 實(shí)操過程一步步實(shí)現(xiàn)mini-cursor4.1 環(huán)境準(zhǔn)備與基礎(chǔ)架構(gòu)搭建首先確保你的Python環(huán)境建議3.8以上并安裝核心依賴。我們主要需要LLM的調(diào)用庫這里以O(shè)penAI API為例但你完全可以替換為任何兼容OpenAI接口的本地模型或其它云服務(wù)。pip install openai接下來創(chuàng)建項(xiàng)目結(jié)構(gòu)。我們主要需要以下幾個文件mini_cursor.py: 主邏輯文件包含Agent核心循環(huán)。tools.py: 定義所有工具。prompts.py: 定義提示詞模板。parsers.py: 定義輸出解析器。我們從定義最基礎(chǔ)的MiniCursorAgent類開始# mini_cursor.py class MiniCursorAgent: def __init__(self, llm, tools, max_iterations10): self.llm llm # 一個可調(diào)用的LLM對象需要實(shí)現(xiàn) generate(prompt) 方法 self.tools {tool.name: tool for tool in tools} # 工具字典 self.max_iterations max_iterations # 防止無限循環(huán) def run(self, user_input, chat_historyNone): 運(yùn)行Agent的主入口。 # 初始化狀態(tài) state { “input”: user_input, “chat_history”: chat_history or [], “intermediate_steps”: [], “agent_scratchpad”: “” } for i in range(self.max_iterations): # 1. 組裝當(dāng)前提示詞 prompt self._construct_prompt(state) # 2. 調(diào)用LLM llm_output self.llm.generate(prompt) # 3. 解析LLM輸出 parsed self._parse_output(llm_output) if parsed[“type”] “answer”: # 獲得最終答案結(jié)束循環(huán) return parsed[“answer”] elif parsed[“type”] “action”: # 執(zhí)行工具調(diào)用 tool_name parsed[“tool”] tool_input parsed[“tool_input”] if tool_name not in self.tools: observation f“錯誤工具 ‘{tool_name}’ 不存在。” else: observation self.tools[tool_name].run(tool_input) # 更新狀態(tài)記錄這一步 state[“intermediate_steps”].append(((tool_name, tool_input), observation)) # 更新臨時便簽供下一輪思考使用 state[“agent_scratchpad”] f“\nThought: {parsed[‘thought’]}\nAction: {tool_name}\nAction Input: {tool_input}\nObservation: {observation}” else: # 解析出錯處理錯誤 observation f“解析LLM輸出時出錯{parsed[‘raw’]}” state[“agent_scratchpad”] f“\nObservation: {observation}” # 可以選擇直接返回錯誤或者讓Agent繼續(xù)嘗試 if i 2: # 連續(xù)出錯多次后放棄 return “抱歉在處理您的請求時遇到了困難請稍后再試或重新表述您的問題?！?# 達(dá)到最大迭代次數(shù) return f“經(jīng)過{self.max_iterations}輪嘗試仍未完成請求。最后的狀態(tài)是{state[‘a(chǎn)gent_scratchpad’][-500:]}” # 返回最后一部分日志供調(diào)試4.2 實(shí)現(xiàn)LLM調(diào)用層與提示詞構(gòu)造為了讓代碼更靈活我們抽象一個簡單的LLM包裝器。這里以O(shè)penAI為例# llm_client.py import openai class OpenAIClient: def __init__(self, model“gpt-3.5-turbo”, api_keyNone): self.model model openai.api_key api_key or os.getenv(“OPENAI_API_KEY”) def generate(self, prompt): try: response openai.ChatCompletion.create( modelself.model, messages[{“role”: “user”, “content”: prompt}], temperature0, # 為了穩(wěn)定性溫度設(shè)為0 max_tokens500 ) return response.choices[0].message.content.strip() except Exception as e: return f“LLM調(diào)用失敗{str(e)}”接下來是提示詞模板這是Agent的“靈魂”。我們將它單獨(dú)放在prompts.py中# prompts.py REACT_PROMPT_TEMPLATE “”” 你是一個智能助手可以使用以下工具 {tools} 使用格式如下 問題用戶輸入的問題 思考你需要思考當(dāng)前情況決定使用哪個工具或直接回答 行動要調(diào)用的工具名稱必須是[{tool_names}]中的一個 行動輸入工具的輸入 觀察工具返回的結(jié)果 … (這個“思考/行動/行動輸入/觀察”的循環(huán)可以重復(fù)多次) 當(dāng)你有了最終答案時必須使用以下格式 思考我已經(jīng)獲得了足夠的信息。 最終答案你的最終回答 開始 之前的對話歷史 {history} 當(dāng)前問題{input} 這是你之前的操作和結(jié)果 {agent_scratchpad} 思考 “”” def construct_react_prompt(tools, state): tool_descriptions “\n”.join([f“- {t.name}: {t.description}” for t in tools]) tool_names “, “.join([t.name for t in tools]) history “\n”.join([f“Human: {h[0]}\nAssistant: {h[1]}” for h in state.get(“chat_history”, [])]) prompt REACT_PROMPT_TEMPLATE.format( toolstool_descriptions, tool_namestool_names, historyhistory, inputstate[“input”], agent_scratchpadstate.get(“agent_scratchpad”, “”) ) return prompt在MiniCursorAgent的_construct_prompt方法中調(diào)用這個函數(shù)即可。4.3 實(shí)現(xiàn)工具與解析器我們先實(shí)現(xiàn)兩個簡單的工具一個計算器一個模擬的搜索工具。# tools.py import math import re class CalculatorTool: name “計算器” description “用于計算數(shù)學(xué)表達(dá)式。輸入應(yīng)為一個包含數(shù)字和運(yùn)算符 -, *, /, **, sqrt等的字符串。例如‘(23)*4’ 或 ‘sqrt(16)’?！?staticmethod def _run(expression: str) - str: try: # 安全警告這里使用eval有安全風(fēng)險僅用于演示。生產(chǎn)環(huán)境應(yīng)用安全的評估庫如asteval。 # 替換一些常用數(shù)學(xué)函數(shù)和常量 expression expression.replace(“^”, “**”).replace(“sqrt”, “math.sqrt”).replace(“pi”, “math.pi”) # 限制可用的命名空間增加安全性 allowed_names {“math”: math} result eval(expression, {“__builtins__”: {}}, allowed_names) return str(result) except Exception as e: return f“計算錯誤{e}” class MockSearchTool: name “搜索” description “用于獲取關(guān)于通用知識、事實(shí)或當(dāng)前事件的信息。輸入應(yīng)為一個搜索查詢字符串?！?staticmethod def _run(query: str) - str: # 模擬一個簡單的搜索返回 mock_knowledge_base { “今天的天氣”: “根據(jù)模擬數(shù)據(jù)今天全國大部分地區(qū)晴間多云氣溫在15-25攝氏度之間。”, “Python的作者”: “Python編程語言由吉多·范羅蘇姆Guido van Rossum創(chuàng)造?！? “地球周長”: “地球的赤道周長約為40075公里?！?} for key, value in mock_knowledge_base.items(): if key in query: return value return “未找到相關(guān)信息。請嘗試更具體或不同的查詢詞。” # 工具工廠函數(shù) def get_tools(): return [ Tool(nameCalculatorTool.name, descriptionCalculatorTool.description, funcCalculatorTool._run), Tool(nameMockSearchTool.name, descriptionMockSearchTool.description, funcMockSearchTool._run), ]然后是解析器我們實(shí)現(xiàn)一個健壯的版本# parsers.py import re def parse_react_output(text: str) - dict: text text.strip() # 嘗試匹配最終答案 final_answer_match re.search(r“Final Answer[:]\s*(.*?)(?\n|$)”, text, re.IGNORECASE | re.DOTALL) if final_answer_match: # 嘗試提取最終答案前的思考 thought_before re.search(r“Thought[:]\s*(.*?)(?\nFinal Answer|\nAction:|$)”, text, re.IGNORECASE | re.DOTALL) thought thought_before.group(1).strip() if thought_before else “” return { “type”: “answer”, “thought”: thought, “answer”: final_answer_match.group(1).strip() } # 嘗試匹配行動 action_match re.search(r“Action[:]\s*(.*?)(?\nAction Input:|$)”, text, re.IGNORECASE | re.DOTALL) action_input_match re.search(r“Action Input[:]\s*(.*?)(?\nThought:|\nFinal Answer:|$)”, text, re.IGNORECASE | re.DOTALL) thought_match re.search(r“Thought[:]\s*(.*?)(?\nAction:|\nFinal Answer:|$)”, text, re.IGNORECASE | re.DOTALL) if action_match and action_input_match: thought thought_match.group(1).strip() if thought_match else “” return { “type”: “action”, “thought”: thought, “tool”: action_match.group(1).strip(), “tool_input”: action_input_match.group(1).strip() } # 如果都不匹配可能是LLM輸出了非標(biāo)準(zhǔn)格式或者直接給出了答案 # 這里做一個簡單的啟發(fā)式判斷如果文本較短且沒有明顯的行動指令視為最終答案 if len(text) 150 and not re.search(r“Action|工具|調(diào)用”, text): return {“type”: “answer”, “thought”: “”, “answer”: text} # 否則視為解析錯誤 return {“type”: “error”, “raw”: text}4.4 組裝與運(yùn)行測試現(xiàn)在把所有部分組裝起來進(jìn)行端到端測試。# main.py from llm_client import OpenAIClient from tools import get_tools from mini_cursor import MiniCursorAgent def main(): # 1. 初始化LLM客戶端請?zhí)鎿Q為你自己的API KEY llm_client OpenAIClient(model“gpt-3.5-turbo”, api_key“your-api-key-here”) # 2. 獲取工具列表 tools get_tools() # 3. 創(chuàng)建Agent agent MiniCursorAgent(llmllm_client.generate, toolstools, max_iterations5) # 4. 運(yùn)行測試 test_queries [ “計算一下 (15 7) * 3 等于多少”, “Python是誰發(fā)明的”, “先告訴我地球的周長再計算這個數(shù)字除以1000是多少。” ] for query in test_queries: print(f“\n 用戶問題{query} “) answer agent.run(query) print(f“助手回答{answer}”) print(“ 結(jié)束 \n”) if __name__ “__main__”: main()運(yùn)行這個腳本你應(yīng)該能看到類似以下的輸出清晰地展示了Agent的思考過程 用戶問題先告訴我地球的周長再計算這個數(shù)字除以1000是多少。 助手回答地球的赤道周長約為40075公里。40075除以1000等于40.075。 結(jié)束 在后臺Agent的agent_scratchpad會記錄下完整的軌跡Thought: 用戶需要兩個信息地球周長和該數(shù)字除以1000的結(jié)果。我需要先獲取地球周長。 Action: 搜索 Action Input: 地球周長 Observation: 地球的赤道周長約為40075公里。 Thought: 我已經(jīng)獲得了地球周長的數(shù)據(jù)現(xiàn)在需要計算40075除以1000。 Action: 計算器 Action Input: 40075 / 1000 Observation: 40.075 Thought: 我已經(jīng)獲得了足夠的信息。 Final Answer: 地球的赤道周長約為40075公里。40075除以1000等于40.075。5. 常見問題與排查技巧實(shí)錄在開發(fā)和測試mini-cursor的過程中我遇到了不少典型問題。這里把它們整理成排查清單希望能幫你快速定位問題。5.1 Agent陷入無限循環(huán)或重復(fù)調(diào)用同一工具癥狀A(yù)gent不停地調(diào)用同一個工具或者來回執(zhí)行幾個動作始終無法輸出最終答案。排查步驟檢查工具描述這是最常見的原因。工具描述是否清晰、無歧義LLM是否誤解了工具的用途嘗試修改描述使其更精確。檢查觀察結(jié)果工具返回的Observation是否清晰、完整如果工具返回了錯誤信息或模糊的結(jié)果LLM可能無法理解從而反復(fù)嘗試。確保工具的錯誤信息對人類和LLM都友好。查看思考鏈打印出每一輪的agent_scratchpad。觀察LLM的“Thought”部分看它的推理邏輯是否合理。有時LLM的思考會陷入死胡同。調(diào)整提示詞在系統(tǒng)指令中增加約束例如“如果同一個工具連續(xù)調(diào)用三次仍未獲得有效信息請嘗試其他方法或承認(rèn)無法解決?！痹O(shè)置迭代上限就像我們代碼中的max_iterations這是一個必要的安全閥。5.2 LLM輸出格式不符合預(yù)期解析失敗癥狀解析器頻繁返回error類型或者解析出的工具名、輸入?yún)?shù)是錯的。排查步驟打印原始輸出第一時間將LLM返回的原始文本打印出來。99%的問題可以通過肉眼發(fā)現(xiàn)比如多了奇怪的換行、使用了中文標(biāo)點(diǎn)、關(guān)鍵詞拼寫錯誤等。強(qiáng)化提示詞格式指令在提示詞中用更醒目的方式如括起來強(qiáng)調(diào)輸出格式并給出多個清晰的正反面示例。優(yōu)化解析器正則使用更寬松、容錯性更強(qiáng)的正則表達(dá)式如使用re.IGNORECASE忽略大小寫用.*?非貪婪匹配處理好可能存在的空格和換行變體。后處理LLM輸出在解析前可以對LLM輸出進(jìn)行簡單的清洗比如去除首尾空行將中文冒號統(tǒng)一替換為英文冒號等。5.3 工具調(diào)用結(jié)果不佳導(dǎo)致任務(wù)失敗癥狀A(yù)gent調(diào)用了正確的工具但任務(wù)還是失敗了因?yàn)楣ぞ叻祷氐慕Y(jié)果質(zhì)量不高。排查與優(yōu)化工具輸入預(yù)處理LLM給出的tool_input可能包含多余的自然語言描述。例如對于計算器它可能輸出“請計算一下sin(30)的值”。你的工具_(dá)run函數(shù)開頭應(yīng)該有一層預(yù)處理嘗試從字符串中提取出純粹的數(shù)學(xué)表達(dá)式“sin(30)”。工具結(jié)果后處理工具返回的結(jié)果可能過于冗長或包含無關(guān)信息。設(shè)計一個精簡或格式化的步驟提取出核心信息作為Observation。例如一個網(wǎng)頁搜索工具返回整個HTML你需要從中提取出文本摘要。引入驗(yàn)證工具對于一些關(guān)鍵操作可以設(shè)計一個“驗(yàn)證”工具。例如在調(diào)用“發(fā)送郵件”工具前先調(diào)用“確認(rèn)郵件內(nèi)容”工具讓LLM二次確認(rèn)減少錯誤。5.4 性能與成本優(yōu)化上下文長度agent_scratchpad會隨著循環(huán)輪次增長可能很快觸及LLM的上下文長度限制。需要設(shè)計截斷策略例如只保留最近3-4輪的交互或者將更早的歷史總結(jié)成一段摘要。LLM調(diào)用延遲每一輪思考都是一次LLM API調(diào)用延遲累加可能很可觀。對于簡單任務(wù)可以嘗試在提示詞中鼓勵LLM“一步到位”減少不必要的工具調(diào)用。Token消耗長上下文意味著高Token消耗。除了截斷歷史還可以考慮使用更便宜的模型進(jìn)行部分輪次的思考例如用gpt-3.5-turbo代替gpt-4或者對工具描述進(jìn)行壓縮。一個高級技巧讓Agent學(xué)會“反思”。你可以在agent_scratchpad的組裝中不僅記錄步驟還在每輪之后讓LLM自己對當(dāng)前進(jìn)展做一個小結(jié)。這有時能幫助它在后續(xù)步驟中做出更連貫的決策。實(shí)現(xiàn)起來就是在更新scratchpad時不僅拼接原始記錄還可以問LLM一句“基于以上步驟我們目前取得了什么進(jìn)展下一步最應(yīng)該關(guān)注什么”并將這個小結(jié)也放入上下文。這稍微增加了復(fù)雜度但對于復(fù)雜任務(wù)非常有效。通過這個從零構(gòu)建mini-cursor的完整過程我們不僅實(shí)現(xiàn)了一個可運(yùn)行的Agent更重要的是我們親手觸摸了Agent每一個組件的脈搏理解了它們?nèi)绾螀f(xié)同工作。下次當(dāng)你使用LangChain的initialize_agent時你看到的將不再是一個魔法函數(shù)而是一個由清晰的數(shù)據(jù)流和控制邏輯構(gòu)成的、你可以預(yù)測和調(diào)試的系統(tǒng)。這才是“完全實(shí)戰(zhàn)”帶來的真正力量——從知其然到知其所以然最終到創(chuàng)造屬于你自己的“然”。