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