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