如果你的多 Agent 系統(tǒng)只在一臺(tái)機(jī)器上跑你可能還意識(shí)不到 Agent-Reach 的價(jià)值。等 Agent 被拆到不同容器、不同機(jī)器、不同網(wǎng)絡(luò)區(qū)域后你就會(huì)遇到一類特別詭異的現(xiàn)象Agent 的進(jìn)程明明活著日志還在打印但調(diào)度 Agent 就是連不上它。我在負(fù)責(zé)一個(gè)多 Agent 質(zhì)檢系統(tǒng)時(shí)被這個(gè)問(wèn)題連續(xù)折磨了兩周。后來(lái)折騰出了一個(gè)輕量工具就是 Agent-Reach。它解決的問(wèn)題非常具體多 Agent 協(xié)作里的觸達(dá)管理——Agent 如何注冊(cè)、如何被感知、任務(wù)消息如何可靠投遞。這篇文章會(huì)從一次真實(shí)事故講起掰開揉碎介紹 Agent-Reach 的架構(gòu)、核心算法、接入步驟和排查經(jīng)驗(yàn)。無(wú)論你是在用 LangGraph、CrewAI 這類編排框架還是準(zhǔn)備自己手寫多 Agent 服務(wù)只要你的 Agent 需要跨進(jìn)程、跨機(jī)器協(xié)作這篇文章里的思路都可以直接參考。1. 先從一次線上事故說(shuō)起Agent 為什么叫不應(yīng)1.1 一次真實(shí)的多 Agent 超時(shí)事故當(dāng)時(shí)我們有一個(gè)質(zhì)檢系統(tǒng)跑著 12 個(gè) Agent分別部署在兩個(gè)機(jī)房和一組容器節(jié)點(diǎn)上。為了把這些 Agent 串起來(lái)我們用了主流的微服務(wù)注冊(cè)中心做服務(wù)發(fā)現(xiàn)每個(gè) Agent 啟動(dòng)后上報(bào)自己的 IP 和端口主調(diào)度 Agent 通過(guò)注冊(cè)中心拿地址然后直接發(fā)起 HTTP 調(diào)用。起初一切正常直到某次發(fā)布后集中式調(diào)度器開始大量出現(xiàn)connect timeout很多子 Agent 的任務(wù)隊(duì)列里堆了上千條消息。我們第一反應(yīng)是網(wǎng)絡(luò)問(wèn)題于是登錄到調(diào)度機(jī)器上手動(dòng) curl 那些 Agent 的地址。結(jié)果非常詭異幾乎每個(gè)地址都能通端口響應(yīng)也正常Agent 的健康檢查接口返回 200。但一旦讓調(diào)度器去調(diào)用真實(shí)的業(yè)務(wù)接口就有一半概率卡住最終超時(shí)。后來(lái)我們查了很久才發(fā)現(xiàn)問(wèn)題出在受檢 Agent 內(nèi)部其中一個(gè)核心組件出現(xiàn)了死循環(huán)導(dǎo)致處理線程幾乎被占滿但負(fù)責(zé)健康檢查的線程還能響應(yīng)簡(jiǎn)單請(qǐng)求。這個(gè)事故讓我徹底意識(shí)到傳統(tǒng)微服務(wù)的注冊(cè)中心模式放在 Agent 協(xié)作場(chǎng)景里是不夠的。Agent 的可達(dá)不能只看進(jìn)程是否活著更要看它有沒(méi)有能力接收并處理當(dāng)前的任務(wù)消息。為了應(yīng)對(duì)這一類問(wèn)題我需要一個(gè)專門為 Agent 設(shè)計(jì)的東西它得懂 Agent 的注冊(cè)、心跳、網(wǎng)絡(luò)探測(cè)和消息投遞而不是讓我把微服務(wù)全家桶搬過(guò)來(lái)再魔改一遍。后來(lái)Agent-Reach 就這么誕生了。1.2 Agent-Reach 是什么適合誰(shuí)Agent-Reach 本質(zhì)上是一個(gè)面向多 Agent 協(xié)作的輕量觸達(dá)層。它不是一個(gè)完整的 Agent 框架不提供大模型推理能力也不替代 LangGraph 這類編排工具。它專注解決三個(gè)問(wèn)題Agent 如何注冊(cè)和發(fā)現(xiàn)、Agent 當(dāng)前是否真正可達(dá)、任務(wù)消息如何可靠地投遞到正確的 Agent 實(shí)例上。你可以把它理解成 Agent 世界的電話交換機(jī) 健康檔案。Agent-Reach 用 Go 實(shí)現(xiàn)核心是一個(gè)中心服務(wù)各 Agent 通過(guò)多語(yǔ)言 SDK 接入。目前我主要維護(hù) Python 和 Node 兩種 SDK基本覆蓋了實(shí)驗(yàn)性項(xiàng)目的常用語(yǔ)言。如果你正在做跨進(jìn)程、跨機(jī)器部署的 Agent 協(xié)作尤其是遇到服務(wù)注冊(cè)了但調(diào)用不到進(jìn)程活著但任務(wù)不消費(fèi)這類問(wèn)題很適合嘗試這套思路。如果你只是在本機(jī)用兩個(gè) Agent 做演示那暫時(shí)不必引入它Agent-Reach 的價(jià)值在于分布式環(huán)境下的確定性。2. 整體架構(gòu)設(shè)計(jì)Agent-Reach 如何做到統(tǒng)一觸達(dá)2.1 注冊(cè)、探測(cè)、路由三層結(jié)構(gòu)Agent-Reach 的架構(gòu)不復(fù)雜核心是三個(gè)組件注冊(cè)中心Registry、可達(dá)性探針Reach Probe和觸達(dá)路由器Router。這三個(gè)組件互相配合形成一條完整的鏈路。注冊(cè)中心負(fù)責(zé)維護(hù)每個(gè) Agent 的元數(shù)據(jù)包括 Agent ID、能力標(biāo)簽、地址列表、版本號(hào)、啟停時(shí)間等。它默認(rèn)使用 SQLite 存儲(chǔ)單機(jī)幾百個(gè) Agent 沒(méi)問(wèn)題如果要部署多副本可以把存儲(chǔ)后端切換到 etcd?？蛇_(dá)性探針會(huì)不斷從注冊(cè)中心拉取 Agent 地址并主動(dòng)發(fā)起 TCP 探測(cè)測(cè)量往返時(shí)延、丟包率和連通性然后生成一個(gè)綜合的可達(dá)性評(píng)分。觸達(dá)路由器則是消息的發(fā)貨員當(dāng)調(diào)用方通過(guò) Agent ID 請(qǐng)求某個(gè) Agent 時(shí)路由器根據(jù)注冊(cè)信息和評(píng)分結(jié)果選擇一個(gè)最優(yōu)實(shí)例把消息投遞過(guò)去失敗時(shí)自動(dòng)進(jìn)入重試流程。三者之間的數(shù)據(jù)流大致是這樣的Agent 啟動(dòng)時(shí)SDK 先調(diào)用agentreach.Register()把自己注冊(cè)進(jìn)去然后后臺(tái)線程每隔固定時(shí)間上報(bào)一次心跳服務(wù)端的探針從注冊(cè)中心拿到地址列表主動(dòng)測(cè)一遍并把結(jié)果寫回注冊(cè)中心當(dāng)業(yè)務(wù)代碼調(diào)用agentreach.Send()時(shí)Router 會(huì)結(jié)合注冊(cè)列表、心跳狀態(tài)、探測(cè)結(jié)果來(lái)決定投遞路徑。整個(gè)過(guò)程中調(diào)用方永遠(yuǎn)只關(guān)心 Agent ID不需要維護(hù)任何 IP 或端口表。這個(gè)設(shè)計(jì)帶來(lái)的直接好處是你調(diào)整 Agent 副本、遷移服務(wù)器、更換容器網(wǎng)絡(luò)都不需要改動(dòng)調(diào)用方代碼。2.2 為什么不用純注冊(cè)中心方案可能有人會(huì)問(wèn)直接用 Nacos、Consul 這類注冊(cè)中心不行嗎我之前也這么想過(guò)但實(shí)踐下來(lái)有幾個(gè)坑。第一傳統(tǒng)注冊(cè)中心的健康檢查通?？?HTTP/health接口返回 200 就認(rèn)為是健康的。但 Agent 場(chǎng)景的問(wèn)題在于健康接口可以很輕而實(shí)際業(yè)務(wù)處理線程可能已經(jīng)被拖垮。也就是說(shuō)傳統(tǒng)健康檢查給不出是否有能力消費(fèi)消息的判斷。第二Agent 的實(shí)例地址經(jīng)常動(dòng)態(tài)變化尤其是容器環(huán)境一個(gè) Agent ID 可能對(duì)應(yīng)多個(gè)實(shí)例傳統(tǒng)注冊(cè)中心雖然支持服務(wù)列表但按能力標(biāo)簽路由需要大量二次開發(fā)。第三注冊(cè)中心本身不負(fù)責(zé)消息投遞它只解決誰(shuí)能被找到不解決消息怎么送進(jìn)去。Agent 協(xié)作最關(guān)鍵的恰恰是后者任務(wù)消息要可靠地進(jìn)入目標(biāo) Agent 的處理隊(duì)列并且在失敗時(shí)能夠重試、轉(zhuǎn)移。Agent-Reach 沒(méi)有把自己定位成又一個(gè)注冊(cè)中心而是把注冊(cè)、探測(cè)和投遞三個(gè)動(dòng)作整合到同一個(gè)上下文里。調(diào)度決策可以同時(shí)參考元數(shù)據(jù)和實(shí)時(shí)探測(cè)結(jié)果盡量避免查到的節(jié)點(diǎn)活著結(jié)果一調(diào)用就超時(shí)的尷尬。這套邏輯用熟了以后你再回去看傳統(tǒng)注冊(cè)中心會(huì)覺(jué)得它只解決了一半問(wèn)題。2.3 心跳與探測(cè)雙通道的取舍Agent-Reach 使用了雙通道來(lái)做可達(dá)性判斷應(yīng)用層心跳和服務(wù)端主動(dòng)探測(cè)。這兩條通道各有側(cè)重缺一不可。應(yīng)用層心跳由 Agent SDK 主動(dòng)發(fā)起默認(rèn)每 10 秒上報(bào)一次除了我還活著之外還會(huì)攜帶當(dāng)前負(fù)載、正在處理的任務(wù)數(shù)、最近一次任務(wù)完成時(shí)間等業(yè)務(wù)狀態(tài)。服務(wù)端主動(dòng)探測(cè)則從 Agent-Reach 服務(wù)端的視角出發(fā)向 Agent 注冊(cè)地址發(fā)送 TCP 探測(cè)包測(cè)量 RTT、丟包率等網(wǎng)絡(luò)指標(biāo)。雙通道的價(jià)值在于互相校驗(yàn)心跳是 Agent 自己說(shuō)的可能因?yàn)榇a bug 而失真探測(cè)來(lái)自服務(wù)端更接近真實(shí)調(diào)用的網(wǎng)絡(luò)視角但它看不到業(yè)務(wù)內(nèi)部狀態(tài)。只有兩者交叉才能同時(shí)發(fā)現(xiàn)進(jìn)程假活和網(wǎng)絡(luò)不通這兩種問(wèn)題。舉一個(gè)實(shí)際例子某個(gè) Agent 因?yàn)橘Y源泄漏進(jìn)入半死狀態(tài)心跳線程還能跑但業(yè)務(wù)線程已經(jīng)全部阻塞。此時(shí)鏈路探測(cè)可能完全正常不過(guò) Agent 上報(bào)的正在處理任務(wù)數(shù)會(huì)持續(xù)上漲。Agent-Reach 就會(huì)結(jié)合這個(gè)業(yè)務(wù)指標(biāo)把該 Agent 標(biāo)記為業(yè)務(wù)性不可達(dá)而不是繼續(xù)把新任務(wù)硬塞進(jìn)去。反之如果心跳線程掛掉了但探測(cè)正常說(shuō)明 Agent 進(jìn)程還在但狀態(tài)上報(bào)出了問(wèn)題這種情況會(huì)觸發(fā)告警但不會(huì)立刻判定為離線。兩條通道互相印證信息更可靠。3. 核心細(xì)節(jié)可達(dá)性評(píng)分與可靠性投遞3.1 AgentReachScore 評(píng)分公式Agent-Reach 最核心的指標(biāo)是AgentReachScore范圍 0~100。它不是簡(jiǎn)單的通或不通而是通過(guò)加權(quán)計(jì)算給上層調(diào)度提供一個(gè)精細(xì)的優(yōu)先選擇依據(jù)。默認(rèn)公式是ReachScore 50 * heartbeatScore 30 * rttScore 20 * lossScore三個(gè)子分?jǐn)?shù)的計(jì)算方式分別如下。心跳分?jǐn)?shù)heartbeatScore取決于最近一次心跳的新鮮度設(shè)置的心跳間隔是 10 秒如果心跳 age 小于 10 秒取 1.0超過(guò) 30 秒后線性衰減到 0。RTT 分?jǐn)?shù)rttScore根據(jù)服務(wù)端到 Agent 的探測(cè)往返時(shí)延計(jì)算小于 20ms 為 1.0大于 500ms 為 0中間線性映射。丟包分?jǐn)?shù)lossScore基于最近 10 次探測(cè)的丟包率0% 為 1.0超過(guò) 30% 為 0。這三個(gè)權(quán)重不是拍腦袋定的。我們?cè)趬簻y(cè)中發(fā)現(xiàn)Agent 失去響應(yīng)比單純網(wǎng)絡(luò)慢對(duì)協(xié)作體驗(yàn)的破壞要大得多所以心跳新鮮度權(quán)重最高RTT 主要影響單次調(diào)用的等待時(shí)長(zhǎng)影響次之短期丟包可以通過(guò)重試來(lái)緩解所以權(quán)重最低。你可以根據(jù)自己網(wǎng)絡(luò)的實(shí)際情況調(diào)整權(quán)重。比如在內(nèi)網(wǎng)低延遲環(huán)境RTT 通常是穩(wěn)定的個(gè)位數(shù)毫秒就可以降低 RTT 權(quán)重避免因?yàn)榕紶栆淮翁綔y(cè)抖動(dòng)導(dǎo)致誤判。舉個(gè)具體的計(jì)算例子。假設(shè)一個(gè) Agent 最近心跳 age 為 12 秒探測(cè) RTT 為 150ms最近 10 次探測(cè)丟包率 5%。那么heartbeatScore 1 - (12-10)/(30-10) 0.9rttScore 1 - (150-20)/(500-20) 0.73lossScore 1 - 5/30 0.83。最終ReachScore 45 21.9 16.6 83.5分屬于可用但狀態(tài)一般。這個(gè)評(píng)分會(huì)直接參與路由選擇分?jǐn)?shù)高的實(shí)例優(yōu)先被投遞。3.2 自適應(yīng)探測(cè)頻率與連接池隔離探測(cè)本身不能太頻繁否則會(huì)無(wú)謂地消耗 Agent 資源和網(wǎng)絡(luò)帶寬但也不能太稀疏否則故障感知會(huì)變慢。Agent-Reach 默認(rèn)的策略是Agent 狀態(tài)健康時(shí)每 5 秒探測(cè)一次當(dāng)某個(gè) Agent 的 ReachScore 降到 60 以下時(shí)探測(cè)頻率自動(dòng)提高到 1 秒如果連續(xù) 3 次探測(cè)全部失敗就會(huì)把該 Agent 標(biāo)記為UNREACHABLE同時(shí)把重試探測(cè)的頻率降為每 30 秒一次。這樣既能在故障發(fā)生時(shí)快速發(fā)現(xiàn)又不會(huì)對(duì)著一個(gè)已經(jīng)宕機(jī)的地址持續(xù)高頻打探。這里有一個(gè)必須強(qiáng)調(diào)的細(xì)節(jié)探測(cè)用的連接池和業(yè)務(wù)消息投遞連接池是要分開的。最初我的實(shí)現(xiàn)里探針復(fù)用了業(yè)務(wù)連接池結(jié)果在一次高負(fù)載測(cè)試中探針連接把連接池占滿真實(shí)的任務(wù)消息反而排不進(jìn)去了。后來(lái)我單獨(dú)為探測(cè)維護(hù)了一個(gè)連接池默認(rèn)最大 8 個(gè)連接超過(guò)就跳過(guò)本次探測(cè)。這個(gè)改動(dòng)雖然不大但對(duì)穩(wěn)定性提升非常明顯屬于那種不踩坑不會(huì)注意到的設(shè)計(jì)。另外探測(cè)結(jié)果還需要做平滑處理不能因?yàn)橐淮?RTT 抖動(dòng)就瘋狂改變路由。Agent-Reach 內(nèi)部保存了最近 10 次探測(cè)結(jié)果的滑動(dòng)窗口路由時(shí)取的是窗口內(nèi)的加權(quán)平均值。這樣做的好處是偶爾一次網(wǎng)絡(luò)毛刺不會(huì)被當(dāng)成 Agent 故障處理。3.3 重試、指數(shù)退避與死信處理Router 在投遞消息時(shí)不會(huì)直接同步阻塞等待目標(biāo) Agent 返回。它先把消息寫入一個(gè)本地持久化隊(duì)列默認(rèn)使用 BoltDB然后異步投遞。這個(gè)設(shè)計(jì)其實(shí)是借鑒了消息隊(duì)列的至少一次語(yǔ)義但用更輕量的方式實(shí)現(xiàn)。為什么不直接上 Kafka因?yàn)橐?Kafka 會(huì)增加部署復(fù)雜度對(duì)中小規(guī)模的 Agent 協(xié)作系統(tǒng)來(lái)說(shuō)性價(jià)比不高。投遞失敗時(shí)Router 會(huì)按照失敗原因做分流處理。目標(biāo) Agent 短暫不可達(dá)時(shí)進(jìn)入重試隊(duì)列按指數(shù)退避重試最多 5 次。第一次重試延遲 1 秒第二次 2 秒第三次 4 秒依次翻倍上限 30 秒。目標(biāo) Agent 返回業(yè)務(wù)錯(cuò)誤比如當(dāng)前負(fù)載已滿或任務(wù)類型不受支持這時(shí)不盲目重試而是立即回調(diào)給調(diào)用方讓上層 Agent 決定是否更換目標(biāo)。重試次數(shù)耗盡后消息進(jìn)入死信隊(duì)列同時(shí)觸發(fā)告警方便人工介入。因?yàn)橥哆f是異步的調(diào)用方拿到的是一個(gè)任務(wù)提交結(jié)果而不是最終執(zhí)行結(jié)果。如果你需要知道 Agent 是否真正處理成功就得依賴任務(wù) ID 做結(jié)果回傳。Agent-Reach 內(nèi)置了結(jié)果回調(diào)接口Agent 處理完消息后可以調(diào)用agentreach.reportResult()把執(zhí)行結(jié)果上報(bào)調(diào)用方通過(guò)agentreach.waitForResult()異步等待結(jié)果。這套機(jī)制對(duì)耗時(shí)任務(wù)非常友好不會(huì)讓調(diào)用方一直占用一個(gè)同步連接。3.4 多副本與按標(biāo)簽路由Agent 生產(chǎn)環(huán)境中經(jīng)常一個(gè) Agent ID 下掛多個(gè)實(shí)例例如三個(gè)相同的文檔解析 Agent 同時(shí)運(yùn)行。Router 在選擇目標(biāo)實(shí)例時(shí)會(huì)先根據(jù)能力標(biāo)簽過(guò)濾然后在可用實(shí)例里按照ReachScore和當(dāng)前負(fù)載綜合排序選最優(yōu)實(shí)例投遞。默認(rèn)策略是最高分優(yōu)先但如果最高分和次高分之間差距小于 5 分會(huì)采用隨機(jī)選擇避免同一個(gè)實(shí)例被反復(fù)選中造成熱點(diǎn)。標(biāo)簽路由是我在實(shí)際使用中認(rèn)為最有價(jià)值的功能之一。你可以給每個(gè) Agent 打上doc、image、gpu、cpu_only這類標(biāo)簽然后調(diào)用時(shí)指定標(biāo)簽要求。例如result agentreach.send( methodtask.process, tags[doc, gpu], payload{doc_id: abc123} )Router 會(huì)自動(dòng)在帶有這兩個(gè)標(biāo)簽的 Agent 中篩選實(shí)例而調(diào)用方完全不需要關(guān)心具體是哪個(gè) Agent 處理。這就讓 Agent 的擴(kuò)容和縮容變得非常靈活新加一個(gè) Agent 實(shí)例只要打上相同標(biāo)簽立刻就能接到任務(wù)下線一個(gè)實(shí)例也只需要從注冊(cè)中心摘除。4. 實(shí)操記錄從零接入 20 個(gè)異構(gòu) Agent4.1 部署 Server 端與配置文件我推薦用 Docker 鏡像方式部署 Server這樣依賴干凈、升級(jí)方便。需要在目標(biāo)機(jī)器上準(zhǔn)備好一個(gè)數(shù)據(jù)目錄用來(lái)存放注冊(cè)數(shù)據(jù)和持久化隊(duì)列。啟動(dòng)命令如下docker run -d --name agent-reach \ -p 8800:8800 \ -p 8900:8900 \ -v /opt/agent-reach/data:/data \ agentreach/server:0.4.2這里 8800 是 HTTP 管理端口供查詢和配置使用8900 是 Agent SDK 通信端口。如果不方便用 Docker也可以下載編譯好的二進(jìn)制文件直接運(yùn)行./agent-reach-server --config config.yaml對(duì)應(yīng)的config.yaml里我習(xí)慣重點(diǎn)配置這幾項(xiàng)server: port: 8900 admin_port: 8800 storage: type: sqlite # 可選 etcd path: /data/agent-reach.db probe: interval: 5s fail_threshold: 3 retry_interval: 30s router: max_retry: 5 dead_letter: trueprobe.interval默認(rèn) 5 秒是一個(gè)比較平衡的配置。調(diào)成 1 秒雖然故障發(fā)現(xiàn)更快但會(huì)讓 Agent 的日志刷新得很快也會(huì)增加連接占用調(diào)成 10 秒以上則會(huì)讓故障發(fā)現(xiàn)變得遲鈍。除非你的監(jiān)控系統(tǒng)有更高頻的需求否則先用默認(rèn)值。4.2 Python Agent 接入與消息收發(fā)以 Python 為例Agent 端接入分為三步注冊(cè)、上報(bào)心跳、啟動(dòng)消息回調(diào)。第一步在 Agent 進(jìn)程啟動(dòng)時(shí)初始化import agentreach agent agentreach.Agent( agent_iddoc-analyzer-01, tags[doc, gpu], addr172.18.0.5:7001, heartbeat_interval10 ) agent.register() agent.start_heartbeat()注意addr必須是其他 Agent 也能訪問(wèn)到的地址不能寫127.0.0.1否則 Agent-Reach 服務(wù)端從別的機(jī)器探測(cè)時(shí)永遠(yuǎn)連不通。這也是新手最容易踩的坑之一。第二步把 Agent 的業(yè)務(wù)處理函數(shù)暴露成回調(diào)接口。Agent-Reach 提供了一套簡(jiǎn)單的裝飾器from agentreach.web import route route(task.process) def handle_task(task_id: str, payload: dict): result process_document(payload[doc_id]) return {code: 0, data: result}裝飾器會(huì)在 Agent 本地啟動(dòng)一個(gè) HTTP 服務(wù)把task.process映射到對(duì)應(yīng)路徑。Router 投遞消息時(shí)會(huì)攜帶task_id、method、payload三個(gè)字段自動(dòng) POST 到這個(gè)路徑。第三步調(diào)用方發(fā)消息result agentreach.send( agent_iddoc-analyzer-01, methodtask.process, payload{doc_id: abc123}, task_idtask-20240915-001 )task_id我強(qiáng)烈建議由業(yè)務(wù)自己生成。如果不傳SDK 會(huì)生成一個(gè) UUID但你沒(méi)有辦法在業(yè)務(wù)上關(guān)聯(lián)原始請(qǐng)求。有了自己的task_id后續(xù)冪等和排查都會(huì)方便很多。4.3 用管理接口驗(yàn)證觸達(dá)狀態(tài)部署完成后可以通過(guò)管理端口快速檢查集群里的所有 Agent 狀態(tài)curl http://localhost:8800/api/v1/agents返回的 JSON 數(shù)組里每個(gè) Agent 會(huì)包含reach_score、probe_status、last_heartbeat、last_probe_error等字段。我當(dāng)時(shí)的 20 個(gè) Agent 里19 個(gè)reach_score穩(wěn)定在 95 分以上只有一個(gè)跨專線部署的 Agent 因?yàn)?RTT 一直在 300ms 左右分?jǐn)?shù)只有 70 多但仍然屬于可用狀態(tài)。我還會(huì)用另一個(gè)命令觀察消息投遞指標(biāo)curl http://localhost:8800/metrics重點(diǎn)關(guān)注agentreach_router_delivery_total、agentreach_router_retry_total和agentreach_router_dead_letter_total三個(gè)指標(biāo)。如果重試次數(shù)持續(xù)上升說(shuō)明網(wǎng)絡(luò)不穩(wěn)定或者目標(biāo) Agent 應(yīng)用層處理能力不足需要進(jìn)一步排查。4.4 長(zhǎng)任務(wù)與異步回調(diào)的處理Agent 處理任務(wù)不總是瞬間完成的。有些任務(wù)比如批量文檔分析可能需要幾十秒甚至幾分鐘。如果調(diào)用方一直同步等結(jié)果會(huì)把連接資源和調(diào)用線程都占住。Agent-Reach 對(duì)此有兩種處理方式。第一種Agent 收到消息后立刻返回一個(gè)已接收狀態(tài)然后在后臺(tái)任務(wù)完成后通過(guò)agentreach.reportResult()回調(diào)結(jié)果。第二種調(diào)用方在發(fā)送消息時(shí)傳入timeout參數(shù)并配合waitForResult()做異步等待。我在接入那個(gè)質(zhì)檢系統(tǒng)時(shí)把所有耗時(shí)超過(guò) 5 秒的任務(wù)都改成了異步回調(diào)模式系統(tǒng)吞吐量立刻上了一個(gè)臺(tái)階。這里要給 Agent 開發(fā)者一個(gè)建議回調(diào)接口一定要做并發(fā)控制。我最初把 Agent 回調(diào)用的是單線程 HTTP 處理結(jié)果連續(xù)投遞幾十個(gè)長(zhǎng)任務(wù)后回調(diào)端口自己先堵了大量消息堆在 TCP backlog 里看起來(lái)服務(wù)端一直在重試實(shí)際 Agent 根本來(lái)不及消費(fèi)。后來(lái)給回調(diào)接口增加了線程池并用max_concurrency元數(shù)據(jù)告訴 Agent-Reach 當(dāng)前實(shí)例的并發(fā)上限路由時(shí)自動(dòng)跳過(guò)已經(jīng)達(dá)到上限的實(shí)例問(wèn)題迎刃而解。5. 常見問(wèn)題與排查技巧實(shí)錄5.1 顯示不可達(dá)但手動(dòng)連接正常這是 Agent-Reach 落地時(shí)最常被問(wèn)到的現(xiàn)象管理接口顯示某個(gè) AgentUNREACHABLE但手動(dòng)curl或nc連接又通。一般情況下問(wèn)題出在判斷維度不同。Agent-Reach 判定不可達(dá)是綜合了心跳新鮮度和服務(wù)端探測(cè)結(jié)果而手動(dòng) curl 通常只驗(yàn)證了端口通。常見原因有三個(gè)。第一Agent 的心跳線程被業(yè)務(wù)代碼阻塞了。比如 Agent 里有一段同步調(diào)用遲遲不返回把心跳 goroutine 也拖住了心跳續(xù)不上評(píng)分自然歸零。第二Agent 注冊(cè)的地址用了127.0.0.1或內(nèi)網(wǎng)映射地址Agent-Reach 服務(wù)端從外部探測(cè)不到。第三云端環(huán)境對(duì) ICMP 或 TCP SYN 限速導(dǎo)致探測(cè)包大量丟失但業(yè)務(wù)流量因?yàn)樽吡藙e的高速通道反而正常。排查時(shí)不要只看最終狀態(tài)要先查last_heartbeat和last_probe_error。如果last_probe_error有內(nèi)容你需要在 Agent-Reach 所在機(jī)器上手動(dòng)執(zhí)行nc -vz agent_ip port確認(rèn)網(wǎng)絡(luò)鏈路是否真的通。如果探測(cè)正常但心跳斷了那問(wèn)題基本在 Agent 進(jìn)程內(nèi)部需要去看 Agent 的日志和線程狀態(tài)。5.2 消息重復(fù)執(zhí)行與冪等處理Agent-Reach 默認(rèn)是至少一次投遞語(yǔ)義所以重試不可避免地會(huì)帶來(lái)重復(fù)消息。如果你收到的任務(wù)里有少量重復(fù)這其實(shí)是正?，F(xiàn)象真正要做的是保證消費(fèi)端的冪等。我常用的方案是在數(shù)據(jù)庫(kù)里維護(hù)一張任務(wù)執(zhí)行記錄表利用唯一索引來(lái)過(guò)濾重復(fù)任務(wù)INSERT INTO task_execute_log(task_id, agent_id, status) VALUES (?, ?, processing) ON CONFLICT(task_id) DO NOTHING;如果插入影響行數(shù)為 0說(shuō)明這個(gè)任務(wù)之前已經(jīng)處理過(guò)直接返回成功不再執(zhí)行業(yè)務(wù)邏輯。這個(gè)方案比先查再插入要穩(wěn)妥能避免并發(fā)重復(fù)投遞時(shí)兩個(gè)人同時(shí)查到不存在然后一起執(zhí)行。注意唯一索引要建立在業(yè)務(wù)冪等鍵上而不是 Agent 生成的隨機(jī) UUID。5.3 多副本下的路由超時(shí)調(diào)優(yōu)如果你一個(gè) Agent ID 掛了多個(gè)副本但還是頻繁出現(xiàn)路由超時(shí)核心原因是 Router 選中的實(shí)例恰好沒(méi)有消費(fèi)能力。比如兩個(gè)文檔分析實(shí)例一個(gè)空閑一個(gè)已經(jīng)積壓了大量任務(wù)但因?yàn)樗鼈兊?ReachScore 差距不大Router 隨機(jī)選中了積壓實(shí)例消息就卡住了。解決辦法有兩個(gè)方向。第一Agent 上報(bào)心跳時(shí)務(wù)必把current_load這個(gè)字段填對(duì)。Router 在選擇實(shí)例時(shí)不僅看 ReachScore還會(huì)參考current_load和max_concurrency負(fù)載高的實(shí)例天然會(huì)被降權(quán)。第二在 Agent 回調(diào)接口處設(shè)置合理的并發(fā)上限。如果并發(fā)數(shù)只設(shè) 1那么來(lái)兩個(gè)任務(wù)就會(huì)有一個(gè)端口響應(yīng)變慢導(dǎo)致 Router 誤判為網(wǎng)絡(luò)問(wèn)題而觸發(fā)重試。我在容器環(huán)境里通常把并發(fā)數(shù)設(shè)為 CPU 核數(shù)的兩倍效果不錯(cuò)。5.4 排查速查表癥狀可能原因檢查方法顯示 UNREACHABLE注冊(cè) IP 外部不可達(dá)、心跳線程阻塞在 Server 端執(zhí)行nc -vz agent_ip portReachScore 持續(xù)偏低網(wǎng)絡(luò) RTT 高、丟包嚴(yán)重查看/metrics中probe_rtt_ms和probe_loss_rate任務(wù)積壓但 Agent 不消費(fèi)業(yè)務(wù)線程池占滿、并發(fā)上限過(guò)低查看 Agent 上報(bào)的current_load和max_concurrency重試次數(shù)飆升目標(biāo) Agent 應(yīng)用層處理能力不足查看agentreach_router_retry_total指標(biāo)變化趨勢(shì)數(shù)據(jù)目錄增長(zhǎng)過(guò)快死信隊(duì)列積壓過(guò)多調(diào)整死信隊(duì)列保留策略只保存必要字段這張表是我在實(shí)際項(xiàng)目中的速查清單覆蓋了我遇到過(guò)的大部分問(wèn)題。當(dāng)然場(chǎng)景不同細(xì)節(jié)會(huì)有點(diǎn)差異但排查方向基本一致。6. 同場(chǎng)景下的三個(gè)擴(kuò)展方向6.1 從單組網(wǎng)走向多組網(wǎng)Agent-Reach 目前的多 Agent 協(xié)作還沒(méi)有支持多租戶聯(lián)邦。如果你有多個(gè)互不相通的網(wǎng)絡(luò)區(qū)域每個(gè)區(qū)域內(nèi)部部署獨(dú)立的 Agent-Reach區(qū)域之間默認(rèn)是隔離的。我最近在嘗試讓不同的 Agent-Reach 服務(wù)之間建立聯(lián)邦關(guān)系通過(guò)一個(gè)輕量的目錄同步機(jī)制讓跨區(qū)域調(diào)用可以像本地調(diào)用一樣按 Agent ID 路由。這個(gè)做法的難點(diǎn)在于區(qū)域間網(wǎng)絡(luò)往往不穩(wěn)定需要把探測(cè)和路由的粒度都加一層。如果只是想做簡(jiǎn)單的多區(qū)域分發(fā)可以先不用等待這個(gè)功能。你可以在上層編排 Agent 里做區(qū)域策略通過(guò) Agent-Reach 的標(biāo)簽?zāi)芰Π巡煌瑓^(qū)域標(biāo)記成不同標(biāo)簽調(diào)用時(shí)指定標(biāo)簽路由器自然只會(huì)選符合條件的實(shí)例。6.2 從通用探測(cè)到任務(wù)級(jí)探測(cè)當(dāng)前 Agent-Reach 的可達(dá)性評(píng)分是通用的只衡量網(wǎng)絡(luò)和應(yīng)用基礎(chǔ)狀態(tài)。但在真實(shí)業(yè)務(wù)里同一個(gè) Agent 可能對(duì)不同類型的任務(wù)響應(yīng)差異很大。例如一個(gè) Agent 既支持文本處理也支持圖片處理GPU 實(shí)例的圖片任務(wù)表現(xiàn)很好文本任務(wù)卻因?yàn)橘Y源競(jìng)爭(zhēng)響應(yīng)很慢。我下一步打算在注冊(cè)數(shù)據(jù)里加入能力資源維度讓每個(gè) Agent 能夠聲明某個(gè)方法預(yù)期的 RTT 和并發(fā)能力Router 在投遞不同任務(wù)時(shí)參考不同的評(píng)分權(quán)重。這樣可以讓調(diào)度更精準(zhǔn)但也會(huì)讓配置和維護(hù)更復(fù)雜。對(duì)于現(xiàn)階段大多數(shù)實(shí)驗(yàn)項(xiàng)目來(lái)說(shuō)通用評(píng)分已經(jīng)足夠用了。6.3 一個(gè)可以馬上動(dòng)手的小優(yōu)化如果你想在現(xiàn)有 Agent-Reach 版本上立刻優(yōu)化效果我建議從心跳載荷入手。SDK 默認(rèn)上報(bào)的心跳消息里除了 Agent ID 和負(fù)載還可以加兩個(gè)自定義字段last_task_duration和consecutive_failure_count。前者可以讓 Router 感知到實(shí)例近期處理任務(wù)的平均耗時(shí)后者可以用于在服務(wù)端做降級(jí)預(yù)判。一旦某個(gè)實(shí)例連續(xù)上報(bào)了 3 次失敗計(jì)數(shù)就可以提前把它從路由池中暫時(shí)移除而不是等任務(wù)消息真正發(fā)過(guò)去之后再等超時(shí)。這個(gè)小改動(dòng)不需要改服務(wù)端邏輯只改 SDK 的心跳字段和服務(wù)端的權(quán)重規(guī)則收益卻很直接。最后再分享一點(diǎn)個(gè)人體會(huì)。我在多 Agent 系統(tǒng)上折騰了這幾年最大的感覺(jué)是大家很容易把注意力放在Agent 聰明不聰明上卻忽略了底層的協(xié)作工程問(wèn)題。Agent-Reach 解決的不是智能問(wèn)題而是穩(wěn)定性問(wèn)題。它讓我在寫業(yè)務(wù)邏輯的時(shí)候再也不用擔(dān)心這個(gè) Agent 到底叫不應(yīng)怎么辦因?yàn)檫@些都交給觸達(dá)層去管了。如果你正在做類似架構(gòu)希望這篇文章里的思路能幫你少踩幾個(gè)坑。