從單智能體到多智能體協同：LangChain 官方聊天機器人架構升級 原創 精華
大家好，我是玄姐。
一、背景
任何成功的平臺都需要可靠的技術支持，但我們發現，團隊成員每天要花數小時查找技術問題的答案。這種低效不僅拖慢了工程師的工作進度，也成為了用戶使用過程中的關鍵瓶頸。
LangChain 官方決定用自己推崇的工具解決這個問題：LangChain、LangGraph 和 LangSmith。最初，將 chat.langchain.com 作為原型開發，明確設定了兩大功能：
- 產品問答：幫助用戶和內部團隊快速獲取權威的產品相關答案。
- 客戶原型示例：作為實操案例，向客戶展示如何利用 LangChain 技術棧構建復雜且可靠的智能體。
LangChain 官方的初衷很明確，產品也能正常運行，但有個問題不得不承認：支持工程師們并沒有主動使用這款 LangChain 聊天機器人。而這，正是真正開始學習和改進的起點。
接下來，就為大家分享如何優化自家智能體，以及在構建真正可靠、可投入生產且能讓客戶靈活適配的應用方面，獲得的關鍵經驗。
工程師們不常用這款聊天機器人，并非因為它功能故障，也不是不認可它的價值。而是當有人問 “為什么流式傳輸在生產環境中無法正常工作？” 這類問題時，僅靠文檔作為信息來源是遠遠不夠的，大家都知道，文檔永遠存在信息缺口。
所以他們摸索出了自己的工作流程：
- 查閱官方文檔（docs.langchain.com），了解該功能的設計用途。
- 查看知識庫（support.langchain.com），確認是否有其他用戶遇到過相同問題及解決方案。
- 打開 Claude Code，搜索實際代碼實現，驗證代碼的真實運行邏輯。
文檔提供官方說明，知識庫記錄實際問題案例，代碼庫則是最核心的事實依據。
二、決定將這套流程自動化
這套三步流程的效果非常好。觀察到工程師們每天要重復幾十次，于是想到：如果能把這套流程直接自動化，會怎么樣？
為此，開發了內部工具 “深度智能體”（Deep Agent），這是一個用于構建復雜多步驟任務智能體的庫，包含三個專業子智能體，分別負責文檔搜索、知識庫查詢和代碼庫檢索。每個子智能體都會主動提出跟進問題、篩選結果，再將關鍵信息傳遞給主協調智能體。
主智能體整合所有信息后，會給出這樣的答案示例：
“要實現子圖流式傳輸，需根據 LangGraph 流式傳輸文檔，在流式配置中設置 subgraphs: true。
有一篇標題為《為何升級后逐 token 流式傳輸失效？》（https://support.langchain.com/articles/7150806184-Why-is-token-by-token-streaming-not-working-after-upgrading-LangGraph?）的支持文章，專門解釋了這個問題，你需要啟用子圖流式傳輸，才能從嵌套智能體中獲取逐 token 更新。相關實現位于 pregel/main.py 文件的 3373-3279 行，其中 subgraphs 參數控制是否將嵌套圖的輸出包含在流式傳輸結果中。”
工程師們對這個工具贊不絕口。
它每周能為工程師節省數小時的復雜調試時間。只需描述生產環境中遇到的問題，就能收到全面的答案，不僅引用了文檔、參考了已知解決方案，還能精準指向關鍵代碼行。
三、新發現
隨后有人提出了一個很關鍵的問題：既然這個工具在內部用著這么好，為什么面向公眾的 Chat LangChain 不采用同樣的設計？
這是個合理的疑問。之前的公共工具采用的是傳統方式：將文檔分割成片段、生成嵌入向量、存儲到向量數據庫中。文檔更新時，我們必須不斷重新索引。用戶雖然能得到答案，但引用信息不夠清晰，上下文也很零散。
我們無意間通過復刻實際工作流程，打造了更優的內部工具?，F在，是時候將這套方案應用到公共產品中了。
重構之初，很快意識到，需要結合兩種不同的架構來應對兩大類問題：大部分問題可通過文檔和知識庫解決，其余復雜問題則需要深入分析代碼核心。
四、新智能體的構建方案
4.1 針對簡單文檔查詢：使用 Create Agent
我們選擇 LangChain 中的智能體抽象工具 Create Agent 作為 chat.langchain.com 的默認模式，因為它能保證響應速度。
這種模式無需規劃階段，也沒有協調開銷，直接調用工具并返回答案。智能體會先搜索文檔，必要時查詢知識庫，若結果不明確則優化查詢語句，最終給出回復。大多數文檔類問題只需 3-6 次工具調用，Create Agent 能在幾秒內完成這些操作。
4.1.1 模型選擇
我們為用戶提供了多種模型選項，Claude Haiku 4.5、GPT-4o Mini 和 GPT-4o-nano。實踐發現，Claude Haiku 4.5 在工具調用方面速度極快，同時還能保持較高的準確性。Create Agent 與 Claude Haiku 4.5 搭配使用，大多數查詢能在 15 秒內得到響應，完全滿足文檔問答的需求。
4.1.2 優化方式
我們利用 LangSmith 追蹤每一次對話，找出智能體進行不必要工具調用的場景，并優化提示詞。數據顯示，只要教會智能體提出更精準的跟進問題，大多數問題只需 3-6 次工具調用就能解決。LangSmith 的評估套件還支持我們對不同提示策略進行 A/B 測試，同時衡量速度和準確性的提升效果。
示例追蹤：某次 30 秒的對話追蹤包含 7 次工具調用：4 次文檔搜索、1 次知識庫文章查詢和 2 次文章讀取，其中 20 秒用于流式傳輸最終響應。
輸入：{'query':' 元數據上下文工程 ', 'page_size': 5}
4.2 針對需代碼分析的復雜查詢：帶子圖的深度智能體
很多問題除了需要參考文檔、知識庫和已知問題外，還得深入代碼庫驗證實現細節。
4.2.1 架構設計
針對這類任務，我們構建了帶有專業子圖的深度智能體（Deep Agent）：一個負責文檔搜索，一個負責知識庫查詢，還有一個專門處理代碼庫檢索。
每個子智能體獨立運作，通過提出跟進問題、篩選信息，只提取最相關的核心內容，再傳遞給主協調智能體。這樣既避免了主智能體被海量上下文淹沒，又能讓每個領域的 “專家” 深入挖掘必要信息。
4.2.2 代碼庫搜索的優勢
代碼庫檢索子智能體的功能尤為強大。它能通過模式匹配搜索私有代碼倉庫，瀏覽文件結構理解上下文，并能精準讀取特定代碼實現及對應行號。
4.2.3 權衡點
這種深度智能體架構運行時間較長，復雜查詢有時需要 1-3 分鐘，但它的全面性值得等待。當初始響應未能觸及問題核心時，我們會啟用深度智能體。
該模式在發布初期僅對部分用戶開放，幾天后將全面上線。
五、為何放棄向量嵌入方案？
傳統的文檔搜索方式（分割文檔、生成嵌入向量、存儲到向量數據庫、通過相似度檢索）適用于 PDF 這類非結構化內容，但在處理結構化產品文檔時，我們頻繁遇到三個問題：
- 分割破壞結構：將文檔切成 500 tokens 片段后，標題、小節和上下文關系都會丟失。智能體可能只引用 “設置 streaming=True”，卻不解釋原因和適用場景，用戶還得自己翻找完整頁面。
- 需持續重新索引：我們的文檔每天更新多次，每次修改都要重新分割、重新生成嵌入向量、重新上傳，嚴重拖慢效率。
- 引用模糊：用戶無法驗證答案的準確性，也無法追溯信息來源。
突破性的發現是：我們一直都在解決錯誤的問題。文檔本身已有清晰結構，知識庫已分類整理，代碼庫也具備可瀏覽性。我們不需要更復雜的檢索方式，而是要讓智能體直接訪問這些現成的結構。
六、更優方案：直接 API 訪問 + 智能提示詞
我們不再采用分割和嵌入的方式，而是讓智能體直接訪問原始內容：
- 文檔方面，使用 Mintlify 的 API，返回包含完整標題、小節和代碼示例的頁面。
- 知識庫方面，先通過標題檢索，再讀取最相關的文章全文。
- 代碼庫方面，將代碼庫上傳到 LangGraph Cloud 部署環境，使用 ripgrep 進行模式匹配、通過目錄遍歷理解結構，并讀取特定代碼實現。
智能體不依賴相似度分數檢索，而是像人類一樣搜索：使用關鍵詞、優化查詢、提出跟進問題。
這就是核心創新點：我們不只是讓智能體單次搜索并返回結果，而是通過提示詞引導它批判性思考現有信息是否足夠。如果結果模糊或不完整，就優化查詢重新搜索；如果文檔提到某個概念但未解釋，就專門搜索該概念；如果存在多種解讀，就聚焦最相關的一種。
七、工具設計：貼合人類工作流程
我們設計工具時，參考的是人類實際的搜索習慣，而非檢索算法的邏輯。
7.1 文檔搜索：完整頁面而非片段
文檔搜索工具通過 Mintlify API 查詢，返回完整頁面。當用戶詢問流式傳輸相關問題時，智能體不會得到來自不同章節的三個零散段落，而是獲取整個流式傳輸文檔頁面，結構與人類閱讀時完全一致。
@tool
def SearchDocsByLangChain(query: str, page_size: int = 5, language: Optional[str] = None) -> str:
"""通過 Mintlify API 搜索 LangChain 文檔"""
params = {"query": query, "page_size": page_size}
if language:
params["language"] = language
response = requests.get(MINTLIFY_API_URL, params=params)
return _format_search_results(response.json())在此基礎上，我們還通過提示詞引導智能體評估初始結果是否真的能回答問題：這是正確的章節嗎？是否有需要澄清的相關概念？使用更具體的搜索詞會不會更好？
智能體最多可進行 4-6 次工具調用，我們鼓勵它戰略性地利用這些機會，在給出回復前充分理解問題。
實際應用示例：用戶問：“如何為智能體添加記憶功能？”智能體先搜索 “memory”，得到的結果涵蓋 checkpointing（檢查點）、對話歷史和 Store API。它意識到問題存在歧義--“記憶” 可能指線程內的對話狀態持久化，也可能指跨多個對話的事實存儲。于是它用 “checkpointing” 重新搜索，找到支持文章《如何在 LangGraph 中配置檢查點？》，但發現該文章未涉及跨線程記憶。接著它搜索 “Store API” 填補信息缺口。最終答案既涵蓋了用于對話歷史的 checkpointing，也包括了用于長期記憶的 Store API，并精確引用了所用的支持文章和文檔。
這種迭代搜索過程在 Create Agent 中只需幾秒，但從根本上提升了回復質量。智能體不只是在檢索信息，更是在思考用戶的真實需求。
7.2 知識庫搜索：先掃描再閱讀
我們將知識庫（由 Pylon 提供支持）的搜索設計為兩步流程，貼合人類使用知識庫的習慣：
- 智能體先獲取幾十篇文章的標題，快速掃描篩選出相關內容。
- 只讀取篩選后最相關的文章全文。??
@tool
def search_support_articles(collections: str = "all", limit: int = 50) -> str:
"""第一步：獲取文章標題進行掃描"""
articles = pylon_client.list_articles(collectinotallow=collections, limit=limit)
return json.dumps([{
"id": a["id"],
"title": a["title"],
"url": a["url"]
} for a in articles])
@tool
def get_article_content(article_ids: List[str]) -> str:
"""第二步：讀取最相關的文章"""
articles = pylon_client.get_articles(article_ids)
return "\n\n---\n\n".join([
f"# {a['title']}\n\n{a['content']}\n\n來源：{a['url']}"
for a in articles
])7.2.1 優勢
這種設計避免了智能體被海量信息淹沒。它不會將 30 篇完整文章傳入上下文窗口，而是篩選出 2-3 篇真正相關的內容，深入閱讀并提取關鍵信息。
提示詞進一步強化了這一邏輯：注重質量而非數量，必要時縮小搜索范圍，只返回與問題直接相關的信息。
7.3 代碼庫搜索：搜索、導航、驗證
這正是深度智能體（Deep Agent）的優勢所在。我們為智能體提供了三個工具，完全復刻了開頭提到的工程師工作流程，與他們使用 Claude Code 時的操作模式一致：?
@tool
def search_public_code(pattern: str, path: Optional[str] = None) -> str:
"""第一步：查找匹配模式的代碼"""
cmd = ["rg", pattern, str(path or search_path)]
return subprocess.run(cmd, capture_output=True, text=True).stdout
@tool
def list_public_directory(path: str, max_depth: int = 2) -> str:
"""第二步：理解文件結構"""
cmd = ["tree", "-L", str(max_depth), str(path)]
return subprocess.run(cmd, capture_output=True, text=True).stdout
@tool
def read_public_file(file_path: str, start_line: int = 1, num_lines: int = 100) -> str:
"""第三步：讀取實際實現代碼"""
with open(file_path, "r") as f:
lines = f.readlines()
return "\n".join(lines[start_line-1:start_line-1+num_lines])7.3.1 工作流程
- 首先，使用 ripgrep 搜索匹配特定模式的代碼。
- 然后，列出目錄結構，理解文件組織方式。
- 最后，讀取特定文件的相關章節，并返回帶有行號的代碼實現。
實際案例：用戶反饋生產環境中流式傳輸 token 出現卡頓。文檔子智能體發現流式傳輸配置涉及緩沖區設置，知識庫子智能體找到一篇關于升級后流式傳輸問題的支持文章。而代碼庫子智能體找到了問題的核心 —— 它搜索 “streaming buffer”，導航到 callbacks/streaming.py 文件，并返回了 47-83 行的代碼，其中默認緩沖區大小被硬編碼，這正是問題的關鍵。
深度智能體的獨特之處在于，它能在三個領域并行工作，并將中間結果匯總成連貫的答案。
八、深度智能體與子圖如何解決上下文過載？
最初，我們將深度智能體設計為單一系統，可訪問所有三個工具，但它會返回所有搜索到的內容。主智能體可能同時收到五篇文檔、十二篇知識庫文章和二十個代碼片段，導致上下文窗口過載。最終回復要么充斥無關細節，要么遺漏關鍵信息。
于是，我們用專業子圖對其進行重構。
8.1 工作原理
每個子智能體獨立運作，在自己的領域內搜索、通過跟進問題澄清歧義、篩選結果，只提取 “黃金數據”—— 即回答問題所需的關鍵事實、引用和上下文。
主協調智能體不會接觸原始搜索結果，只接收每個領域 “專家” 提煉后的核心信息。
8.2 核心價值
文檔子智能體可能閱讀五篇完整頁面，但只返回兩個關鍵段落；知識庫子智能體可能掃描二十個標題，但只返回三個相關摘要；代碼庫子智能體可能搜索五十個文件，但只返回帶有行號的特定實現。
主智能體得到的是干凈、經過篩選的信息，能夠輕松整合為全面的答案。
九、打造可投入生產的穩定系統
再精良的智能體設計，也需要可靠的生產級基礎設施才能應對真實用戶的使用場景。我們開發了模塊化中間件，處理那些會干擾提示詞邏輯的運營問題：???
?
middleware = [
guardrails_middleware, # 過濾無關查詢
model_retry_middleware, # API 調用失敗時重試
model_fallback_middleware, # 切換備用模型
anthropic_cache_middleware # 緩存高成本調用結果
]9.1 各層中間件的作用
- 防護中間件（Guardrails）：過濾無關查詢，確保智能體專注于 LangChain 相關問題。
- 重試中間件（Retry）：優雅處理臨時 API 故障，避免用戶看到晦澀的錯誤信息。
- 備用中間件（Fallback）：當某個模型不可用時，自動切換到 Haiku、GPT-4o Mini 或 Gemini Nano。
- 緩存中間件（Caching）：復用相同查詢的結果，降低成本。
這些中間件對用戶不可見，但對系統可靠性至關重要。它們讓智能體專注于邏輯推理，而基礎設施則負責處理故障、優化成本和質量控制。
十、讓用戶輕松使用智能體
打造優秀的智能體只是第一步，更重要的是讓用戶能以快速、智能的方式使用它。
我們借助 LangGraph SDK 處理流式傳輸和狀態管理的所有復雜邏輯。
10.1 加載用戶對話線程
當用戶打開 Chat LangChain 時，我們通過 LangGraph SDK 獲取其對話歷史：?
const userThreads = await client.threads.search({
metadata: { user_id: userId },
limit: THREAD_FETCH_LIMIT,
})?
每個對話線程的元數據中都存儲了用戶 ID，確保對話隱私安全，且在不同會話中保持連續。LangGraph SDK 會自動處理篩選邏輯。
10.2 實時流式傳輸響應
當用戶發送消息時，LangGraph SDK 會實時流式傳輸生成中的響應：?
const streamResponse = client.runs.stream(threadId, "docs_agent", {
input: { messages: [{ role: "user", content: userMessage }] },
streamMode: ["values", "updates", "messages"],
streamSubgraphs: true,
})
for await (const chunk of streamResponse) {
if (chunk.event === "messages/partial") {
setMessages(prev => updateWithPartialContent(chunk.data.content))
}
}10.3 用戶可見效果
三種流式模式展示智能體的完整思考過程：
- messages：智能體逐詞生成回復，用戶可實時看到內容。
- updates：顯示智能體正在進行的工具調用（如搜索文檔）。
- values：處理完成后的最終完整狀態。
用戶能直觀看到智能體的思考過程，搜索文檔、查詢知識庫、逐詞構建回復，全程無需等待加載。
10.4 對話記憶功能
只需在消息間傳遞相同的 thread_id，LangGraph 的檢查點工具就會自動處理后續工作：存儲對話歷史、為每個回合檢索上下文、在不同會話中維持狀態。我們設置了 7 天的生存時間（TTL），無需額外配置。
十一、重構成果
新系統上線后，我們看到了顯著的改進：
- 面向公眾的 Chat LangChain：用戶能在 15 秒內收到帶精準引用的回復，可直接通過鏈接查看相關文檔或知識庫文章，文檔更新也能自動同步，無需手動重新索引。
- 內部使用：支持工程師借助深度智能體處理最復雜的工單。它能搜索文檔、交叉驗證已知問題、深入私有代碼庫查找實現細節，為工程師提供關鍵參考。智能體不會取代工程師，而是成為他們的助力，承擔研究工作，讓工程師能專注于解決問題。
十二、核心經驗總結
- 遵循用戶工作流程：不要重新發明輪子，自動化優秀用戶（或內部專家）已在使用的高效流程。對 LangChain 而言，就是復刻 “查閱文檔→查看知識庫→檢索代碼庫” 的三步流程。
- 評估向量嵌入的適用性：對于產品文檔、代碼這類結構化內容，向量嵌入可能破壞文檔結構、導致引用模糊，還需持續重新索引。向量嵌入更適合非結構化內容、短文本片段或聚類場景。
- 讓智能體直接訪問結構化內容：通過 API 讓智能體直接對接現有結構化內容，使其能像人類一樣通過關鍵詞搜索、優化查詢來獲取信息。
- 優先強化推理能力而非檢索能力：工具設計要貼合人類習慣（ 比如：先掃標題再讀全文、代碼檢索結合模式匹配與目錄導航），通過提示詞引導智能體在結果模糊時提出跟進問題、優化查詢，確?；卮鹁珳矢采w用戶真實需求。
- 用深度智能體和子圖管理上下文：處理跨領域復雜問題時，帶專業子圖的深度智能體能避免主協調智能體被原始搜索結果淹沒，每個子智能體只傳遞篩選后的核心信息。
- 生產級中間件不可或缺：再精良的智能體設計也需要可靠的基礎設施支撐。實現防護（過濾無關查詢）、重試（API 故障）、備用（模型切換）和緩存等模塊化中間件，是確保系統可靠性、成本優化和質量控制的關鍵。
十三、后續規劃
公共代碼庫搜索功能即將上線（未來幾天內），當文檔和知識庫無法解答問題時，智能體將搜索公開代碼倉庫，驗證實現細節并引用具體行號。
十四、親自體驗
Chat LangChain 已正式上線（地址：chat.langchain.com）。想要最快響應速度，可選擇 Claude Haiku 4.5；也可以嘗試 GPT-5 Mini 和 GPT-5 Nano，對比不同模型的表現。
好了，這就是我今天想分享的內容。
本文轉載自???玄姐聊AGI?? 作者：玄姐
