你不知道的 Agent：原理、架構與工程實踐

在寫完「你不知道的 Claude Code：架構、治理與工程實踐」之后，發現自己對 Agent 底層的理解還不夠深入。加上團隊在 Agent 方向已經有不少業務落地經驗，一直缺少一份系統梳理，所以我又把資料、開源實現和自己寫的代碼一起過了一遍，最后整理成了這篇文章。

這篇文章主要講 Agent 架構里幾塊最影響工程效果的內容，包括控制流、上下文工程、工具設計、記憶、多 Agent 組織、評測、追蹤和安全，最后再用 OpenClaw 的實現把這些設計原則串起來看一遍。

整理下來，有幾處判斷和我原來想的不太一樣。更貴的模型帶來的提升，很多時候沒有想象中那么大，反而 Harness 和驗證測試質量對成功率的影響更大，調試 Agent 行為時，也應優先檢查工具定義，因為多數工具選擇錯誤都出在描述不準確。另外，評測系統本身的問題，很多時候比 Agent 出問題更難發現。如果一直在 Agent 代碼上反復調，效果未必明顯，下面文章應該能給你這些問題答疑。

1. Agent Loop 的基本運轉方式

Agent Loop 的核心實現邏輯抽象后其實不到 20 行代碼：

對應的控制流如下，感知 -> 決策 -> 行動 -> 反饋四個階段不斷循環，直到模型返回純文本為止：

看過不少 Agent 實現和官方 SDK，結構都差不多。循環本身相當穩定，從最小實現一路擴展到支持子 Agent、上下文壓縮和 Skills 加載，主循環基本沒有變化，新增能力通常都是疊加在循環外部，而不是改動循環內部。

新能力基本只通過三種方式接入：擴展工具集和 handler、調整系統提示結構、把狀態外化到文件或數據庫。不應該讓循環體本身變成一個巨大的狀態機，模型負責推理，外部系統負責狀態和邊界，一旦這個分工確定下來，核心循環邏輯就很少需要頻繁調整了。

Workflow 和 Agent 有什么區別

Anthropic 對這兩類系統有一個直接區分：執行路徑由代碼預先寫死的是 Workflow，由 LLM 動態決定下一步的是 Agent，核心區別在于控制權掌握在誰手里。現實中很多標著 Agent 的產品，深入看其實更接近 Workflow，不過兩者本身并無高下之分，真正重要的是給任務找到更適合的解決方案。

放在一張圖里看，會更直觀：

五種常見控制模式

大多數 AI 系統拆開看，其實都是這五種模式的組合。很多場景并不需要完整的 Agent 自主權，把其中幾種模式搭起來就夠了，關鍵還是看任務本身適合哪一種設計。

上面這些模式解決的是控制流怎么搭，下面再看另一個更工程的問題，系統為什么能跑穩。

2. 為什么 Harness 比模型更關鍵

Harness 是指圍繞 Agent 構建的測試、驗證與約束基礎設施，這里的 Harness 至少包括四個部分：驗收基線、執行邊界、反饋信號和回退手段。

下面三個案例角度不同，但講的是同一件事。模型雖然重要，但決定系統能不能收斂的，往往是這些外圍工程條件。這個判斷在代碼編寫、編譯器實現這類高可驗證任務上最成立，但在開放式研究、多輪協商這類弱驗證任務里，模型上限本身仍然更關鍵。

OpenAI Codex 的做法

3 個工程師 5 個月寫了百萬行代碼，將近 1500 個 PR，是傳統開發速度的 10 倍。這個案例更值得看的是，這么快的產出背后，哪些工程約束在起作用：

這個案例里比較關鍵的一點是，他們并沒有把 Codex 僅僅當作代碼生成器來用，而是為它配套了一整套按任務臨時創建、任務完成后即銷毀的可觀測性棧，讓 Agent 可以直接利用日志、指標和追蹤來理解、驗證并修正系統行為，從而把代碼修改、運行驗證和結果反饋串成一個閉環。

上圖展示了這套可觀測性棧的完整數據流：應用產生的日志、指標和追蹤數據先匯集到可觀測性棧，再通過統一查詢接口暴露給 Codex。Codex 查詢這些數據進行分析、關聯和推理，生成代碼修改，應用修改后重啟服務并重新運行工作負載進行測試，測試結果再次進入可觀測性棧，形成循環。這個架構的關鍵在于 Agent 能主動查詢和理解系統狀態，而不是被動等待人工告知錯誤。

Anthropic 的 C 編譯器實驗

他們通過 16 個并行 Agent，運行約 2000 個 Claude Code 會話，花費約 $20,000 API 成本，在兩周內從零實現了一個可以編譯 Linux 6.9 的 C 編譯器。這個實驗的數據很突出，但從工程角度看，更值得關注的是它怎么處理回歸和收斂問題。

最終產出約 10 萬行 Rust 代碼，不僅能編譯 Linux Kernel，還能編譯 PostgreSQL、SQLite、Redis、FFmpeg、QEMU，并且通過了 99% 的 GCC torture test。

在接近 Opus 能力極限時，也遇到了一個非常真實的軟件工程問題，每完成一個新功能，常常連帶破壞若干已有功能，回歸很多，最后項目能穩定推進，主要依賴三個關鍵工程判斷：

Karpathy 的 Autoresearcher

Autoresearcher 是 Karpathy 做的一個實驗項目，讓 Agent 自主修改訓練腳本、跑實驗、評估改進是否有效，整個實現只有幾百行代碼，是理解 Agent Harness 設計的一個很好的例子。

圖里是 83 次實驗的結果。橫軸是實驗序號，縱軸是驗證集 BPB，越低越好。綠色圓點是保留的 15 個有效改進，灰色點是廢棄的嘗試。失敗是常態，但單次失敗成本很低，直接回滾就行。

Agent 能改的只有 train.py 這個文件，評估指標固定為 bits-per-byte，也就是 bpb，越低越好。每次實驗最多跑 5 分鐘，結果更好就 commit 作為新基準，結果變差就直接 revert。所有實驗結果記錄在 results.tsv 中，不進入 git 歷史。整個系統的控制平面是 program.md，相當于 Agent 的操作手冊，里面定義了工作流程、可修改的文件邊界、日志格式和崩潰恢復步驟，其中幾條設計很值得參考：

你的約束條件越清晰，Agent 的優化目標就越明確，加上搜索空間可控，我們就更容易在系統跑偏時把它及時拉回。

Harness 的關鍵結論是什么

這張圖用驗證難度和任務清晰度兩個維度劃分四個象限。右上角是最適合 Agent 發揮的區域，任務目標明確，結果也能自動驗證。左上角的問題是任務雖然清楚，但結果還要靠人審查，右下角的問題是雖然有自動化反饋，但目標不夠清楚，系統容易在錯誤方向上持續優化，左下角則同時缺少清晰目標和可靠驗證，Agent 基本無從發力。

Harness 設計的關鍵在于，只有自動化驗證和清晰的目標與參照標準同時具備，Agent 才能真正高效工作，只滿足其中一個條件都不夠。依賴人工驗證的狀態，效率和穩定性都有限，方向不清晰的狀態，也很難持續產出可靠結果。也就是說，無論任務起點更接近人工驗證，還是更接近方向模糊，最終都要被推進到同時具備清晰約束和自動化驗證的狀態，這才是 Harness 追求的理想工作區。

3. 上下文工程為什么決定穩定性

上下文工程的關鍵，不是窗口夠不夠長，而是放進去的東西是否真正相關，Transformer 的注意力復雜度是 O(n2)，上下文越長，關鍵信號越容易被噪聲稀釋。實踐里一個很常見的失效模式是無關內容一旦占到上下文的大頭，Agent 的決策質量就會明顯下滑，這類現象通常被叫作 Context Rot（上下文腐化）。很多看起來像模型能力不足的問題，往往可以追溯到上下文組織不當。

這里將圍繞這個四個點來講：上下文信息怎么分層，歷史信息怎么壓縮，知識如何按需加載，以及大體積信息怎么移出上下文。

上下文為什么要分層

上下文里的信息并不是平鋪的，而是應該按用途分層管理。下面這張圖概括了一種常見的結構：

這里和我寫的你不知道的 Claude Code 那篇文章里面的結論非常類似，上面這些層也對應一套信息分發機制：

別把確定性邏輯放進上下文，凡是可以通過 Hooks、代碼規則或工具約束表達的內容，都應交給外部系統處理，而不是讓模型反復讀取。

三種常見壓縮策略

1. 滑動窗口：丟棄舊消息，成本極低，會丟早期上下文，適合簡短對話 2. LLM 摘要：模型生成總結，成本中等，丟細節保留決策，適合長任務 3. 工具結果替換：占位符替換原始輸出，成本極低，適合工具調用密集型

壓縮的目標不是單純減少 token，而是在有限上下文預算內優先保留決策價值最高的信息，并把可重建內容移出上下文。

Prompt Caching 如何減少重復開銷

Anthropic API 支持對消息內容塊標記 cache_control: { type: "ephemeral" }。首次請求會建立緩存，之后 5 分鐘內，相同前綴的請求可以直接復用。被緩存部分的費用可下降約 90%，很適合系統提示較長、調用又頻繁的 Agent。是否命中緩存，可以通過 response.usage 里的 cache_read_input_tokens 和 cache_creation_input_tokens 來判斷。

為什么 Skills 要按需加載

Skills 是上下文工程里非常有效的一種模式，核心思路是：系統提示只保留索引，完整知識按需加載。

這種做法把領域知識從一次性預加載，改成索引加延遲加載，Claude 的生成式 UI 就采用了類似思路：先按需讀取設計規范的對應模塊，再調用渲染工具，而不是把整套設計系統一次性塞進上下文。Codex 團隊早期也嘗試過大而全的 AGENTS.md，后來改成 100 行以內的索引文件，再把細節拆到 docs/ 目錄按需引用，效果才好起來。

這里有兩個關鍵點，第一，Skill 描述要短，因為描述本身會常駐上下文，幾十個 token 的差異在高頻調用里會持續累積。第二，Skill 描述要寫成路由條件，而不是功能介紹。

壓縮最容易丟掉什么

壓縮階段最常見的問題，不是摘要不夠短，而是保留順序設錯了。LLM 通常會優先刪除那些看起來還可以重新獲取的信息，早期的 tool output 通常最先被移除，但與之相關的架構決策、約束理由和失敗路徑也很容易一并丟失。

文件系統為什么適合做上下文接口

只要 Agent 具備按需拉取信息的能力，初始上下文越克制，整體效果往往越穩定。Cursor 把這種方式稱為 Dynamic Context Discovery，核心不是預先提供盡可能多的信息，而是默認少給，只在需要時讀取。

4. 工具設計決定 Agent 能做什么

上下文決定模型能看到什么，工具決定模型能做什么，相比增加工具數量，工具定義的質量往往更重要。僅 5 個 MCP 服務器，就可能帶來約 55,000 tokens 的工具定義開銷，工具一旦過多，模型對單個工具的注意力也會被稀釋。

工具問題多數不在數量不夠，而在粒度不對、描述不清、返回太多、出錯后也修不回來，下面幾節基本都圍繞這幾個問題展開。

工具設計如何演進

工具設計大致經歷了三個階段，早期做法是直接把現有 API 封裝成工具扔給模型，后來發現模型選錯工具，問題不在模型能力，而在工具本身的設計視角就錯了，原來是給工程師設計的，不是給 Agent 設計的。

第一代，API 封裝：每個 API Endpoint 對應一個工具，粒度過細，Agent 往往需要協調多個工具才能完成一個目標。

第二代，ACI，即 Agent-Computer Interface：工具應對應 Agent 的目標，而不是底層 API 操作。不要分別暴露 create_file、write_content、set_permissions，而是直接給一個 create_script(path, content, executable)，一次搞定。

第三代，Advanced Tool Use：在工具設計之上，進一步優化工具的發現、調用和描述方式，主要包括三個方向：

ACI 工具設計有哪些原則

ACI 可以類比人機交互設計 HCI，工具設計對 Agent 的影響和界面設計對人的影響一樣直接，不能只看「工具能不能調用」，還要看「調用錯了之后能不能自己修回來」。

調試 Agent 時應先檢查工具定義，大多數工具選擇錯誤的原因出在描述不準確，不在模型能力。工具數量也要克制，能用 Shell 處理的、只需靜態知識的、更適合 Skill 的，都不需要新增工具。

5. 記憶系統如何設計

Agent 不具備原生的時間連續性，會話結束后，上下文隨之清空，下一次啟動時也不會自動保留此前狀態。要讓系統具備跨會話的一致性，記憶層得單獨設計，對 Agent 來說它是一層基礎設施，不是可以事后補上的能力。

四種記憶分別存在哪里

這里不是按存儲介質來分，而是按 Agent 實際要解決的問題來分：

把這四類記憶放到一張圖里看，會更容易理解它們的存儲位置和生命周期。左側是 Agent 運行時，只有上下文窗口存在于 messages[] 中，會隨著會話結束一起清空，右側是磁盤上的持久層，Skills 文件按需加載，JSONL 會話歷史保留完整過程并支持檢索，MEMORY.md 則沉淀 Agent 主動寫入的穩定事實，并在后續會話中持續注入。

MEMORY.md 和 Skills 如何協作

實際系統實現方式不同，但核心都在解決兩件事：重要事實要留下來，注入模型的內容又不能失控。下面兩個例子，一個偏產品形態，一個偏工程形態。

ChatGPT 四層記憶：1. Session Metadata：設備、地點、使用模式，不持久化 2. User Memory：約 33 條關鍵偏好事實，持久化，每次注入 3. Conversation Summary：約 15 個最近對話的輕量摘要，持久化 4. Current Session：當前對話滑動窗口，不持久化

OpenClaw 混合檢索：1. memory/YYYY-MM-DD.md，追加寫日志，保留原始細節 2. MEMORY.md，精選事實，Agent 主動維護 3. memory_search，70% 向量相似度 + 30% 關鍵詞權重的混合檢索

記憶整合如何觸發并回退

有了記憶分層之后，下一步要處理的就不是「要不要存」，而是「什么時候整合，以及整合失敗怎么辦」。

所以這里最關鍵的不是摘要寫得多漂亮，而是流程本身必須可回退。整合本質上是壓縮，不是覆蓋，系統只移動指針，不刪除原始消息，即使整合失敗，也還能回到原始存檔繼續工作。

6. 自主度應該如何逐步放開

這里說的自主度，不是少幾次人工確認，而是讓 Agent 能在更長時間跨度內穩定推進任務，前提也不是直接放權，而是先補齊三類基礎設施：跨 session 續跑、單個 session 內的進度約束，以及慢速 I/O 的后臺接入。

長任務如何跨 session 繼續

長任務最常見的失敗，不是單步報錯，而是 session 結束時任務還沒做完。即使啟用 compaction，也擋不住兩類問題：一是在單個 session 里試圖做完整個應用，結果上下文先耗盡，二是只做完一部分，下一輪又無法準確恢復現場，過早判斷完成。

這里的關鍵在于，Initializer Agent 只跑一次，職責是把任務外化成文件系統狀態，Coding Agent 可重入，每個 session 只推進一個功能，狀態通過 claude-progress.txt 和 git 記錄傳遞，不依賴上一輪對話上下文。真正跨 session 傳遞狀態的，不是上下文窗口，而是文件系統里的進度文件和 git 記錄，只要這些狀態還在，某一輪中斷、崩潰或上下文耗盡，后續 session 就能繼續，不需要重頭再來。

為什么任務狀態要顯式寫出來

跨 session 解決的是「下次從哪里繼續」，單個 session 內還要解決「當前做到哪一步」。長任務一旦拉長，沒有外部進度錨點，Agent 很容易偏航，或者在還有任務未完成時過早結束。

后臺 I/O 如何接入

自主度提高以后，真正容易拖慢主循環的，通常不是模型推理，而是文件操作、網絡請求和長耗時命令這類外部 I/O。這些操作一旦阻塞主循環，執行節奏就會明顯變差。

7. 多 Agent 應該如何組織

一說到多 Agent，不少同學先想到的就是并行，但工程上先要解決的其實是隔離和協作，這里對應的是兩種完全不同的工作模式。

常見的組織方式是主 Agent 作為 Orchestrator 統籌全局，下掛多個子 Agent 獨立并行工作。它們之間通過 JSONL inbox 協議通信，用 Worktree 隔離文件修改，用任務圖管理依賴關系。

子 Agent 適合做什么

子任務里的搜索、試錯和調試過程，不該污染主 Agent 的上下文。主 Agent 真正需要的只是結論，探索細節留在子 Agent 自己的消息歷史里。

為什么協作方式要寫成協議

多 Agent 協作一旦靠自然語言來對齊，很快就會出問題。模型記不穩誰承諾了什么，也記不穩誰在等誰的結果，任務開始互相依賴之后，就得先把協議寫清楚：

多 Agent 下幻覺會互相放大

多個 Agent 頻繁互動時，錯誤也會被一層層放大。Agent A 先帶偏，Agent B 跟著強化，Agent C 再繼續疊加，最后所有 Agent 都收斂到同一個高置信度的錯誤結論。交叉驗證的價值就在這里，它能打斷這條鏈，讓某個 Agent 獨立判斷，而不是順著前面的結論繼續走。

8. Agent 評測應該如何做

Agent 做得對不對，最終要靠評測來判斷，很多團隊會把這一步往后放，結果就是改了 Prompt，不知道是否變好，換了模型，也不知道是否退化，最后只剩下一組無法解釋的波動數字。評測的核心是測試用例、評分標準和自動驗證，真正的難點不是有沒有分數，而是這些分數能不能反映真實質量。

這張圖里真正需要記住的，其實就三組概念。第一組是 task、trial、grader，分別對應測什么、跑多少次、怎么打分。第二組是 transcript 和 outcome，前者是完整執行記錄，后者是環境里的最終結果，評測不能只看其中一邊。第三組是 agent harness 和 evaluation harness，前者是被評測的 Agent 運行框架，后者是負責把任務跑起來、打分、匯總結果的評測基礎設施。

三類評分器的區別

評測是否可靠，首先取決于評分器選得對不對，三種主要類型之間，確定性和覆蓋范圍通常呈反向關系： 1. 代碼評分器：字符串匹配、單測、結構比對，確定性最高，適合有明確答案的任務 2. 模型評分器：rubric 打分、pairwise 比較、多 judge 共識，確定性中等，適合語義質量評估 3. 人工評分器：專家抽樣審查、標注校準，可靠但慢，適合建立基準

先修評測，再改 Agent

一個常見誤區是，看到 Agent 表現下降，就立刻著手修改 Agent 本身，而忽略了評測系統可能先出了問題。評測環境給的資源越緊，比如算力、時間預算或環境限制越嚴，成功率通常越低，基礎設施錯誤率也越高，這和模型能力完全無關，但在評測結果里會被直接誤讀為 Agent 退化。

9. 如何追蹤 Agent 的執行過程

先把 Trace 能力搭起來，沒有完整記錄，失敗案例就沒法穩定復現。Agent 出現問題時，傳統只監控延遲和錯誤率的 APM 往往幫助有限，接口層看起來可能一切正常，但真正的問題出在模型某一輪做出了錯誤決策，只有回看完整 Trace 才能定位。

事件流為什么更適合做底座

把 Agent 的執行步驟發布成事件流之后，可觀測性才真正有了底座。

10. 用 OpenClaw 看 Agent 如何落地

前面幾節講的是 Agent 的控制流、上下文、工具、記憶、評測和安全，這一節換成 OpenClaw，看看這些設計在系統里是怎么落下去的。上下文分層、Skills 延遲加載、結構化通信協議、文件系統狀態，在 OpenClaw 里都能找到對應實現，后面就拿這個實現一層層往下看。

整體架構：四層解耦

OpenClaw 可以看成四層，分別解決渠道接入、消息解耦、Agent 調度和工具執行。最上面是負責連接和消息分發的 WebSocket 服務，底部是 SOUL.md、MEMORY.md、Skills 等配置文件，下面這張表把各層職責和關鍵設計放在一起看會更清楚。

系統提示如何按層疊加

OpenClaw 的系統提示可以從 SOUL.md 看起，這個文件定義了 Agent 是誰、按什么方式做事、什么情況下算完成。

為什么安全邊界要先于功能

開放 Shell 權限之后，git push、rm、數據庫寫入這類操作都可能被觸發，安全邊界要先于功能。三件事必須先到位：誰能用、能在哪用、做了什么可以追蹤。

11. Agent 落地里的常見反模式

這類問題都很常見，很多看起來像模型能力不夠，回頭看其實是工程約束沒立住：

1. 系統提示當知識庫：越來越長，關鍵規則被忽略，約定留提示，知識移 Skills

2. 工具數量失控：Agent 頻繁選錯工具，合并重疊工具，明確命名空間

3. 驗證閉環缺失：Agent 說完成了但沒法驗證，每類任務綁驗收標準

4. 多 Agent 無邊界：狀態漂移，故障歸因困難，明確角色權限，worktree 隔離

5. 記憶不整合：長對話第 20 輪后決策質量下降，監控 token，超閾值自動觸發

6. 沒有評測：改了一個地方不知道有沒有引入回歸，失敗案例立刻轉測試用例

7. 過早引入多 Agent：協調開銷超過并行收益，先驗證單 Agent 上限再擴展

8. 約束靠期望不靠機制：規則在文檔里 Agent 選擇性遵守，改用工具驗證 / Linter / Hook

12. 收尾一下

前面幾節其實都在講同一件事，Agent 能不能穩定，不只看模型，也看 Harness。上下文管理、工具邊界、記憶整合、評測、可觀測性和安全邊界，單拆出來都不難，難的是把它們一起做對。

多 Agent 也一樣，先解決隔離，再談并行。評測也一樣，先保證評測可信，再去改 Agent。很多問題表面上像模型不夠強，實際是任務沒定義清楚，驗收標準沒立住，或者系統邊界沒收好。現階段最值得投入的，還是把驗證、上下文、工具和評測這些基礎工程打牢。如果大家有更多 Agent 開發上的經驗和技巧，也歡迎一起交流。

原文鏈接：https://x.com/HiTw93/status/2034627967926825175