← 部落格
使用者實踐閱讀約 20 分鐘

我為什麼推倒重寫了自己的 AI Agent?

一次重寫,讓我重新理解狀態、脈絡和系統邊界。

Translated by AI
開發者將複雜的水母形 Agent 拆開,重新組織記憶、訊息與工作流模組。
重寫的起點,是重新理解每個模組應該承擔什麼。

第一次把 Agent 的主鏈路跑通時,我以為最難的部分已經結束了。

模型能呼叫,資料能落庫,向量能召回,工作流也能順利走到最後。對於一個第一次用 LangGraph 做完整專案的人來說,這已經足夠讓我興奮一陣子。

但真正開始連續使用,問題才一個個冒出來:明明配置了 checkpoint,下一輪模型卻不知道上一輪發生了什麼;工作流拆得很細,狀態裡卻塞滿了沒必要保存的中間產物;資料庫裡存了不少資訊,模型拿到的脈絡卻未必有用。

更難受的是,每當產品需求發生變化,我總要先解釋一遍,為什麼現有架構不太支援這個需求,再想辦法把它硬塞進去。

後來,我決定重寫。

為了方便討論,下面隱去專案的具體業務,把它看作一個需要持續累積脈絡、支援多輪互動的對話 Agent。這篇也不打算羅列一遍技術棧,我更想聊聊那些真正讓我卡住的地方,以及這些問題怎樣改變了我對 Agent 開發的理解。

一、我把工作流狀態,當成了模型的記憶

最早的架構是一條比較長的 Pipeline:載入業務物件、整理基礎資料、建構檢索 query、召回資訊、組織脈絡,最後呼叫模型。

為了方便節點之間傳遞資料,我把途中產生的東西幾乎全部放進了 Graph State。查詢結果、檢索 query、組織到一半的脈絡,甚至 SQLAlchemy 的 ORM 實例,都往裡面塞。

當時的理解很簡單:State 不就是跨節點共享的資料嗎?放進去,下個節點直接拿,多方便。

直到接入 checkpoint,問題來了。

首先是序列化。ORM 實例不能像普通字典一樣直接交給當時的 checkpoint 序列化鏈路。其次是持久化範圍:很多只在本次執行中有用的臨時資料,也跟著狀態一起被存了下來。

我最初的修法是在最後一個節點裡把中間欄位清空。後來才意識到,checkpoint 在執行過程中就會記錄狀態,最後清空一次,並不能消除前面已經寫下的快照。

但這還不是最大的坑。

為了支援連續追問,我希望第二輪直接複用第一輪保存的脈絡,省掉一次耗時的建構過程。配置相同的 thread_id,接著呼叫 Graph,結果模型仍然像沒見過上一輪一樣。

仔細看鏈路,原因其實很直白:狀態恢復了,但我在呼叫模型時,只建構了一條新的 HumanMessage。歷史資訊躺在 State 裡,沒有被組織進本次請求,模型自然看不到。

更離譜的是,第二輪輸入裡,我還給脈絡欄位傳了一個空字串。本來想表達「這輪不重新計算」,實際效果卻是用空值覆蓋了已有狀態……

這次之後,我才真正把幾件事分開:

資料在系統裡的職責
節點內部的臨時變數完成當前步驟,用完即可丟棄
Graph State在節點間傳遞、按需要恢復的執行狀態
訊息歷史多輪互動中需要保留的對話內容
本次模型輸入當前任務真正需要消費的資訊

checkpoint 能幫助恢復執行狀態,但哪些內容進入模型輸入,仍然需要我自己設計。反過來,State 很大,也不意味著每次請求一定會消耗很多 token;只有把這些內容發送給模型,它們才會成為輸入成本。

這個區別看起來很基礎,但我確實是栽過一次才懂的。

我也重新考慮了節點的劃分。之前幾乎是一個函式拆一個 node,後來又一度走到另一個極端,把整條鏈路塞回一個 node。繼續做下去才發現,節點邊界應該跟著執行需求走:需要獨立觀察、分支路由或者並行調度的步驟,拆出來有價值;只在局部使用的轉換邏輯,普通函式就夠了。

存儲櫃裡的資訊經過選擇後,才被送入右側模型。
存下來的狀態,只有被組織進本次請求,才會成為模型能使用的脈絡。

二、模型處理得慢,有時是我給它出的題太難

早期有一條輸入鏈路,需要從截圖中恢復結構化記錄。

我要求模型識別每條訊息的說話人、內容、時間,再整理成嚴格的 JSON。為了提高準確性,還給使用者加了不少限制:截圖按順序上傳、包含時間、控制張數等等。

結果並不理想。一次嘗試中,兩張截圖處理了大約兩分鐘,仍然存在時間混亂、說話人錯位和無效內容。

第一反應當然是繼續調 prompt。但再看一遍最終用途,我突然發現,自己並不需要把原始記錄一條不漏地恢復出來。

下游真正需要的是:這段材料圍繞什麼主題,包含哪些值得保留的資訊,以及它們發生在什麼語境下。

於是我把資料粒度從「逐條原始記錄」調整為「圍繞一個主題組織的資訊」。模型不再承擔完整復原記錄的任務,後續檢索也不用先從大量零散訊息裡重新拼出語義。

當然,這個方案當時也有代價:我要求使用者單次提交的材料盡量屬於同一主題,相當於把一部分分段工作交還給了使用者。它減輕了處理負擔,但還不能算完全解決了輸入體驗。

這件事讓我開始習慣在優化模型之前,先問兩個問題:最終功能究竟需要什麼資訊?現在要求模型輸出的粒度,是不是超過了實際用途?

資料庫能裝下原始記錄,不代表模型必須逐條重建它;模型能輸出一套複雜結構,也不代表產品需要使用者等它把這套結構填完。

三、脈絡的難點,從「存下來」轉向「這輪怎麼用」

最初做記憶,我的注意力主要在寫入端:資料怎麼抽取、資料怎麼建模、文本怎麼向量化。

後來接觸一些以 Markdown 組織脈絡的方案,我發現它們在資訊分類和表達上有很多值得借鑑的地方。但我試用的方案中,一些檔案要求每輪必讀,其他檔案則按需全量載入。

資料少的時候,這樣很直接。資料逐漸變多之後,我開始擔心,每次只需要一小部分資訊,卻要先載入整份檔案。

於是重構時,我保留了基礎資料,把更細的資訊拆成獨立條目,支援後續按問題檢索。這裡,資料庫負責管理條目的歸屬、分類和時間,文本內容負責表達模型需要理解的語義。

但有了向量檢索,問題也沒有自動消失。

早期召回主要依賴語義距離。後來我逐漸加入業務範圍過濾、重要性權重,以及對部分資訊的時間衰減。因為「與問題很相似」和「適合用於當前回答」,並不是一回事。

尤其是時間。

我曾經只在系統提示詞裡放一個「當前時間」,後來才意識到,它無法說明歷史訊息分別發生在什麼時候。再往上游看,即使資料庫有建立時間,如果抽取後的文本丟掉了原始材料中的年份、時期或階段,模型仍然容易把不同時間發生的相似事情混在一起。

後來的調整分成兩部分:對話訊息顯式帶時間戳;抽取資訊時,把材料中可確認的時間錨點保留到正文裡,無法確定的時間則不補寫。

這比單純調整排序公式更靠前。時間資訊在抽取時丟了,檢索階段很難憑空找回來。

另外,我也嘗試過把知識召回封裝成 Tool,讓模型判斷何時需要補充資料,避免每輪機械地跑完整套檢索。

但 Tool Call 又暴露出另一個邊界:模型不能穩定生成當前業務物件的 ID。這個 ID 明明已經在系統執行脈絡裡,我卻還要求模型再猜一次。

最後,我在執行工具前注入當前脈絡中已確定的參數。模型可以決定是否需要檢索、檢索什麼;至於當前使用者是誰、正在操作哪個物件,以及是否有權存取,應該由程式確定和校驗。

這些問題做下來,我對脈絡的理解才從「收集得盡可能多」,逐漸轉向:為當前任務保留必要資訊,並讓它以合適的形式進入模型。

至於每項改動究竟提高了多少效果,我沒有足夠系統的評測資料,不想在這裡編一個百分比。能確認的是,我開始知道應該沿著哪條鏈路排查,而不再只盯著最終回答調提示詞。

四、拆了目錄,不代表真的解耦了

過去做 Web 專案,我很習慣先寫後端,再包裝 HTTP 介面,最後給前端呼叫。這個 Agent 最初也沿用了類似結構,業務能力和 Web 服務放得很近。

後來產品主要透過 IM 互動,我又加入 CLI,用來執行配置、管理和診斷操作。到這時,業務層繼續依賴 Web 框架就顯得很彆扭。

於是我把 Service 拆出來,讓它承載業務與資料存取能力,再由不同入口呼叫。

聽起來已經解耦了,對吧?現實又給了我一拳。

一次執行 CLI 的說明命令,輸出的竟然是 Web 框架的說明。

原因是命令模組匯入 Service,Service 又在頂層匯入了 Web 框架的 Request 型別。它原本只是一個型別註解,卻在執行時把整個框架帶進來,並影響了命令列參數解析。

修法並不複雜:純型別依賴移到 TYPE_CHECKING 下,命令註冊階段盡量保持輕量,真正執行時再載入必要模組。

但這件小事讓我意識到,架構圖上的依賴箭頭,最終要落實到模組匯入和初始化行為上。一個看起來很乾淨的 Service,如果匯入它就會帶起框架、讀取參數或啟動外部連線,換個入口呼叫時,問題照樣會冒出來。

後來我又為了簡化使用者配置,把一部分資料能力嘗試放到遠端。原先拿 ORM 物件的地方,要改為消費明確的返回結構;入口和 Graph 中散落的資料庫操作,也得繼續往 Service 收。

我加了一層統一分發:本地模式呼叫 Service,遠端模式呼叫對應 HTTP API。序列化也在這個邊界處理,避免列舉、時間物件和可選參數的轉換散落在各處。

比如一個缺省的查詢參數,在 Python 函式裡傳 None 很自然,到了 HTTP query 編碼卻可能直接報錯。修復應當收在請求邊界,同時保留 0、False 這些有實際意義的值;也不能順手把 JSON 請求體裡的顯式 null 一起刪掉。

這些都不是什麼複雜演算法,卻決定了「本地能呼叫的函式」能不能成為一個可靠的遠端介面。

五、使用者少配一個資料庫,系統就多了一組責任

做 CLI 和 IM 入口,最初是為了減少獨立前端的開發量,也讓使用者在熟悉的地方互動。

但把安裝流程串起來,我發現自己只是省掉了前端,使用者仍然要準備資料庫、模型配置和機器人配置。程式能跑通,距離使用者願意用,中間還有很長一段路。

因此我嘗試讓伺服器端承接資料庫存取,減少使用者自行建庫的負擔。

第一個約束很明確:不能為了方便,就把共享資料庫的連線憑證發到客戶端。普通資料操作可以透過鑑權 API 承接,但工作流的 checkpoint 依賴資料庫連線,它不會因為我加了 HTTP 路由,就自動獲得遠端儲存能力。

當時的處理是保留兩種行為:本地模式繼續用 PostgreSQL 持久化 checkpoint;實驗性的共享模式改用行程記憶體。

代價也很明確:行程重啟後,共享模式下的這部分短期記憶會丟失。

我沒有把這個問題徹底解決,只是接受了一個降級,換取不向客戶端暴露資料庫連線的執行方式。它也不意味著 checkpoint 永遠不能遠端化,只是當時那套分發層覆蓋不了它,繼續抽象的成本已經超出了那一輪的目標。

更麻煩的問題還在後面。

某些看起來是「資料同步」的 Service,內部其實會呼叫模型。把它移到伺服器端,究竟應該使用誰的模型配置?使用者的配置怎麼傳?呼叫成本由誰承擔?

原先在單機裡,資料庫、模型配置和執行環境都在同一個地方,這些問題很容易被忽略。跨過網路之後,每一項都得重新回答。

登入態也一樣。為減少背景任務被 token 過期打斷,我一度採用了不設定過期時間的方式。但它留下的輪換、撤銷和失效治理問題仍然存在,不能因為主鏈路繼續運行,就說鑑權已經設計完整。

最終,共享模式的部分鏈路雖然已經打通,我還是隱藏了公開配置入口。模型配置歸屬和伺服器端代執行的邊界沒有處理乾淨,就不應該讓使用者把它當成一個已經準備好的選項。

這也是我在產品層面的一次轉變:降低使用成本,意味著有人要承擔原先交給使用者的複雜度。資料庫不用使用者配了,伺服器端就要接住相應的權限、配置和執行責任。一個「Easy Mode」,遠不止是少展示幾個輸入框。

使用者桌面上的配置變簡單,背後的伺服器端承接權限、儲存、配置和執行責任。
使用者少配一項,系統就要接住相應的責任。

六、一次提示詞服務故障,讓我重新看待執行依賴

還有一次教訓,跟模型能力幾乎沒有關係。

為了方便調優,我把提示詞放在外部平台,執行時即時拉取。修改提示詞不必重新發布,開發體驗確實很好。

然後平台服務出故障了。

我既沒有保留本地備份,也沒有設計讀取失敗的兜底,涉及提示詞的鏈路一下子全部掛掉。外部服務大約兩天後恢復,但這兩天足夠讓我意識到:我把一個開發便利工具,放成了執行時的硬依賴。

這件事給我的教訓很具體。提示詞雖然是一段文本,在系統裡卻承擔著實際執行邏輯;它的版本、備份和可用性,都需要認真對待。把它放到遠端管理,並不會讓這些責任消失。

後來的開發過程中,我也開始把反覆出現的協作要求沉澱成 Skill:改動後做質檢、記錄變更、同步 Graph 文件,以及把糾偏寫回規則。

這些規程不能替代測試,也不能保證 Agent 每次都執行正確。但至少,同一種遺漏再次出現時,我有機會修改持續被消費的規則,而不只是再提醒一次。

寫到最後

回頭看,這次重寫並不是在某一天想通全部問題,然後畫一張新架構圖,一次性完成。

我先誤解 checkpoint,再重新設計狀態;先追求細粒度輸入,再回到下游實際需要的語義;先拆業務層、刪掉不必要的入口,後來為了新的部署方式又補回 HTTP 服務。新的問題不斷出現,前面做過的選擇也會被重新審視。

我不再特別糾結「當初是不是選錯了框架」。真正讓我繞遠路的,是沒有弄清楚一些更基礎的邊界:什麼需要持久化,什麼需要進入模型,哪些參數由程式決定,以及一項能力換了運行位置之後,會把哪些責任一起帶過去。

現在開始寫一個新功能,我會比以前多花一點時間追問這些問題。它們不一定能讓我第一次就做對,但能讓我少寫一些看起來已經完成、換個場景卻又要推倒的程式碼。

至於這次重寫,我最願意留下的成果,大概就是這些後來會繼續影響我怎麼寫程式碼的問題。