AI 智能體的上下文工程企業(yè)級落地實踐 原創(chuàng) 精華
大家好，我是玄姐。
在 Manus 項目啟動之初，團隊面臨一個關鍵抉擇：是基于開源基礎模型訓練端到端的智能體，還是借助前沿模型的核心能力搭建 AI 智能體？回溯 NLP 生涯前十年，我們根本沒有這樣的選擇余地。在七年前的 BERT 時代，模型必須經過繁瑣的微調與評估，才能遷移到新任務中，即便這些模型相較于如今的 LLM 體積小巧，每次迭代仍需耗費數(shù)周時間。對于亟待快速迭代的應用而言，尤其是在尚未實現(xiàn)產品市場匹配（PMF）的階段，這種緩慢的反饋循環(huán)堪稱致命缺陷。這是上一個創(chuàng)業(yè)項目的慘痛教訓：當時我們從零開始訓練模型，用于開放信息提取與語義搜索，可 GPT-3 與 Flan-T5 的橫空出世，讓我們的自研模型一夜之間淪為雞肋。頗具諷刺意味的是，正是這些模型開啟了上下文學習的全新賽道，指明了截然不同的前進方向。
這段來之不易的經歷讓決策變得清晰：Manus 果斷押注上下文工程。這一選擇不僅讓我們的產品改進周期從數(shù)周壓縮至數(shù)小時，更讓產品與底層模型保持了靈活的適配性，若將模型進步比作上漲的潮水，我們希望 Manus 是順勢航行的船，而非固定在海床的柱。
然而，上下文工程絕非易事，它更像是一門實驗科學。我們先后四次重構智能體框架，每一次都是在探索出更優(yōu)的上下文塑造方式后推倒重來。我們戲稱這種手動調整架構、優(yōu)化提示詞與反復試錯的過程為 “隨機研究生下降”（SGD），雖不優(yōu)雅，卻行之有效。本文將分享我們通過這套 “SGD” 方法摸索出的實踐心得，希望能幫助正在構建 AI 智能體的開發(fā)者少走彎路，更快找到最優(yōu)解。
一、圍繞 KV 緩存設計：把控核心性能指標
若要挑選一個生產環(huán)境中 AI 智能體的關鍵指標，我認為 KV 緩存命中率當之無愧，它直接決定了系統(tǒng)的響應延遲與運營成本。要理解其重要性，首先需明確 AI 智能體的工作邏輯：
接收用戶輸入后，智能體會通過一系列工具調用鏈推進任務。每一輪迭代中，模型會根據(jù)當前上下文，從預定義的動作空間中選擇合適動作，在環(huán)境（例如：Manus 的虛擬機沙盒）中執(zhí)行后產生觀察結果，而動作與觀察結果會持續(xù)追加到上下文，作為下一輪迭代的輸入。這個循環(huán)會一直持續(xù)到任務完成。
不難想象，隨著迭代推進，上下文會不斷膨脹，但輸出（通常是結構化的函數(shù)調用）卻相對簡短。這使得智能體的輸入與輸出 token 比例嚴重傾斜，以 Manus 為例，平均比例約為 100:1。幸運的是，擁有相同前綴的上下文可借助 KV 緩存技術，大幅降低首個 token 生成時間（TTFT）與推理成本，無論你使用自托管模型還是調用推理 API，節(jié)省效果都十分顯著：以 Claude Sonnet 為例，緩存后的輸入 token 成本僅為 0.30 美元 / 百萬 token，未緩存則高達 3 美元 / 百萬 token，差距達 10 倍。
從上下文工程角度，提升 KV 緩存命中率需遵循三大核心實踐：
- 保持提示詞前綴穩(wěn)定：LLM 的自回歸特性決定了，哪怕單個 token 的差異，都會導致該 token 后的緩存失效。常見誤區(qū)是在系統(tǒng)提示詞開頭加入精確到秒的時間戳，雖能讓模型獲取當前時間，卻會嚴重拉低緩存命中率；
- 采用 “只追加” 式上下文：避免修改歷史動作或觀察結果，同時確保序列化過程的確定性，許多編程語言和庫在序列化 JSON 時不保證鍵順序穩(wěn)定，這可能會隱性破壞緩存；
- 明確標記緩存斷點：部分模型提供商或推理框架不支持自動增量前綴緩存，需手動在上下文中插入斷點。設置斷點時需考慮緩存過期問題，且至少要包含系統(tǒng)提示詞的結尾部分。
# 系統(tǒng)提示詞（固定不變的基礎規(guī)則+結構化工具定義）
你是一個數(shù)據(jù)分析智能體，只能使用以下工具處理數(shù)據(jù)：
1. 數(shù)據(jù)導入工具：導入指定數(shù)據(jù)表，參數(shù)：table_name（必填）、time_range（可選）；
2. 篩選工具：篩選數(shù)據(jù)維度，參數(shù)：region（可選）、date（可選）；
3. 計算工具：計算統(tǒng)計指標，參數(shù)：indicator（必填，支持同比增長率/環(huán)比增長率）。
處理步驟：1. 解析用戶需求；2. 選擇工具；3. 執(zhí)行并返回結果。
## 第1輪對話
用戶需求：分析2025年Q3的銷售數(shù)據(jù)；
代理動作：調用“數(shù)據(jù)導入工具”，參數(shù)：{"table_name": "2025Q3_sales", "time_range": "2025-07-01至2025-09-30"}；
執(zhí)行結果：成功導入2025年Q3銷售數(shù)據(jù)表，包含全國各地區(qū)銷售額、客單價等字段，共1200條數(shù)據(jù)。
## 第2輪對話
用戶補充需求：只看華東地區(qū)的數(shù)據(jù)，先篩選再計算；
代理動作：調用“篩選工具”，參數(shù)：{"region": "華東地區(qū)"}；
執(zhí)行結果：成功篩選出華東地區(qū)Q3銷售數(shù)據(jù)，共320條，涉及上海、江蘇、浙江、安徽4個省份。
# 固定引導語（穩(wěn)定前綴，避免系統(tǒng)提示微調導致緩存失效）
以下是當前任務的動態(tài)上下文：
<!-- CACHE_BREAKPOINT --> # 緩存斷點（固定位置，始終在系統(tǒng)提示+引導語之后）
# 斷點之后：動態(tài)上下文（順序追加）
# 最新待處理需求（第3輪要執(zhí)行的新內容）
用戶需求：計算華東地區(qū)Q3銷售額同比增長率；此外，若使用 vLLM 等框架自托管模型，需確保啟用前綴 / 提示詞緩存，并通過會話 ID 等技術，在分布式工作節(jié)點間實現(xiàn)請求的一致路由。
二、遮蔽而非移除：穩(wěn)定動作空間
隨著智能體能力增強，其動作空間會自然變得復雜，本質上是工具數(shù)量的爆炸式增長，而近期流行的 MCP（多工具組合平臺）更讓這一問題雪上加霜。若允許用戶自定義工具，必然會出現(xiàn)數(shù)百個功能不明的工具被插入到精心設計的動作空間中的情況，導致模型更易選擇錯誤動作或低效路徑，讓 “武裝過度” 的智能體反而變得 “愚蠢”。
面對這一問題，常見思路是設計動態(tài)動作空間，比如采用類似 RAG 的方法按需加載工具。在 Manus 中也曾嘗試過這種方案，但實驗結果明確了一條規(guī)則：除非絕對必要，否則避免在迭代過程中動態(tài)添加或移除工具。原因有二：
- 大多數(shù) LLM 中，工具定義序列化后會位于上下文前部（通常在系統(tǒng)提示詞前后），任何修改都會導致后續(xù)所有動作和觀察結果的 KV 緩存失效；
- 若歷史動作與觀察結果仍引用當前上下文已移除的工具，模型會陷入困惑，在無約束解碼的情況下，極易出現(xiàn)模式違規(guī)或幻覺動作。
為解決這一問題并優(yōu)化動作選擇，Manus 采用上下文感知的狀態(tài)機管理工具可用性：不直接移除工具，而是在解碼過程中掩蔽 token 的 logits，基于當前上下文阻止或強制選擇特定動作。
在實踐中，多數(shù)模型提供商與推理框架支持響應預填充功能，可在不修改工具定義的前提下約束動作空間。函數(shù)調用通常包含三種模式（以 NousResearch 的 Hermes 格式為例）：
- 自動模式：模型可自主選擇是否調用函數(shù)，僅需預填充回復前綴：?
?<<|im_start|>assistant??； - 必需模式：模型必須調用函數(shù)，選擇不受約束，預填充至工具調用令牌：?
?<<|im_start|>assistant<tool_call>??； - 指定模式：模型需從特定工具子集選擇調用，預填充至函數(shù)名稱開頭：?
?<<|im_start|>assistant<tool_call>{"name": "browser_??。
我們一起看個電商客服智能體的案例如下：
假設你在做一個「電商客服 AI 智能體」，需要用到這些工具：
- 瀏覽器工具（?
?browser_查詢訂單???、??browser_查詢物流??） - 命令行工具（?
?shell_修改地址???、??shell_發(fā)起退款??） - 表單工具（?
?form_收集售后信息??）總共 5 個工具，全部寫在系統(tǒng)提示里，不會刪除。
現(xiàn)在遇到兩個核心問題：
- 用戶剛發(fā)消息 “查一下我的訂單”，此時 AI 應該只調用瀏覽器工具，不能選退款、收集信息工具；
- 后續(xù)用戶說 “想退款”，AI 應該只能選退款和查詢訂單工具（查訂單確認信息后才能退款），不能選物流查詢、修改地址工具。
按 “動態(tài)移除工具” 和 “遮蔽工具” 兩種方式對比，就能明白區(qū)別：
第一、先看「動態(tài)移除工具」的坑（為什么不能這么做）
如果用 “動態(tài)移除” 思路，處理用戶 “查訂單” 需求時，會把系統(tǒng)提示里的 ??shell_修改地址???、??shell_發(fā)起退款???、??form_收集售后信息?? 這 3 個工具刪掉，只留瀏覽器工具。
- 坑 1：工具定義在上下文前部，刪除后，后面的歷史對話（比如之前用戶問過物流）的 KV 緩存全失效，下一輪請求要重新計算，延遲變高；
- 坑 2：如果歷史對話里提到過 “退款”（比如用戶之前問過 “能退款嗎”），現(xiàn)在工具里沒了?
?shell_發(fā)起退款??，AI 會困惑：“之前說的退款工具去哪了？” 可能亂選工具或胡言亂語。
第二、再看「遮蔽工具」的正確操作（一步步實操）
我們不刪除任何工具，而是通過「預填充回復前綴」+「工具統(tǒng)一前綴」，讓 AI “看不見” 不該選的工具（即遮蔽），具體分 3 種情況：
情況 1：用戶剛發(fā)消息，AI 需先回復確認（自動模式）
用戶輸入：“在嗎？我想查訂單”此時 AI 不能直接調用工具，得先回應用戶，再問訂單號 —— 用「自動模式」遮蔽所有工具調用：
- 預填充回復前綴：?
?<<|im_start|>assistant?? - 效果：AI 只能輸出自然語言回復（比如 “你好呀！請告訴我你的訂單號，我?guī)湍悴樵儭保?，沒法調用任何工具（因為沒觸發(fā)?
?tool_call??令牌，工具相關的 token 被遮蔽了）。
情況 2：用戶提供訂單號，AI 必須調用工具（必需模式）
用戶補充：“訂單號是 123456”此時 AI 必須調用工具，不能再閑聊 —— 用「必需模式」遮蔽 “自然語言回復”，只允許調用工具：
- 預填充回復前綴：?
?<<|im_start|>assistant<tool_call>?? - 效果：AI 只能輸出工具調用格式（比如?
?{"name": "browser_查詢訂單", "parameters": {"order_id": "123456"}}??），沒法說廢話，且能選所有工具（但我們下一步會進一步限制）。
情況 3：用戶查訂單，AI 只能選瀏覽器工具（指定模式）
接著上面的場景，AI 必須調用 “查詢訂單” 工具，不能選退款、修改地址 —— 用「指定模式」遮蔽其他工具，只允許選瀏覽器工具：
- 預填充回復前綴：?
?<<|im_start|>assistant<tool_call>{"name": "browser_?? - 效果：AI 只能在 “browser_” 開頭的工具里選（即?
?browser_查詢訂單???、??browser_查詢物流???），沒法選??shell_???或??form_???開頭的工具（這些工具的 token 被遮蔽了，AI “看不見”）。最終 AI 會輸出：??<<|im_start|>assistant<tool_call>{"name": "browser_查詢訂單", "parameters": {"order_id": "123456"}}??
情況 4：用戶后續(xù)說 “想退款”（切換指定模式）
用戶輸入：“訂單查到了，我想退款”此時 AI 只能選??shell_發(fā)起退款???和??browser_查詢訂單??（查訂單確認狀態(tài)）—— 用「指定模式」+「工具前綴」：
- 預填充回復前綴：?
?<<|im_start|>assistant<tool_call>{"name": "?? - 同時利用工具統(tǒng)一前綴：告訴 AI“只能選 browser_或 shell_開頭的工具，且優(yōu)先 shell_發(fā)起退款”（不用刪工具，只是遮蔽其他前綴的工具）。
- 效果：AI 只能選?
?browser_查詢訂單???（二次確認）或??shell_發(fā)起退款???，不會選??form_收集售后信息??這類無關工具。
#舉個 System Prompt 的實際寫法（電商客服場景）
你是電商客服AI智能體，需遵循以下模式規(guī)則：
1. 模式類型及觸發(fā)條件：
- 自動模式：用戶剛發(fā)起對話、需求模糊（無具體參數(shù)）、咨詢規(guī)則時，可自主選擇自然語言回復或調用工具，回復開頭無強制前綴，僅需符合對話邏輯；
- 必需模式：用戶提供明確參數(shù)（如訂單號、地址）、需要查實時數(shù)據(jù)（物流/訂單）或執(zhí)行操作（退款/改地址）時，必須調用工具，不能閑聊，回復開頭必須是<tool_call>{"name": "；
- 指定模式：用戶需求明確指向某類工具（如“查訂單”“退款”）時，必須調用對應前綴的工具（查訂單→browser_開頭，退款→shell_開頭），回復開頭必須是<tool_call>{"name": "工具前綴"（如browser_、shell_）；
2. 工具列表（永久保留，不刪除）：
- browser_查詢訂單（參數(shù)：order_id）、browser_查詢物流（參數(shù)：order_id）；
- shell_修改地址（參數(shù)：order_id、new_address）、shell_發(fā)起退款（參數(shù)：order_id、reason）；
- form_收集售后信息（參數(shù)：problem、contact）；
3. 輸出要求：嚴格按當前模式的預填充開頭續(xù)寫，不偏離格式，不調用無關工具。通過這種方式，我們可直接通過掩碼 token 的 logits 約束動作選擇。例如，當用戶提供新輸入時，Manus 需立即回復而非執(zhí)行動作。同時，我們?yōu)橥惞ぞ咴O計了統(tǒng)一前綴（如瀏覽器工具以??browser_???開頭，命令行工具以??shell_??開頭），無需依賴有狀態(tài)的 logits 處理器，即可輕松確保智能體在特定狀態(tài)下僅從指定工具組中選擇，保障智能體循環(huán)的穩(wěn)定性。
三、以文件系統(tǒng)為上下文：突破窗口限制
現(xiàn)代前沿 LLM 的上下文窗口已擴展至 128K 令牌甚至更高，但在真實的代理應用場景中，這一容量仍顯不足，有時甚至會成為負擔，主要存在三大痛點：
- 觀察結果可能異常龐大，尤其是代理與網頁、PDF 等非結構化數(shù)據(jù)交互時，極易超出上下文限制；
- 超過一定上下文長度后，即便模型技術上支持該窗口大小，性能也會明顯下降；
- 長輸入的傳輸與預填充成本高昂，即便使用前綴緩存，仍需為每個 token 付費。
為解決這一問題，許多代理系統(tǒng)采用上下文截斷或壓縮策略，但過度激進的壓縮必然導致信息丟失。從邏輯層面看，代理需基于所有歷史狀態(tài)預測下一個動作，而我們無法預判哪些觀察結果會在后續(xù)步驟中發(fā)揮關鍵作用，因此任何不可逆的壓縮都存在風險。
正是基于這一考量，Manus 將文件系統(tǒng)視為 “終極上下文”—— 它不僅容量無限制、天然支持持久化，還能被代理直接操作。模型會學會按需讀寫文件，將文件系統(tǒng)既作為存儲介質，也作為結構化的外部記憶。我們的壓縮策略始終遵循 “可恢復性” 原則：例如，移除網頁內容時保留 URL，省略文檔內容時保留沙盒中的文件路徑，確保在縮短上下文長度的同時，不永久丟失關鍵信息。
在開發(fā)這一功能時，我不禁思考狀態(tài)空間模型（SSM）在智能體環(huán)境中的應用潛力。與 Transformer 不同，SSM 缺乏完整的注意力機制，處理長距離后向依賴的能力較弱，但如果能讓它們掌握基于文件的記憶方式 —— 將長期狀態(tài)外部化而非存儲在上下文中，其速度與效率優(yōu)勢或許能催生出全新類型的智能體，成為神經圖靈機的真正繼任者。
四、通過復述操控注意力：錨定核心目標
Manus 處理復雜任務時，平均需要約 50 次工具調用。如此長的循環(huán)中，依賴 LLM 做決策的智能體極易偏離主題，或忘記早期設定的目標，尤其是在長上下文或復雜任務場景中，“丟失在中間” 的問題尤為突出。
對此，我們設計了一種刻意的注意力操控機制：Manus 會創(chuàng)建??todo.md??文件，在任務推進過程中持續(xù)更新，通過反復重寫待辦事項列表，將目標 “復述” 到上下文末尾。這一操作能將全局計劃納入模型的近期注意力范圍，有效避免目標偏移，減少行動與目標的不一致性。本質上，這是通過自然語言引導模型注意力偏向核心任務，無需對模型架構做任何特殊修改，卻能顯著提升任務完成度。
五、保留錯誤內容：助力自主迭代優(yōu)化
智能體犯錯是不可避免的現(xiàn)實，語言模型會產生幻覺、環(huán)境會返回錯誤、外部工具可能出現(xiàn)異常，意外的邊緣情況隨時可能發(fā)生。在多步驟任務中，失敗不是例外，而是循環(huán)的一部分。
面對錯誤，許多團隊的本能反應是 “掩蓋痕跡”：清理錯誤記錄、重試操作，或重置模型狀態(tài)，寄希望于通過調整 “溫度” 參數(shù)解決問題。這種做法看似更安全可控，卻存在隱性代價：擦除失敗痕跡意味著模型失去了學習的依據(jù)，沒有這些證據(jù)，模型無法調整自身行為，自然難以避免重復犯錯。
根據(jù)我們的實踐經驗，改善智能體行為的有效方法出奇地簡單：將錯誤嘗試完整保留在上下文中。當模型看到失敗的動作、對應的觀察結果或堆棧跟蹤時，會隱性更新內部信念，調整決策先驗，從而降低重復犯錯的概率。事實上，我們認為錯誤恢復能力是真正代理行為的核心標志之一，但這一點在當前多數(shù)學術研究與公共基準測試中仍未得到充分關注， 它們往往更側重理想條件下的任務成功率。
六、打破少樣本局限：注入受控隨機性
少樣本提示是提升 LLM 輸出一致性的常用技術，但在代理系統(tǒng)中，它可能會以微妙的方式適得其反。語言模型本質上是優(yōu)秀的模仿者，會復刻上下文的行為模式。如果上下文充斥著重復的行動 - 觀察對，模型會傾向于沿用該模式，即便它已不再是最優(yōu)選擇。
這一問題在涉及重復決策或動作的任務中尤為危險。例如，使用 Manus 審查 20 份簡歷時，智能體可能會陷入固定節(jié)奏，僅僅因為上下文呈現(xiàn)的都是類似行動，就機械重復相同操作，最終導致目標偏離、過度泛化甚至產生幻覺。
解決這一問題的關鍵在于增加多樣性。Manus 會在行動與觀察的呈現(xiàn)中，引入少量結構化變化，比如采用不同的序列化模板、替代性措辭，或在順序、格式上加入微小 “噪音”。這種受控的隨機性能有效打破固有模式，調整模型注意力，避免智能體陷入少樣本學習的窠臼。換句話說，上下文的單一性會導致智能體的脆弱性，適度的變化才能提升系統(tǒng)的魯棒性。
七、結語
上下文工程雖仍是一門新興科學，卻已成為 AI 智能體開發(fā)的核心支柱。無論底層模型如何迭代升級，變得更強大、更快速、更經濟，都無法替代對記憶管理、環(huán)境交互與反饋機制的優(yōu)化，如何塑造上下文，最終決定了智能體的運行速度、恢復能力與擴展邊界。
這些經驗源于 Manus 團隊的反復試錯、無數(shù)次彎路，以及面向數(shù)百萬用戶的實戰(zhàn)檢驗。我們分享的并非放之四海而皆準的真理，而是經過實踐驗證的有效模式。如果這些內容能幫助你避免哪怕一次痛苦的迭代，這篇文章便實現(xiàn)了它的價值。
智能體的未來，正在于每一個精心設計的上下文。愿你能在實踐中不斷探索，構建出更強大的智能系統(tǒng)。
好了，這就是我今天想分享的內容。
本文轉載自??玄姐聊AGI?? 作者：玄姐
