還在糾結(jié)要不要給項(xiàng)目引入 Agent 的時(shí)候我第一個(gè)跳出來(lái)的念頭就是別給項(xiàng)目加一堆東西先把你頭腦里的推理過(guò)程翻譯成一個(gè)循環(huán)。ReAct 這個(gè)名字一旦出現(xiàn)網(wǎng)上搜出來(lái)的全是框架、庫(kù)、Agent 中間件搞得人以為這是什么重量級(jí)方案。實(shí)際上你要是把 ReAct 的論文扒開(kāi)看它做的事情就一句話讓模型在思考和行動(dòng)之間反復(fù)橫跳直到得出答案。翻譯成代碼不過(guò)是一個(gè) while 循環(huán)加幾個(gè)狀態(tài)變量。我寫(xiě)這篇文章就是想把這個(gè)推理模式拆到你能親手寫(xiě)出來(lái)不依賴任何 Agent 框架不引入額外的抽象層只需要一個(gè)循環(huán)、一次 LLM 調(diào)用、和一個(gè)能執(zhí)行動(dòng)作的函數(shù)。我先說(shuō)結(jié)論ReAct 的價(jià)值根本不在工程實(shí)現(xiàn)而在它強(qiáng)迫你回答兩個(gè)問(wèn)題——模型應(yīng)該看到什么和模型下一步能做什么。想明白了代碼反而簡(jiǎn)單到讓人懷疑是不是漏了東西。這篇文章會(huì)從 ReAct 的推理模式拆解開(kāi)始給出一個(gè)完全可運(yùn)行的最小實(shí)現(xiàn)再逐步加上 LLM 接入、解析容錯(cuò)、終止條件這些實(shí)操細(xì)節(jié)最后把我自己踩過(guò)的坑列成一張排查表。適合那種不想被框架綁架、想真正理解 Agent 內(nèi)部機(jī)制的開(kāi)發(fā)者也適合第一次接觸 Agent 的初學(xué)者照著抄作業(yè)。1. ReAct 不是框架是推理循環(huán)的重命名好多人對(duì) ReAct 的第一印象是被 Agent 框架給帶偏的。市面上太多實(shí)現(xiàn)了 ReAct 模式的庫(kù)裝個(gè)包、配個(gè) key、跑一個(gè) demo任務(wù)完成了但腦子里留下的印象是ReAct 很復(fù)雜。其實(shí) ReAct 甚至算不上一個(gè)新概念。它的全稱是 Reasoning Acting出自 2022 年那篇《ReAct: Synergizing Reasoning and Acting in Language Models》核心思想是在提示詞里把模型的推理過(guò)程拆成 Thought、Action、Observation 三步讓模型交替輸出思考內(nèi)容、調(diào)用外部工具的動(dòng)作、以及基于執(zhí)行結(jié)果的新觀察。這三步不斷重復(fù)直到模型輸出最終答案。你把它和普通 LLM 對(duì)話對(duì)比一下就明白了。普通對(duì)話里你問(wèn)模型一個(gè)問(wèn)題模型直接給答案遇到?jīng)]法從內(nèi)部知識(shí)回答的問(wèn)題就瞎編。ReAct 多了一個(gè)行動(dòng)環(huán)節(jié)模型可以說(shuō)我拿不準(zhǔn)我要查一下或者我要算一下然后系統(tǒng)真的去執(zhí)行這個(gè)動(dòng)作把結(jié)果喂回給它。模型再基于這個(gè)新信息繼續(xù)推理。這不就是一個(gè)人處理陌生問(wèn)題的流程嗎先想再做再看結(jié)果再想。放到程序里這就是循環(huán)結(jié)構(gòu)。為什么我用重命名這個(gè)詞因?yàn)檠h(huán)這個(gè)概念早就存在ReAct 只是把循環(huán)的每一步應(yīng)該做什么規(guī)范化了。它定義了一種模型與外部環(huán)境交互的模式而不是定義了一套你要安裝的軟件。搜 ReAct 的時(shí)候出來(lái)的 react 框架、react native 教程、react 面試題那是另一個(gè)生態(tài)圈的東西。真正的 ReAct 模式既不需要包管理器也不需要組件樹(shù)你要做的只是寫(xiě)一個(gè)循環(huán)然后設(shè)計(jì)好每一步的提示詞。1.1 為什么框架感會(huì)誤導(dǎo)你框架給我們的暗示是你引入一個(gè)東西然后按照它的生命周期去寫(xiě)代碼。但 ReAct 的核心邏輯簡(jiǎn)單到可以被任何程序語(yǔ)言的三五行偽代碼概括。如果你抱著我要用 ReAct 框架的心態(tài)去搜索大概率會(huì)找到一個(gè)安裝命令、一個(gè)配置文件、一套事件機(jī)制然后陷入配置地獄。這種路徑不是不能實(shí)現(xiàn)功能而是把你和真實(shí)原理隔開(kāi)了。我自己強(qiáng)烈建議先脫離框架去手寫(xiě)一遍。原因有三個(gè)第一框架把循環(huán)、解析、調(diào)用這些細(xì)節(jié)都封裝了你出了問(wèn)題根本不知道從哪里查。手寫(xiě)版本只有幾個(gè)變量和幾十行代碼邏輯鏈路全在眼皮底下。第二框架通常自帶提示詞模板但真實(shí)業(yè)務(wù)里你可能需要定制模型輸出格式、調(diào)整最大步數(shù)、改終止條件。如果你不理解底層循環(huán)改這些全憑感覺(jué)。第三面試和團(tuán)隊(duì)溝通的時(shí)候你能說(shuō)清楚我們的 Agent 本質(zhì)是一個(gè)帶終止條件的 while 循環(huán)這比我用了某個(gè)框架的某個(gè) Agent 類要有說(shuō)服力得多。這里我不是否定框架的價(jià)值等你想清楚每一步的原理之后找一個(gè)工程化框架來(lái)省時(shí)間是完全合理的。但這篇文章的目的就是讓你先想清楚。1.2 用生活化的方式理解 ReAct 循環(huán)如果你喊家里的小朋友幫忙找個(gè)東西會(huì)發(fā)生這個(gè)過(guò)程你說(shuō)去客廳找一下遙控器——這是初始任務(wù)小朋友走進(jìn)客廳看了一圈沒(méi)找到——這是執(zhí)行一個(gè)動(dòng)作并得到觀察結(jié)果他想了想遙控器可能在沙發(fā)縫里——這是基于觀察的推理他翻開(kāi)沙發(fā)墊——新動(dòng)作發(fā)現(xiàn)了遙控器——新觀察于是回答你找到了——終止條件滿足。這個(gè)場(chǎng)景里的每一步都可以對(duì)應(yīng)到 ReAct 循環(huán)思考生成下一動(dòng)作的計(jì)劃動(dòng)作被系統(tǒng)執(zhí)行系統(tǒng)把執(zhí)行結(jié)果作為觀察返回模型基于新的觀察繼續(xù)思考。整個(gè)流程重復(fù)執(zhí)行直到模型認(rèn)為問(wèn)題已經(jīng)解決。你可以把 while 循環(huán)看成小朋友未找到遙控器之前他不能停下來(lái)的規(guī)則。循環(huán)體和終止條件就是 ReAct 的全部秘密。2. 解剖 ReAct 推理模式Thought、Action、Observation 三段式ReAct 循環(huán)的每次迭代模型要輸出一段結(jié)構(gòu)化文本通常包含三個(gè)字段Thought當(dāng)前推理、Action決定做什么、Action Input動(dòng)作參數(shù)。系統(tǒng)執(zhí)行完動(dòng)作后把結(jié)果以 Observation 字段的形式追加到上下文里。這四樣?xùn)|西拼在一起構(gòu)成模型下一輪推理的輸入。有些人會(huì)把 Action 和 Action Input 合并稱成一步但本質(zhì)上這三個(gè)字段代表三種不同的信息Thought 是模型的思維鏈Action 是動(dòng)作選擇Observation 是環(huán)境的反饋?？梢岳斫鉃門(mén)hought 是決策的理由Action 是決策的結(jié)果Observation 是決策的后果。2.1 手寫(xiě)偽代碼把模式變成你能控制的邏輯在寫(xiě)真實(shí)代碼之前先用偽代碼搭建骨架初始化上下文 系統(tǒng)提示 用戶問(wèn)題 最大步數(shù) 10 步數(shù)計(jì)數(shù)器 0 最終答案 None while 最終答案是 None 且 步數(shù)計(jì)數(shù)器 最大步數(shù): 調(diào)用模型輸入上下文得到模型輸出 從模型輸出中解析出 Thought, Action, Action Input 如果 Action 是 Finish: 最終答案 Action Input 跳出循環(huán) 否則: 執(zhí)行 Action Action Input得到 Observation 把這一輪的所有輸出追加到上下文 步數(shù)計(jì)數(shù)器 1 如果最終答案是 None: 返回達(dá)到最大步數(shù)未得到答案 否則: 返回最終答案這就是 ReAct 的完整邏輯骨架和是不是用了框架完全沒(méi)有關(guān)系。你可以把這個(gè)骨架翻譯成任何語(yǔ)言甚至翻譯成手寫(xiě)的狀態(tài)機(jī)。循環(huán)條件有兩個(gè)一個(gè)是模型主動(dòng)說(shuō)完成一個(gè)是步數(shù)上限兜底。這兩個(gè)條件的順序也值得注意每次迭代都要先檢查模型是否給出了最終答案而步數(shù)上限是在每次循環(huán)之后判斷的確保至少能執(zhí)行一次動(dòng)作。2.2 為什么終止條件這么關(guān)鍵如果把 ReAct 循環(huán)比作一個(gè)員工終止條件就是明確的下班標(biāo)準(zhǔn)。沒(méi)有這個(gè)標(biāo)準(zhǔn)的循環(huán)會(huì)出兩類問(wèn)題一類是模型反復(fù)執(zhí)行相同動(dòng)作進(jìn)入死循環(huán)另一類是模型胡亂猜答案在錯(cuò)誤的觀察上越走越遠(yuǎn)。我建議把最大步數(shù)的默認(rèn)值設(shè)成 8 到 10 步。設(shè)太短多步驟工具調(diào)用沒(méi)跑完就被截?cái)嘣O(shè)太長(zhǎng)如果模型行為異常你要付出好幾倍的 token 成本和時(shí)間成本。實(shí)際項(xiàng)目中可以做成可配置項(xiàng)并且每次循環(huán)記錄一下已消耗的 token 數(shù)一旦超預(yù)算就終止。這比只有步數(shù)限制更符合真實(shí)場(chǎng)景因?yàn)橛行﹦?dòng)作返回的文本特別長(zhǎng)步數(shù)沒(méi)超但 token 已經(jīng)吃了很多。Finch 動(dòng)作是另一個(gè)關(guān)鍵。ReAct 提示詞里必須告訴模型當(dāng)你認(rèn)為問(wèn)題已經(jīng)解決時(shí)輸出 Action: Finish并且把最終答案放在 Action Input 里。有些實(shí)現(xiàn)會(huì)輸出 Final Answer 字段本質(zhì)上是一樣的。你把什么時(shí)候算完成這個(gè)判定權(quán)交給模型同時(shí)用步數(shù)上限做兜底這就是工程上的雙保險(xiǎn)。2.3 動(dòng)作空間設(shè)計(jì)ReAct 模式的核心決策ReAct 循環(huán)里可以執(zhí)行的動(dòng)作是你在系統(tǒng)提示詞里預(yù)先聲明的。比如你有 search 和 calculate 兩個(gè)工具你就要在提示詞里寫(xiě)清楚每個(gè)工具的用途和參數(shù)格式。動(dòng)作空間設(shè)計(jì)的好壞直接決定了模型能不能高效解決問(wèn)題。我見(jiàn)過(guò)兩個(gè)極端一個(gè)動(dòng)作空間全塞滿給了模型十幾個(gè)工具它每次都在做選擇題另一個(gè)動(dòng)作空間狹窄到只有一個(gè)搜索工具模型遇到計(jì)算問(wèn)題也去搜得出錯(cuò)誤答案。好的設(shè)計(jì)是給模型提供最小但足夠的工具集。工具太少模型無(wú)法完成任務(wù)工具太多模型的選擇成本上升出錯(cuò)概率也上升。我的經(jīng)驗(yàn)是一個(gè) Agent 任務(wù)的工具數(shù)量控制在三到五個(gè)之間每個(gè)工具的參數(shù)盡量簡(jiǎn)單最好都支持 JSON 格式的參數(shù)描述。工具描述文本也直接影響執(zhí)行質(zhì)量。描述應(yīng)該包含什么時(shí)候用的場(chǎng)景說(shuō)明而不只是做什么。比如寫(xiě) search 工具的描述時(shí)不要只寫(xiě)搜索互聯(lián)網(wǎng)要寫(xiě)當(dāng)需要查詢實(shí)時(shí)信息、驗(yàn)證事實(shí)、或查找不熟悉的內(nèi)容時(shí)使用此工具輸入為搜索關(guān)鍵詞。這樣模型在思考階段更容易做出準(zhǔn)確的工具選擇。這一點(diǎn)很多人忽略但它對(duì) ReAct 效果的影響比模型選擇的差別還要大。3. 手寫(xiě)核心循環(huán)一份能跑的 Python 實(shí)現(xiàn)進(jìn)入實(shí)操環(huán)節(jié)。我們用 Python 寫(xiě)一個(gè)不依賴任何 Agent 框架的 ReAct 循環(huán)。這段代碼的目標(biāo)不是完成一個(gè)炫酷的項(xiàng)目而是把一個(gè)最小可運(yùn)行的 ReAct 機(jī)制擺在你面前每個(gè)變量都能看明白。3.1 環(huán)境準(zhǔn)備與項(xiàng)目文件結(jié)構(gòu)只需要 Python 3.9 以上環(huán)境不需要安裝任何框架庫(kù)。如果你要接 OpenAI 兼容的 LLM 接口需要安裝 openai 或 requests任選其一。我建議先用一個(gè)假的 LLM 來(lái)調(diào)試循環(huán)本身因?yàn)檫@樣能隔離問(wèn)題循環(huán)邏輯的 bug 和 LLM 接口的 bug 分開(kāi)排查。目錄結(jié)構(gòu)盡量簡(jiǎn)單react_loop/ |-- main.py # 主程序 |-- tools.py # 工具定義 |-- llm_client.py # LLM 調(diào)用封裝先把工具函數(shù)寫(xiě)好。假設(shè)我們有兩個(gè)工具一個(gè)計(jì)算加法一個(gè)獲取當(dāng)前時(shí)間。computed 的場(chǎng)景雖然簡(jiǎn)單但已經(jīng)足夠演示 ReAct 的動(dòng)作調(diào)用和觀察返回。3.2 核心 while 循環(huán)代碼詳解main.py 的核心部分如下import json from tools import add_numbers, get_current_time from llm_client import call_llm SYSTEM_PROMPT 你是一個(gè)能調(diào)用工具的智能體。你有以下工具可用 - add_numbers: 輸入兩個(gè)數(shù)字返回它們的和。參數(shù)格式: {a: 數(shù)字, b: 數(shù)字} - get_current_time: 返回當(dāng)前時(shí)間。參數(shù)格式: {} 你的輸出必須嚴(yán)格按照以下格式 Thought: 你的推理過(guò)程 Action: 工具名稱 或 Finish Action Input: 工具的 JSON 參數(shù) 或 最終答案 .strip() def execute_action(action: str, action_input: str) - str: if action add_numbers: args json.loads(action_input) return str(add_numbers(args[a], args[b])) elif action get_current_time: return get_current_time() elif action Finish: return action_input else: raise ValueError(f未知?jiǎng)幼? {action}) def react_loop(question: str, max_steps: int 10): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: question}, ] context messages for step in range(1, max_steps 1): model_output call_llm(context) print(f\n--- 第 {step} 輪 ---) print(model_output) parsed parse_output(model_output) if parsed is None: print(解析失敗終止循環(huán)) return ERROR: 模型輸出格式解析失敗 thought, action, action_input parsed if action Finish: return action_input try: observation execute_action(action, action_input) except Exception as e: observation f工具執(zhí)行失敗: {str(e)} context context [ {role: assistant, content: model_output}, {role: user, content: fObservation: {observation}}, ] return ERROR: 達(dá)到最大步數(shù)仍未得出最終答案 if __name__ __main__: print(react_loop(現(xiàn)在是幾點(diǎn)))這里有幾處需要認(rèn)真理解第一循環(huán)用的是for step in range(1, max_steps 1)這樣就天然有了步數(shù)上限同時(shí) step 變量可以直接用于打印日志。它本質(zhì)上是 while 循環(huán)的一種確定次數(shù)變體但效果一樣。第二assistant 輸出一整段被放回上下文隨后緊接著一個(gè)偽造的 user 消息內(nèi)容為 Observation。為什么要偽裝成 user 角色因?yàn)榇蟛糠帜Ｐ筒粫?huì)自己輸出 ObservationObservation 是環(huán)境產(chǎn)生的不屬于模型所以我們要把它作為外部輸入塞回去。這種角色安排在很多框架里被簡(jiǎn)寫(xiě)成Observation 前綴消息但我更傾向于明確使用 user 角色兼容性更好。3.3 輸出解析函數(shù)把模型的自由文本變成可執(zhí)行指令模型輸出的文本需要被解析成結(jié)構(gòu)化的 Thought、Action、Action Input。這個(gè)解析函數(shù)是整個(gè)循環(huán)能不能穩(wěn)定的關(guān)鍵def parse_output(text: str): lines text.strip().split(\n) thought None action None action_input None for line in lines: if line.startswith(Thought:): thought line[len(Thought:):].strip() elif line.startswith(Action:): action line[len(Action:):].strip() elif line.startswith(Action Input:): action_input line[len(Action Input:):].strip() if action is None: return None return thought, action, action_input這個(gè)解析方式比較天真只適用于模型嚴(yán)格按說(shuō)明輸出的情況。實(shí)際項(xiàng)目中你會(huì)遇到模型不老實(shí)比如把 Action Input 寫(xiě)成了多行、或者 Action 行寫(xiě)成了Action: add_numbers 參數(shù)是...這種多余描述。我們?cè)诘谖骞?jié)再談怎么增強(qiáng)魯棒性。現(xiàn)在用這個(gè)單純版本因?yàn)樗倪壿嬊逦奖隳阏{(diào)試。3.4 手動(dòng)模擬一輪 LLM 輸出打通整個(gè)流程讓我手動(dòng)模擬一次調(diào)用幫助你理解每次循環(huán)的數(shù)據(jù)流。假設(shè)用戶問(wèn)題是請(qǐng)問(wèn) 23 加 19 等于多少模型第一次的輸出可能是Thought: 用戶需要計(jì)算兩個(gè)數(shù)字的和我需要使用 add_numbers 工具。 Action: add_numbers Action Input: {a: 23, b: 19}解析后執(zhí)行 execute_action得到 observation 為 42。然后我們把這個(gè)模型輸出和 observation 一起追加到上下文。回到循環(huán)頂部模型現(xiàn)在看到的歷史記錄包括它上一輪的 Thought 和 Action以及系統(tǒng)返回的 Observation于是它會(huì)在下一輪輸出Thought: 我已經(jīng)得到了計(jì)算結(jié)果可以回答用戶了。 Action: Finish Action Input: 23 加 19 等于 42循環(huán)檢測(cè)到 Finish返回最終答案。這個(gè)過(guò)程你可以在 main.py 里打印每一步的上下文確認(rèn)數(shù)據(jù)結(jié)構(gòu)變化。這是最直接的調(diào)試手段。4. 接入真實(shí) LLM讓循環(huán)真正工作起來(lái)上面的循環(huán)是骨架現(xiàn)在我們要把它接到真實(shí)的 LLM 接口上。llm_client.py 負(fù)責(zé)完成這一層封裝。我以 OpenAI 兼容接口為例因?yàn)槟壳敖^大多數(shù)開(kāi)源模型、國(guó)內(nèi)大模型服務(wù)都提供這個(gè)協(xié)議的接口遷移成本很低。4.1 LLM 調(diào)用封裝與上下文管理from openai import OpenAI client OpenAI( base_url你的模型服務(wù)地址, api_key你的密鑰 ) def call_llm(messages: list, max_tokens: int 500, temperature: float 0): response client.chat.completions.create( model你的模型名, messagesmessages, max_tokensmax_tokens, temperaturetemperature, ) return response.choices[0].message.contenttemperature 設(shè)為 0 或者非常低這一點(diǎn)極其重要。ReAct 循環(huán)里我們希望模型輸出的動(dòng)作能夠穩(wěn)定復(fù)現(xiàn)高溫度會(huì)讓模型在 Action 選擇上飄忽不定同一個(gè)問(wèn)題可能得出完全不同的工具調(diào)用序列。我自己通常設(shè)成 0只有在做頭腦風(fēng)暴類的 Agent 時(shí)才調(diào)到 0.3 以上。max_tokens 也要注意。模型一次推理輸出的文本通常不會(huì)太長(zhǎng)但 Action Input 如果是長(zhǎng)文本比如搜索術(shù)語(yǔ)幾百個(gè) token 也有必要。500 是一個(gè)比較安全的默認(rèn)值可以避免因?yàn)檩敵鼋財(cái)鄬?dǎo)致 Action 不完整的問(wèn)題。如果發(fā)現(xiàn)模型經(jīng)常在中間截?cái)嘞葯z查 max_tokens 而不是換模型。4.2 完整流程從問(wèn)題到答案的完整循環(huán)日志真實(shí)運(yùn)行一次日志通常會(huì)長(zhǎng)成這個(gè)樣子--- 第 1 輪 --- Thought: 用戶想知道當(dāng)前時(shí)間我應(yīng)該用 get_current_time 工具獲取。 Action: get_current_time Action Input: {} --- 第 2 輪 --- Thought: 我已經(jīng)獲得了當(dāng)前時(shí)間可以直接回答。 Action: Finish Action Input: 當(dāng)前時(shí)間是 2024-06-15 14:30:00。如果第一個(gè)工具沒(méi)有解決還會(huì)繼續(xù)。比如用戶問(wèn)一個(gè)需要兩步的問(wèn)題--- 第 1 輪 --- Thought: 我需要先獲取商品價(jià)格再計(jì)算總價(jià)。 Action: get_product_price Action Input: {product: apple} --- 第 2 輪 --- Thought: 蘋(píng)果單價(jià)是 5 元用戶買(mǎi)了 3 個(gè)需要計(jì)算總價(jià)。 Action: multiply Action Input: {a: 5, b: 3} --- 第 3 輪 --- Thought: 總價(jià)是 15 元回答用戶。 Action: Finish Action Input: 總價(jià)是 15 元這種多步調(diào)用體現(xiàn)了 ReAct 的價(jià)值第一步獲取數(shù)據(jù)第二步處理數(shù)據(jù)第三步總結(jié)。每一步的觀察都被保存在上下文里模型可以在后續(xù)推理中引用。4.3 上下文膨脹問(wèn)題循環(huán)的隱形成本ReAct 循環(huán)有個(gè)不太好直接看見(jiàn)的問(wèn)題每一輪都會(huì)把模型的整段輸出和觀察追加到上下文上下文長(zhǎng)度會(huì)線性增長(zhǎng)。如果工具返回的觀察很長(zhǎng)比如搜索引擎返回一大段網(wǎng)頁(yè)摘要幾輪之后就可能超出模型的上下文窗口。處理這個(gè)問(wèn)題的常規(guī)思路有三種。第一種是截?cái)?Observation只保留前 N 個(gè)字符。第二種是讓工具本身返回摘要比如搜索工具不要把全文都返回而是返回標(biāo)題加摘要。第三種是定期壓縮歷史消息把前面的 Thought 和 Action 合并成一句話。我建議優(yōu)先用第二種思路因?yàn)樗鼜脑搭^減少數(shù)據(jù)量效果最明顯。比如一個(gè)網(wǎng)絡(luò)搜索工具完整網(wǎng)頁(yè)內(nèi)容可能是幾萬(wàn)字但你只需要返回給模型一個(gè)兩三百字的摘要。這個(gè)摘要可以由工具內(nèi)部完成也可以在把結(jié)果塞給大模型之前做一次 LLM 摘要。我踩過(guò)一次很深的坑當(dāng)時(shí)直接讓搜索工具返回整個(gè)網(wǎng)頁(yè)的正文第三輪循環(huán)之后輸入長(zhǎng)度就爆了報(bào)錯(cuò)提示超出上下文限制。后來(lái)加了一層摘要模塊把網(wǎng)頁(yè)正文壓縮到 300 字以內(nèi)問(wèn)題立竿見(jiàn)影。節(jié)省的不只是上下文空間還有 token 成本每一輪循環(huán)都在為你的上下文長(zhǎng)度買(mǎi)單。4.4 超時(shí)與錯(cuò)誤處理機(jī)制真實(shí)場(chǎng)景里工具調(diào)用可能失敗LLM 接口可能超時(shí)。如果不處理整個(gè)循環(huán)就會(huì)卡死或崩潰。我在 execute_action 外面包了一層 try-except把異常信息轉(zhuǎn)換為 Observation 文字工具執(zhí)行失敗: 網(wǎng)絡(luò)錯(cuò)誤請(qǐng)重試。這比讓循環(huán)崩掉要好得多因?yàn)槟Ｐ涂吹搅隋e(cuò)誤信息可能會(huì)選擇換一個(gè)工具或換一種參數(shù)重試。這種把錯(cuò)誤作為觀察反饋給模型的做法是 ReAct 容錯(cuò)的核心技巧。LLM 接口超時(shí)需要單獨(dú)處理。我的做法是在 call_llm 里設(shè)置客戶端超時(shí)時(shí)間比如 30 秒。如果超時(shí)就拋出一個(gè)特定異常在循環(huán)內(nèi)捕獲并重試一次重試仍失敗則提前返回錯(cuò)誤信息。這里要注意的是不要把超時(shí)報(bào)錯(cuò)直接當(dāng)作 Observation 喂給模型那樣模型可能長(zhǎng)期陷入重試同一動(dòng)作的死胡同。要給它一個(gè)明確指令超時(shí)后停止循環(huán)告訴用戶系統(tǒng)暫時(shí)不可用。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄手寫(xiě) ReAct 循環(huán)的過(guò)程中你一定會(huì)遇到下面這些問(wèn)題。我把它們整理成一張速查表每個(gè)都附上我的排查思路和解決建議。5.1 模型輸出格式不穩(wěn)定Action 解析不出來(lái)這是最高頻的問(wèn)題。模型沒(méi)有按你要求的格式輸出可能把 Action Input 寫(xiě)成多行或者在 Action 后面加了括號(hào)說(shuō)明。我的經(jīng)驗(yàn)是做一個(gè)多級(jí)解析策略。首先嘗試按行前綴解析解析失敗就嘗試正則表達(dá)式再失敗就把整個(gè)文本當(dāng)作 Thought 并把無(wú)法識(shí)別的部分提示給模型要求它重新輸出標(biāo)準(zhǔn)格式。如果連續(xù)三次解析失敗不要無(wú)限重試直接終止循環(huán)。關(guān)鍵點(diǎn)在于提示詞本身要寫(xiě)得非常嚴(yán)格你的輸出必須嚴(yán)格遵循以下格式不要輸出任何額外內(nèi)容 Thought: 你的推理 Action: 工具名或 Finish Action Input: JSON 格式參數(shù)或最終答案我在提示詞里會(huì)再加一句Action Input 必須是合法 JSON不得包含換行。這句話能顯著減少多行 JSON 帶來(lái)的解析問(wèn)題。5.2 循環(huán)進(jìn)入了死循環(huán)模型反復(fù)執(zhí)行同一個(gè)動(dòng)作模型可能因?yàn)橛^察結(jié)果不符合預(yù)期一遍遍嘗試同一個(gè)工具。我見(jiàn)過(guò)最離譜的情況是模型連續(xù)六次調(diào)用同一個(gè)搜索動(dòng)作參數(shù)一模一樣每次都返回同樣的結(jié)果然后它又接著搜索。排查思路有兩個(gè)第一檢查觀察返回是否太冗長(zhǎng)模型可能沒(méi)有注意到它已經(jīng)看過(guò)這個(gè)結(jié)果了第二在系統(tǒng)提示詞里明確告訴模型如果觀察結(jié)果與之前某一步完全相同說(shuō)明該路徑無(wú)效必須更換策略。代碼層面也可以加一個(gè)動(dòng)作去重機(jī)制維護(hù)一個(gè)已經(jīng)執(zhí)行過(guò)的動(dòng)作哈希集合如果當(dāng)前動(dòng)作重復(fù)出現(xiàn)且參數(shù)一致就自動(dòng)返回一個(gè)提示觀察讓模型換個(gè)方向。這算是工程上對(duì)模型推理能力不足的一個(gè)補(bǔ)丁實(shí)踐證明很有效。5.3 Action Input 是非法 JSON占比很高模型可能輸出{a: 23}而不是{a: 23}字符串和數(shù)字混淆也可能輸出帶注釋的 JSON或者用單引號(hào)代替雙引號(hào)。不要把 JSON 解析失敗直接拋給用戶。我的做法是寫(xiě)一個(gè)寬容解析函數(shù)先嘗試 json.loads失敗后用正則提取數(shù)字和鍵名再拼回合法的 JSON。另一個(gè)更省心的方案是把參數(shù)格式設(shè)計(jì)成字符串比如 add_numbers 的 Action Input 直接是 23 19工具內(nèi)部再用 split 切分。犧牲一點(diǎn)結(jié)構(gòu)換取穩(wěn)定性在動(dòng)作很簡(jiǎn)單的時(shí)候是劃算的。5.4 模型提前 Finish答案明顯不對(duì)這是最難排查的問(wèn)題之一因?yàn)檠h(huán)本身沒(méi)有報(bào)錯(cuò)但你一看結(jié)果就知道不對(duì)?？赡艿脑虬ㄌ崾驹~里的例子引導(dǎo)了模型讓它誤以為問(wèn)題簡(jiǎn)單到可以直接回答或者上下文里的歷史軌跡讓模型產(chǎn)生了幻覺(jué)。我建議在系統(tǒng)提示詞里加一條硬性規(guī)則除非你已經(jīng)執(zhí)行了至少一個(gè)工具調(diào)用并且獲得了觀察結(jié)果否則不得輸出 Finish。這樣能強(qiáng)制模型至少嘗試一輪工具調(diào)用避免它純靠?jī)?nèi)部知識(shí)作答。如果已經(jīng)完成了工具調(diào)用但答案還是錯(cuò)那大概率是 Observation 被截?cái)嗄Ｐ蜎](méi)看到完整信息或者工具本身返回的數(shù)據(jù)有問(wèn)題。這時(shí)候需要在日志里檢查工具返回的原始內(nèi)容確認(rèn)數(shù)據(jù)源是否存在缺陷。很多情況下問(wèn)題不在 ReAct 循環(huán)而在工具的執(zhí)行質(zhì)量。5.5 幾個(gè)讓你少走彎路的調(diào)試手段把每一輪的完整消息數(shù)組打印出來(lái)存成 JSON 文件。這樣隨時(shí)可以復(fù)盤(pán)模型到底看到了什么。像這樣在循環(huán)內(nèi)print(json.dumps(context, ensure_asciiFalse, indent2))你會(huì)發(fā)現(xiàn)很多詭異行為都能歸因于上下文里的某條歷史消息。做一個(gè)無(wú)外部依賴的假工具調(diào)試環(huán)境也就是我在第三節(jié)代碼里演示的兩個(gè)簡(jiǎn)單工具。先用這些假工具把循環(huán)調(diào)順再換成真實(shí)業(yè)務(wù)工具。環(huán)境越簡(jiǎn)單定位問(wèn)題越快。最后所有工具調(diào)用的入?yún)ⅰ⒊鰠?、耗時(shí)都要打日志。Agent 循環(huán)是黑盒屬性很強(qiáng)的東西沒(méi)有日志你基本就是盲人摸象。我認(rèn)為這一條比任何框架特性都重要。6. 從 ReAct 循環(huán)走出來(lái)的下一步你已具備手寫(xiě) Agent 的基礎(chǔ)把 ReAct 循環(huán)手寫(xiě)一遍之后你對(duì) Agent 的理解會(huì)和只聽(tīng)說(shuō)Agent 大模型 工具調(diào)用的人完全不同。你知道了每一步的數(shù)據(jù)流長(zhǎng)什么樣知道了模型輸出如何被解析為動(dòng)作知道了觀察如何回灌上下文也知道了終止條件為什么需要雙保險(xiǎn)。這些認(rèn)知無(wú)法通過(guò)安裝框架獲得只能靠你一行行寫(xiě)出來(lái)、一遍遍調(diào)試出來(lái)。我個(gè)人還會(huì)在這個(gè)基礎(chǔ)上再加兩層?xùn)|西。第一層是記憶機(jī)制把經(jīng)過(guò)壓縮的歷史摘要放入上下文讓循環(huán)可以處理更長(zhǎng)的問(wèn)題。第二層是規(guī)劃?rùn)C(jī)制在進(jìn)入 ReAct 循環(huán)之前先讓模型生成一個(gè)整體計(jì)劃然后循環(huán)按照計(jì)劃執(zhí)行。這兩層都屬于 ReAct 模式的外延核心骨架仍然是那個(gè) while 循環(huán)。最后再分享一個(gè)我在項(xiàng)目里的實(shí)際用法不要全天候把所有請(qǐng)求都放進(jìn) ReAct 循環(huán)?？梢韵茸屍胀ù竽Ｐ椭苯踊卮鹜ㄟ^(guò)一個(gè)置信度判斷只有低置信度時(shí)再進(jìn)入 ReAct 模式。這樣能大幅降低 token 成本和延遲。這個(gè)小技巧幫我省下了很多不必要的工具調(diào)用成本也希望你在自己寫(xiě) ReAct 循環(huán)時(shí)能感受到這種掌控一切的踏實(shí)感。從你寫(xiě)出第一個(gè)能運(yùn)行的 while 循環(huán)那一刻起Agent 對(duì)你就再也沒(méi)有黑魔法了。