級接入層：服務(wù)發(fā)現(xiàn)、健康檢查與智能路由實戰(zhàn))
“Agent”這個詞這兩年快被說爛了。從AutoGPT到各類MCP、工作流編排框架大家都在談智能體但真落到業(yè)務(wù)里你會發(fā)現(xiàn)一個特別容易翻車的環(huán)節(jié)你的智能體跑起來了但你怎么知道它現(xiàn)在活著、在哪兒、能不能被調(diào)用、負載怎么樣你用OpenAI的API不會操心這個問題但自建Agent集群時這套“服務(wù)發(fā)現(xiàn)健康檢查路由調(diào)度”的東西基本上得從頭造一遍。我最近在內(nèi)部把這套基礎(chǔ)設(shè)施做完了項目代號就叫Agent-Reach。名字很直白意思就是“讓每一個Agent都能被準確觸達”。這篇文章把我這幾周的踩坑、設(shè)計取舍和落地實錄整理出來不聊虛的直接講怎么把一個Agent集群做成“有服務(wù)注冊、有健康探活、有智能路由”的生產(chǎn)級接入層。如果你正準備把Agent能力接入業(yè)務(wù)系統(tǒng)或者想給自己的多Agent項目加一層可靠調(diào)度這篇內(nèi)容對你會很有用。不用懂太深的后端知識我會盡量把每一層的設(shè)計邏輯和實現(xiàn)細節(jié)都講清楚。1. 項目初衷與整體設(shè)計思路Agent-Reach不是一個業(yè)務(wù)Agent它不負責對話、寫代碼、做規(guī)劃。它是一層基礎(chǔ)設(shè)施我們內(nèi)部叫它“觸點管理服務(wù)”。簡單說它解決三個問題Agent注冊、Agent發(fā)現(xiàn)、Agent路由。1.1 為什么需要專門的Reach層如果你只有一兩個Agent用配置文件寫死地址就夠了。但一旦Agent數(shù)量上到幾十個或者Agent分散在多臺服務(wù)器、多個K8s節(jié)點上問題馬上變麻煩。部署了新版本的話舊地址失效某臺機器負載過高某類任務(wù)必須由特定Agent處理Agent崩潰后流量還是往它那邊打。這些問題單靠配置管理和負載均衡器是擋不住的因為Agent有狀態(tài)、有類型、有容量差異不是普通的HTTP服務(wù)。我當時走訪了一圈團隊需求總結(jié)下來就是需要一個中間層讓上層應(yīng)用不必感知具體Agent實例的IP和狀態(tài)只按“能力名字”去調(diào)用剩下的尋址和調(diào)度全部交給這一層。這也是Agent-Reach最核心的設(shè)計目標。1.2 三層架構(gòu)的取舍我最初參考了微服務(wù)里注冊中心的成熟套路但Agent和微服務(wù)有一個關(guān)鍵差異微服務(wù)實例相對穩(wěn)定Agent的啟停要頻繁得多而且Agent對上下文和數(shù)據(jù)隔離的要求也更高。所以我沒有直接照搬Eureka或者Nacos而是做了一個偏輕量的三層模型接入層負責接收Agent上報的狀態(tài)信息包括心跳、能力說明、當前并發(fā)數(shù)、上下文長度調(diào)度層根據(jù)業(yè)務(wù)請求攜帶的能力標簽、優(yōu)先級、數(shù)據(jù)親和性在可用Agent列表里選一個最合適的實例緩存層把Agent狀態(tài)數(shù)據(jù)同步到本地內(nèi)存和Redis避免調(diào)度層每次做遠程調(diào)用使得請求路徑盡量短。這個設(shè)計的核心取舍是“以Agent自身狀態(tài)為中心”。調(diào)度器不主動刻板地輪詢一切選擇都以Agent最近一次上報的信息為準。上報的間隔越短調(diào)度越精準代價是Agent端壓力增大。我后來把默認心跳設(shè)成了5秒既不會漏判導致大規(guī)模誤剔除也不會因為上報太頻繁占滿Agent進程的資源。1.3 核心模塊拆解整體代碼可以分為四個模塊。注冊模塊負責接收Agent第一次上線的注冊請求寫入唯一實例ID、能力名、標簽和附加元數(shù)據(jù)探活模塊負責跟蹤每個Agent的續(xù)約超過租約時間就標記為失聯(lián)路由模塊負責按策略篩選可用實例并返回目標地址控制臺模塊提供一個極簡界面能實時看到各Agent的在線狀態(tài)和請求分布。注冊信息我用的是MySQL持久化但實時調(diào)度不查庫只在Agent狀態(tài)變更時才寫庫。這樣設(shè)計的好處是調(diào)度路徑上完全無SQL操作性能瓶頸基本就剩下網(wǎng)絡(luò)開銷了。實際壓測下來單機調(diào)度層QPS能到1.2萬左右對于內(nèi)部工具來說非常夠用。2. 核心機制注冊、?；钆c可達性判定Agent-Reach的關(guān)鍵在于“可達性判定”。這是所有調(diào)度邏輯的地基一旦誤判下游所有策略都會出問題。我把它細分成注冊協(xié)議、心跳租約、狀態(tài)摘除三個子環(huán)節(jié)。2.1 Agent注冊協(xié)議設(shè)計Agent首次啟動時調(diào)用Reach的注冊接口上報自己的實例名、Agent類型、可以處理的技能標簽、限制信息最大并發(fā)數(shù)、單次任務(wù)最長執(zhí)行時間、支持的大模型類型等。注冊完成之后Reach會返回一個instanceId和一個臨時token后續(xù)的心跳和上下線都帶這個token防止偽造上報。注冊信息里有一項我覺得特別重要preferred_regions。這是Agent所在的物理或邏輯區(qū)域標識。比如我的Agent分布在兩個內(nèi)網(wǎng)網(wǎng)段一部分在GPU區(qū)一部分在通用計算區(qū)。當業(yè)務(wù)請求帶有數(shù)據(jù)本地性要求時調(diào)度器能根據(jù)這個字段避開跨網(wǎng)段傳輸省掉大量數(shù)據(jù)搬遷開銷。注冊接口本身冪等性很好做因為instanceId由Agent自己生成一般是hostname進程ID隨機數(shù)Reach側(cè)按這個ID做upsert。第一次上線是insert后續(xù)重復注冊就是update元數(shù)據(jù)。實測中重復注冊主要發(fā)生在Agent崩潰重啟或網(wǎng)絡(luò)閃斷后重連冪等設(shè)計省了前端很多事。2.2 心跳與租約機制心跳接口我設(shè)計得比較簡Agent每隔5秒打一次BeaconBody里只帶instanceId、當前狀態(tài)BUSY或IDLE、當前并發(fā)任務(wù)數(shù)、最近一次任務(wù)耗時。Reach收到心跳后刷新這條Agent的最后更新時間并同步更新內(nèi)存里的狀態(tài)快照。租約機制參考了分布式系統(tǒng)里常見的TTL思路。Reach指定一個leaseDuration默認是15秒。如果15秒內(nèi)沒有收到某實例的心跳就判定該實例失聯(lián)將其從可用池子摘除。同時摘除動作只是把status置為OFFLINE記錄摘除原因和時間并不刪除注冊記錄這樣網(wǎng)絡(luò)抖動恢復后Agent重新上報心跳就能自動回池不需要再次全量注冊。這個設(shè)計有個細節(jié)值得注意心跳不能一過期就殺。瞬斷很常見Agent可能只是暫停了3秒的GC或一次長任務(wù)阻塞。所以我把狀態(tài)切換做成三級HEALTHY、SUSPECT、OFFLINE。超過15秒沒心跳進SUSPECT轉(zhuǎn)發(fā)時標記“降級權(quán)重”但還能接收輕量請求超過30秒還沒心跳才真正摘除。這個緩沖讓系統(tǒng)在波動時穩(wěn)定很多尤其能扛住Agent JVM導致的偶發(fā)停頓。2.3 狀態(tài)摘除與優(yōu)雅下線除了被動摘除Agent還可能主動下線比如發(fā)布新版本時需要排空流量。我預留了一個下線路由Agent調(diào)用/offline接口聲明“我要離線了”Reach把這個實例從可用列表里立刻摘掉但保留已有請求執(zhí)行完。這就避免新流量進入正在重啟的進程。這里踩過一個坑Agent進程在卸載鉤子里調(diào)用offline但進程退出太快HTTP調(diào)用還沒發(fā)出去就斷了。后來我把下線動作做了兩級保障——先標記本進程為“停止接收新任務(wù)”再發(fā)離線請求同時本地維持10秒的grace period確保離線請求在進程真正退出前送達。對于極端場景比如機器斷電那就只能等心跳過期被動摘除了這類情況沒辦法完全避免。3. 路由策略與調(diào)度實現(xiàn)Agent-Reach真正花時間的是路由模塊。它不能隨便挑一個健康實例就算完事而要支持多維度約束。我把調(diào)度拆成“過濾打分選擇”三段每一段都有背后邏輯。3.1 過濾階段先排除不可用實例過濾規(guī)則按優(yōu)先級執(zhí)行第一層過濾是不可用狀態(tài)包括OFFLINE和SUSPECT第二層過濾是能力匹配業(yè)務(wù)請求里的capability字段必須與Agent支持的技能標簽交集非空第三層過濾是數(shù)據(jù)親和性如果請求指定了data_region就只保留該區(qū)域的Agent最后一層是并發(fā)水位過濾Agent當前并發(fā)數(shù)和最大并發(fā)比例超過0.85就臨時不參與調(diào)度。實際使用下來并發(fā)水位過濾是最影響結(jié)果質(zhì)量的。以前沒加這項時某個Agent可能已經(jīng)被壓滿調(diào)度器還是往里扔任務(wù)導致響應(yīng)時長一下子拉胯。加了之后系統(tǒng)會自動把熱點Agent留一口氣處理已有任務(wù)新任務(wù)分散到其他實例上。代價是小部分請求會跑到較遠的區(qū)域但相比整體延遲劣化這個代價完全值得。3.2 打分階段量化每個候選Agent的適配度過濾只剩健康實例后進入打分環(huán)節(jié)。打分函數(shù)我用的加權(quán)綜合公式Score 0.35 * ConcurrencyScore 0.30 * AffinityScore 0.20 * LatencyScore 0.15 * StabilityScoreConcurrencyScore是剩余并發(fā)容量的歸一化值A(chǔ)ffinityScore看的是候選Agent的歷史調(diào)用記錄如果有過去5分鐘內(nèi)成功處理過同一類請求就加分LatencyScore取最近100次任務(wù)的P50執(zhí)行耗時耗時越低分越高StabilityScore看的是近一小時GC暫停次數(shù)、內(nèi)存增長趨勢、注意這里是Agent運行時統(tǒng)計上來的指標不是Reach自己猜的。這個公式不是一開始就定死的。最初我把穩(wěn)定性的權(quán)重設(shè)為0結(jié)果某個Agent因為內(nèi)存泄漏導致頻繁FullGC調(diào)度器毫不知情照樣把任務(wù)給它直到請求超時才發(fā)現(xiàn)。后來加入了穩(wěn)定性指標并在控制臺打了一個“GC風暴”告警這類問題才被提前攔下。3.3 選擇階段隨機加權(quán)與親和保持得分算完后自然是用加權(quán)隨機選擇而不是直接選最高分。原因很簡單如果始終選最高分實例所有流量會在瞬間集中到同一批Agent上很快就把它們打熱然后又被并發(fā)過濾防住導致“熱點漂移”。加權(quán)隨機讓高分實例有更高概率被選中但低分實例也有少量機會整體分布更平滑。這里還有一個“親和保持”的細節(jié)如果請求的traceId之前已經(jīng)固定到了一個Agent實例且該實例仍然健康我會把它直接返回不加額外計算。這保證同一用戶會話盡量在一個Agent上完成避免上下文反復搬運。親和保持出過一次問題agent實例因網(wǎng)絡(luò)瞬斷進入SUSPECT狀態(tài)但親和策略還把它返回給調(diào)用方導致一批請求全部失敗。修復方法是在親和命中后增加一個快速狀態(tài)校驗SUSPECT直接跳過親和。這個邏輯是給調(diào)度器加了一行判斷但實際收益很明顯故障恢復速度從分鐘級降到了秒級。4. 實操落地從零搭建Agent-Reach理論講完了分享點直接能上手的操作。我用Go寫了Reach服務(wù)端Agent端SDK用了Python因為現(xiàn)在大部分Agent框架的膠水層還是Python多點。下面把關(guān)鍵環(huán)節(jié)列一下照著做基本能跑通。4.1 服務(wù)端核心代碼骨架Reach的服務(wù)端入口我用了Gin框架數(shù)據(jù)庫用MySQL緩存用了Redis和內(nèi)存混合。核心調(diào)度邏輯不依賴RedisRedis只用于跨節(jié)點同步和審計日志。代碼結(jié)構(gòu)比較清晰核心就兩個接口注冊和心跳。// 注冊Agent r.POST(/api/agent/register, func(c *gin.Context) { var req RegisterRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } id : registry.Register(req) c.JSON(200, gin.H{instance_id: id, token: registry.GenToken(id)}) }) // 心跳上報 r.POST(/api/agent/beacon, func(c *gin.Context) { var req BeaconRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } registry.Heartbeat(req.InstanceID, req.Status) c.JSON(200, gin.H{ok: true}) })心跳接口沒有做復雜的鑒權(quán)只校驗了token前綴的合法性因為Agent端和Reach端都在內(nèi)網(wǎng)且中間有防火墻規(guī)則依賴內(nèi)網(wǎng)信任可以降低不少通信開銷。調(diào)度查詢接口是另一個重點。上層應(yīng)用傳入的調(diào)用ID其實是capabilityNameReach根據(jù)它選好Agent后返回完整的調(diào)用地址和參數(shù)模板。# 偽代碼簡化突出調(diào)度流程 def schedule_request(capability: str, context: dict) - AgentTarget: pool registry.get_candidates(capability) if not pool: raise NoAvailableAgentError(capability) filtered filter_by_health(pool) filtered filter_by_capacity(filtered) pool_with_score [(agent, compute_score(agent, context)) for agent in filtered] return weighted_choose(pool_with_score)4.2 Agent端SDK接入要點Agent端SDK封裝了注冊、心跳、狀態(tài)上報三個動作。我建議把SDK設(shè)計成啟動時自動異步注冊不阻塞Agent主流程。試用的時候發(fā)現(xiàn)如果注冊失敗直接拋異常很多Agent啟動邏輯會被卡住所以我改成“注冊失敗進入重試隊列不影響本地執(zhí)行”的模式。心跳邏輯用后臺線程實現(xiàn)每次打心跳時順帶傳最近一次任務(wù)執(zhí)行耗時。這里要強調(diào)任務(wù)耗時的統(tǒng)計口徑必須準我遇到過Agent端把排隊時間也算進執(zhí)行耗時導致Reach端的LatencyScore完全失真。后來規(guī)范了字段task_duration_ms只算真正執(zhí)行時間排隊和網(wǎng)絡(luò)傳輸時間都單獨上報。class AgentReachSDK: def start(self): threading.Thread(targetself._beacon_loop, daemonTrue).start() self.register() def _beacon_loop(self): while True: self.report_state() time.sleep(5)這里還有一個經(jīng)驗值心跳線程的網(wǎng)絡(luò)超時時間不要設(shè)置太長建議2秒以內(nèi)。如果Reach端整個宕機Agent不該無限等網(wǎng)絡(luò)響應(yīng)而是降級成本地模式保留Agent獨立工作的能力。畢竟Reach掛了業(yè)務(wù)Agent還能干活等到Reach恢復再做補償注冊就行。4.3 控制臺與可觀測性Reach控制臺有一個實時視圖能看到所有Agent實例的列表每行帶狀態(tài)、最近心跳時間、當前并發(fā)、24小時成功率。這個視圖對運維特別有用基本能替代一大部分調(diào)試工作。另外我加了一個事件流頁面所有Agent的注冊、失聯(lián)、恢復、路由變更都在頁面上滾動顯示。排查問題的時候按時間軸看事件流比看日志快很多。比如某個時刻調(diào)度變慢往上查一下往往能看到某臺機器因為GC發(fā)生SUSPECT再結(jié)合日志確認就是那次事件引起的連鎖反應(yīng)。5. 常見問題與排查經(jīng)驗速查這幾周實際跑下來遇到的問題比預想的多。我挑了些有代表性的做成表格方便速查。現(xiàn)象可能原因排查手段Agent列表全部脫機Reach服務(wù)端與數(shù)據(jù)庫連接斷開檢查MySQL連接池心跳寫庫失敗導致判定全部失聯(lián)偶發(fā)請求打到已下線的Agent親和保持跳過了SUSPECT校驗確認親和命中后的狀態(tài)二次檢查邏輯是否生效調(diào)度結(jié)果總集中到同一實例打分函數(shù)內(nèi)緩存被人為刪掉檢查Redis緩存失效策略確認實例分數(shù)未過期心跳正常但請求超時Agent實例已阻塞但心跳線程仍能執(zhí)行查看實例執(zhí)行池線程消耗增加單獨的執(zhí)行狀態(tài)上報注冊接口偶發(fā)503注冊并發(fā)量過大數(shù)據(jù)庫寫沖突注冊寫庫改為異步批量同步注冊接口改為最終一致除了表格里這些還有一個非常值得說的坑Agent上線時如果注冊得太快下一條心跳還沒跟上Reach端可能會把它認成“新實例但從未活躍”然后被租約機制誤判剔除。我的解決辦法是在注冊接口返回后代理端以此為起點立刻打一條帶initialtrue的心跳。這條心跳不參與正常租約計算只用于確認“我確實活了”。還有一個和Agent調(diào)度強相關(guān)的問題——線程池阻塞。曾有一個Agent實例的心跳一直正常但它內(nèi)部處理請求的線程池全部阻塞新請求進入后排隊耗時指數(shù)級增長。Reach的P50耗時指標很快捕捉到了異常但由于閾值設(shè)置過寬沒有觸發(fā)自動摘除。后來我把LatencyScore的異常閾值收緊并加了一條“連續(xù)5次P99延遲超過3秒就強制摘除”的規(guī)則這類故障現(xiàn)在基本幾秒內(nèi)就能自動隔離。還有個細節(jié)Agent端時間不同步會導致心跳時間錯亂。Reach校準時間是以自己的服務(wù)器時鐘為準Agent上報的時間僅作參考不參與租約計算。如果環(huán)節(jié)里有人直接用了Agent端的系統(tǒng)時間做過期判斷很容易出現(xiàn)誤殺或漏殺。后來我統(tǒng)一了所有服務(wù)的NTP同步租約計算只用Reach本地時間戳。6. 后續(xù)可以怎么擴展Agent-Reach現(xiàn)在對我這邊的多Agent平臺來說夠用了但有幾塊我還在籌劃升級。第一是加上容器化環(huán)境下的自動注冊K8s的Pod重建很快如果Reach沒有及時感知到新Pod注冊的實例流量會短暫丟失。我把這個做成一個單獨的控制器監(jiān)聽Pod的Ready狀態(tài)之后自動調(diào)用注冊接口。第二是路由策略加上語義標簽目前capability匹配是對標簽做集合運算下一步想接入向量相似度讓Agent能力描述更自然不再依賴人工打標。還有一個方向是給Agent做調(diào)用配額管理。目前Reach只管調(diào)度不管“誰來調(diào)”。如果某個調(diào)用方寫了個死循環(huán)瘋狂請求會把整個Agent池打爆。我計劃增加一個配額層按調(diào)用方身份限流類似網(wǎng)關(guān)里的Rate Limit避免單個調(diào)用方把基礎(chǔ)設(shè)施拖垮。不過這些都是迭代計劃當前的Agent-Reach已經(jīng)解決了最重要的問題Agent不再是一個個孤島而是能被統(tǒng)一發(fā)現(xiàn)、統(tǒng)一調(diào)度、統(tǒng)一治理的集群能力。如果你正好也在做類似的多Agent調(diào)度層建議先別急著堆功能把注冊協(xié)議、心跳租約、路由打分這三件事想透后面再加什么都順手。最后分享一個我自己的體會。做Agent基礎(chǔ)設(shè)施最忌諱的就是“把Agent當普通服務(wù)”來管理。Agent有狀態(tài)、有偏好、有性能差異單純用負載均衡的思路去路由短期能跑規(guī)模一大必然出問題。我這次把“Agent自身狀態(tài)上報”放到了調(diào)度決策的中心收到的效果比預想好得多。如果你也卡在Agent集群管理這塊可以試試從“讓Agent主動說自己的情況”這個思路入手很多調(diào)度難題會一下變得簡單很多。 Agent集群生產(chǎn)級接入層：服務(wù)發(fā)現(xiàn)、健康檢查與智能路由實戰(zhàn)
“Agent”這個詞這兩年快被說爛了。從AutoGPT到各類MCP、工作流編排框架大家都在談智能體但真落到業(yè)務(wù)里你會發(fā)現(xiàn)一個特別容易翻車的環(huán)節(jié)你的智能體跑起來了但你怎么知道它現(xiàn)在活著、在哪兒、能不能被調(diào)用、負載怎么樣你用OpenAI的API不會操心這個問題但自建Agent集群時這套“服務(wù)發(fā)現(xiàn)健康檢查路由調(diào)度”的東西基本上得從頭造一遍。我最近在內(nèi)部把這套基礎(chǔ)設(shè)施做完了項目代號就叫Agent-Reach。名字很直白意思就是“讓每一個Agent都能被準確觸達”。這篇文章把我這幾周的踩坑、設(shè)計取舍和落地實錄整理出來不聊虛的直接講怎么把一個Agent集群做成“有服務(wù)注冊、有健康探活、有智能路由”的生產(chǎn)級接入層。如果你正準備把Agent能力接入業(yè)務(wù)系統(tǒng)或者想給自己的多Agent項目加一層可靠調(diào)度這篇內(nèi)容對你會很有用。不用懂太深的后端知識我會盡量把每一層的設(shè)計邏輯和實現(xiàn)細節(jié)都講清楚。1. 項目初衷與整體設(shè)計思路Agent-Reach不是一個業(yè)務(wù)Agent它不負責對話、寫代碼、做規(guī)劃。它是一層基礎(chǔ)設(shè)施我們內(nèi)部叫它“觸點管理服務(wù)”。簡單說它解決三個問題Agent注冊、Agent發(fā)現(xiàn)、Agent路由。1.1 為什么需要專門的Reach層如果你只有一兩個Agent用配置文件寫死地址就夠了。但一旦Agent數(shù)量上到幾十個或者Agent分散在多臺服務(wù)器、多個K8s節(jié)點上問題馬上變麻煩。部署了新版本的話舊地址失效某臺機器負載過高某類任務(wù)必須由特定Agent處理Agent崩潰后流量還是往它那邊打。這些問題單靠配置管理和負載均衡器是擋不住的因為Agent有狀態(tài)、有類型、有容量差異不是普通的HTTP服務(wù)。我當時走訪了一圈團隊需求總結(jié)下來就是需要一個中間層讓上層應(yīng)用不必感知具體Agent實例的IP和狀態(tài)只按“能力名字”去調(diào)用剩下的尋址和調(diào)度全部交給這一層。這也是Agent-Reach最核心的設(shè)計目標。1.2 三層架構(gòu)的取舍我最初參考了微服務(wù)里注冊中心的成熟套路但Agent和微服務(wù)有一個關(guān)鍵差異微服務(wù)實例相對穩(wěn)定Agent的啟停要頻繁得多而且Agent對上下文和數(shù)據(jù)隔離的要求也更高。所以我沒有直接照搬Eureka或者Nacos而是做了一個偏輕量的三層模型接入層負責接收Agent上報的狀態(tài)信息包括心跳、能力說明、當前并發(fā)數(shù)、上下文長度調(diào)度層根據(jù)業(yè)務(wù)請求攜帶的能力標簽、優(yōu)先級、數(shù)據(jù)親和性在可用Agent列表里選一個最合適的實例緩存層把Agent狀態(tài)數(shù)據(jù)同步到本地內(nèi)存和Redis避免調(diào)度層每次做遠程調(diào)用使得請求路徑盡量短。這個設(shè)計的核心取舍是“以Agent自身狀態(tài)為中心”。調(diào)度器不主動刻板地輪詢一切選擇都以Agent最近一次上報的信息為準。上報的間隔越短調(diào)度越精準代價是Agent端壓力增大。我后來把默認心跳設(shè)成了5秒既不會漏判導致大規(guī)模誤剔除也不會因為上報太頻繁占滿Agent進程的資源。1.3 核心模塊拆解整體代碼可以分為四個模塊。注冊模塊負責接收Agent第一次上線的注冊請求寫入唯一實例ID、能力名、標簽和附加元數(shù)據(jù)探活模塊負責跟蹤每個Agent的續(xù)約超過租約時間就標記為失聯(lián)路由模塊負責按策略篩選可用實例并返回目標地址控制臺模塊提供一個極簡界面能實時看到各Agent的在線狀態(tài)和請求分布。注冊信息我用的是MySQL持久化但實時調(diào)度不查庫只在Agent狀態(tài)變更時才寫庫。這樣設(shè)計的好處是調(diào)度路徑上完全無SQL操作性能瓶頸基本就剩下網(wǎng)絡(luò)開銷了。實際壓測下來單機調(diào)度層QPS能到1.2萬左右對于內(nèi)部工具來說非常夠用。2. 核心機制注冊、?；钆c可達性判定Agent-Reach的關(guān)鍵在于“可達性判定”。這是所有調(diào)度邏輯的地基一旦誤判下游所有策略都會出問題。我把它細分成注冊協(xié)議、心跳租約、狀態(tài)摘除三個子環(huán)節(jié)。2.1 Agent注冊協(xié)議設(shè)計Agent首次啟動時調(diào)用Reach的注冊接口上報自己的實例名、Agent類型、可以處理的技能標簽、限制信息最大并發(fā)數(shù)、單次任務(wù)最長執(zhí)行時間、支持的大模型類型等。注冊完成之后Reach會返回一個instanceId和一個臨時token后續(xù)的心跳和上下線都帶這個token防止偽造上報。注冊信息里有一項我覺得特別重要preferred_regions。這是Agent所在的物理或邏輯區(qū)域標識。比如我的Agent分布在兩個內(nèi)網(wǎng)網(wǎng)段一部分在GPU區(qū)一部分在通用計算區(qū)。當業(yè)務(wù)請求帶有數(shù)據(jù)本地性要求時調(diào)度器能根據(jù)這個字段避開跨網(wǎng)段傳輸省掉大量數(shù)據(jù)搬遷開銷。注冊接口本身冪等性很好做因為instanceId由Agent自己生成一般是hostname進程ID隨機數(shù)Reach側(cè)按這個ID做upsert。第一次上線是insert后續(xù)重復注冊就是update元數(shù)據(jù)。實測中重復注冊主要發(fā)生在Agent崩潰重啟或網(wǎng)絡(luò)閃斷后重連冪等設(shè)計省了前端很多事。2.2 心跳與租約機制心跳接口我設(shè)計得比較簡Agent每隔5秒打一次BeaconBody里只帶instanceId、當前狀態(tài)BUSY或IDLE、當前并發(fā)任務(wù)數(shù)、最近一次任務(wù)耗時。Reach收到心跳后刷新這條Agent的最后更新時間并同步更新內(nèi)存里的狀態(tài)快照。租約機制參考了分布式系統(tǒng)里常見的TTL思路。Reach指定一個leaseDuration默認是15秒。如果15秒內(nèi)沒有收到某實例的心跳就判定該實例失聯(lián)將其從可用池子摘除。同時摘除動作只是把status置為OFFLINE記錄摘除原因和時間并不刪除注冊記錄這樣網(wǎng)絡(luò)抖動恢復后Agent重新上報心跳就能自動回池不需要再次全量注冊。這個設(shè)計有個細節(jié)值得注意心跳不能一過期就殺。瞬斷很常見Agent可能只是暫停了3秒的GC或一次長任務(wù)阻塞。所以我把狀態(tài)切換做成三級HEALTHY、SUSPECT、OFFLINE。超過15秒沒心跳進SUSPECT轉(zhuǎn)發(fā)時標記“降級權(quán)重”但還能接收輕量請求超過30秒還沒心跳才真正摘除。這個緩沖讓系統(tǒng)在波動時穩(wěn)定很多尤其能扛住Agent JVM導致的偶發(fā)停頓。2.3 狀態(tài)摘除與優(yōu)雅下線除了被動摘除Agent還可能主動下線比如發(fā)布新版本時需要排空流量。我預留了一個下線路由Agent調(diào)用/offline接口聲明“我要離線了”Reach把這個實例從可用列表里立刻摘掉但保留已有請求執(zhí)行完。這就避免新流量進入正在重啟的進程。這里踩過一個坑Agent進程在卸載鉤子里調(diào)用offline但進程退出太快HTTP調(diào)用還沒發(fā)出去就斷了。后來我把下線動作做了兩級保障——先標記本進程為“停止接收新任務(wù)”再發(fā)離線請求同時本地維持10秒的grace period確保離線請求在進程真正退出前送達。對于極端場景比如機器斷電那就只能等心跳過期被動摘除了這類情況沒辦法完全避免。3. 路由策略與調(diào)度實現(xiàn)Agent-Reach真正花時間的是路由模塊。它不能隨便挑一個健康實例就算完事而要支持多維度約束。我把調(diào)度拆成“過濾打分選擇”三段每一段都有背后邏輯。3.1 過濾階段先排除不可用實例過濾規(guī)則按優(yōu)先級執(zhí)行第一層過濾是不可用狀態(tài)包括OFFLINE和SUSPECT第二層過濾是能力匹配業(yè)務(wù)請求里的capability字段必須與Agent支持的技能標簽交集非空第三層過濾是數(shù)據(jù)親和性如果請求指定了data_region就只保留該區(qū)域的Agent最后一層是并發(fā)水位過濾Agent當前并發(fā)數(shù)和最大并發(fā)比例超過0.85就臨時不參與調(diào)度。實際使用下來并發(fā)水位過濾是最影響結(jié)果質(zhì)量的。以前沒加這項時某個Agent可能已經(jīng)被壓滿調(diào)度器還是往里扔任務(wù)導致響應(yīng)時長一下子拉胯。加了之后系統(tǒng)會自動把熱點Agent留一口氣處理已有任務(wù)新任務(wù)分散到其他實例上。代價是小部分請求會跑到較遠的區(qū)域但相比整體延遲劣化這個代價完全值得。3.2 打分階段量化每個候選Agent的適配度過濾只剩健康實例后進入打分環(huán)節(jié)。打分函數(shù)我用的加權(quán)綜合公式Score 0.35 * ConcurrencyScore 0.30 * AffinityScore 0.20 * LatencyScore 0.15 * StabilityScoreConcurrencyScore是剩余并發(fā)容量的歸一化值A(chǔ)ffinityScore看的是候選Agent的歷史調(diào)用記錄如果有過去5分鐘內(nèi)成功處理過同一類請求就加分LatencyScore取最近100次任務(wù)的P50執(zhí)行耗時耗時越低分越高StabilityScore看的是近一小時GC暫停次數(shù)、內(nèi)存增長趨勢、注意這里是Agent運行時統(tǒng)計上來的指標不是Reach自己猜的。這個公式不是一開始就定死的。最初我把穩(wěn)定性的權(quán)重設(shè)為0結(jié)果某個Agent因為內(nèi)存泄漏導致頻繁FullGC調(diào)度器毫不知情照樣把任務(wù)給它直到請求超時才發(fā)現(xiàn)。后來加入了穩(wěn)定性指標并在控制臺打了一個“GC風暴”告警這類問題才被提前攔下。3.3 選擇階段隨機加權(quán)與親和保持得分算完后自然是用加權(quán)隨機選擇而不是直接選最高分。原因很簡單如果始終選最高分實例所有流量會在瞬間集中到同一批Agent上很快就把它們打熱然后又被并發(fā)過濾防住導致“熱點漂移”。加權(quán)隨機讓高分實例有更高概率被選中但低分實例也有少量機會整體分布更平滑。這里還有一個“親和保持”的細節(jié)如果請求的traceId之前已經(jīng)固定到了一個Agent實例且該實例仍然健康我會把它直接返回不加額外計算。這保證同一用戶會話盡量在一個Agent上完成避免上下文反復搬運。親和保持出過一次問題agent實例因網(wǎng)絡(luò)瞬斷進入SUSPECT狀態(tài)但親和策略還把它返回給調(diào)用方導致一批請求全部失敗。修復方法是在親和命中后增加一個快速狀態(tài)校驗SUSPECT直接跳過親和。這個邏輯是給調(diào)度器加了一行判斷但實際收益很明顯故障恢復速度從分鐘級降到了秒級。4. 實操落地從零搭建Agent-Reach理論講完了分享點直接能上手的操作。我用Go寫了Reach服務(wù)端Agent端SDK用了Python因為現(xiàn)在大部分Agent框架的膠水層還是Python多點。下面把關(guān)鍵環(huán)節(jié)列一下照著做基本能跑通。4.1 服務(wù)端核心代碼骨架Reach的服務(wù)端入口我用了Gin框架數(shù)據(jù)庫用MySQL緩存用了Redis和內(nèi)存混合。核心調(diào)度邏輯不依賴RedisRedis只用于跨節(jié)點同步和審計日志。代碼結(jié)構(gòu)比較清晰核心就兩個接口注冊和心跳。// 注冊Agent r.POST(/api/agent/register, func(c *gin.Context) { var req RegisterRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } id : registry.Register(req) c.JSON(200, gin.H{instance_id: id, token: registry.GenToken(id)}) }) // 心跳上報 r.POST(/api/agent/beacon, func(c *gin.Context) { var req BeaconRequest if err : c.ShouldBindJSON(req); err ! nil { c.JSON(400, gin.H{error: err.Error()}) return } registry.Heartbeat(req.InstanceID, req.Status) c.JSON(200, gin.H{ok: true}) })心跳接口沒有做復雜的鑒權(quán)只校驗了token前綴的合法性因為Agent端和Reach端都在內(nèi)網(wǎng)且中間有防火墻規(guī)則依賴內(nèi)網(wǎng)信任可以降低不少通信開銷。調(diào)度查詢接口是另一個重點。上層應(yīng)用傳入的調(diào)用ID其實是capabilityNameReach根據(jù)它選好Agent后返回完整的調(diào)用地址和參數(shù)模板。# 偽代碼簡化突出調(diào)度流程 def schedule_request(capability: str, context: dict) - AgentTarget: pool registry.get_candidates(capability) if not pool: raise NoAvailableAgentError(capability) filtered filter_by_health(pool) filtered filter_by_capacity(filtered) pool_with_score [(agent, compute_score(agent, context)) for agent in filtered] return weighted_choose(pool_with_score)4.2 Agent端SDK接入要點Agent端SDK封裝了注冊、心跳、狀態(tài)上報三個動作。我建議把SDK設(shè)計成啟動時自動異步注冊不阻塞Agent主流程。試用的時候發(fā)現(xiàn)如果注冊失敗直接拋異常很多Agent啟動邏輯會被卡住所以我改成“注冊失敗進入重試隊列不影響本地執(zhí)行”的模式。心跳邏輯用后臺線程實現(xiàn)每次打心跳時順帶傳最近一次任務(wù)執(zhí)行耗時。這里要強調(diào)任務(wù)耗時的統(tǒng)計口徑必須準我遇到過Agent端把排隊時間也算進執(zhí)行耗時導致Reach端的LatencyScore完全失真。后來規(guī)范了字段task_duration_ms只算真正執(zhí)行時間排隊和網(wǎng)絡(luò)傳輸時間都單獨上報。class AgentReachSDK: def start(self): threading.Thread(targetself._beacon_loop, daemonTrue).start() self.register() def _beacon_loop(self): while True: self.report_state() time.sleep(5)這里還有一個經(jīng)驗值心跳線程的網(wǎng)絡(luò)超時時間不要設(shè)置太長建議2秒以內(nèi)。如果Reach端整個宕機Agent不該無限等網(wǎng)絡(luò)響應(yīng)而是降級成本地模式保留Agent獨立工作的能力。畢竟Reach掛了業(yè)務(wù)Agent還能干活等到Reach恢復再做補償注冊就行。4.3 控制臺與可觀測性Reach控制臺有一個實時視圖能看到所有Agent實例的列表每行帶狀態(tài)、最近心跳時間、當前并發(fā)、24小時成功率。這個視圖對運維特別有用基本能替代一大部分調(diào)試工作。另外我加了一個事件流頁面所有Agent的注冊、失聯(lián)、恢復、路由變更都在頁面上滾動顯示。排查問題的時候按時間軸看事件流比看日志快很多。比如某個時刻調(diào)度變慢往上查一下往往能看到某臺機器因為GC發(fā)生SUSPECT再結(jié)合日志確認就是那次事件引起的連鎖反應(yīng)。5. 常見問題與排查經(jīng)驗速查這幾周實際跑下來遇到的問題比預想的多。我挑了些有代表性的做成表格方便速查。現(xiàn)象可能原因排查手段Agent列表全部脫機Reach服務(wù)端與數(shù)據(jù)庫連接斷開檢查MySQL連接池心跳寫庫失敗導致判定全部失聯(lián)偶發(fā)請求打到已下線的Agent親和保持跳過了SUSPECT校驗確認親和命中后的狀態(tài)二次檢查邏輯是否生效調(diào)度結(jié)果總集中到同一實例打分函數(shù)內(nèi)緩存被人為刪掉檢查Redis緩存失效策略確認實例分數(shù)未過期心跳正常但請求超時Agent實例已阻塞但心跳線程仍能執(zhí)行查看實例執(zhí)行池線程消耗增加單獨的執(zhí)行狀態(tài)上報注冊接口偶發(fā)503注冊并發(fā)量過大數(shù)據(jù)庫寫沖突注冊寫庫改為異步批量同步注冊接口改為最終一致除了表格里這些還有一個非常值得說的坑Agent上線時如果注冊得太快下一條心跳還沒跟上Reach端可能會把它認成“新實例但從未活躍”然后被租約機制誤判剔除。我的解決辦法是在注冊接口返回后代理端以此為起點立刻打一條帶initialtrue的心跳。這條心跳不參與正常租約計算只用于確認“我確實活了”。還有一個和Agent調(diào)度強相關(guān)的問題——線程池阻塞。曾有一個Agent實例的心跳一直正常但它內(nèi)部處理請求的線程池全部阻塞新請求進入后排隊耗時指數(shù)級增長。Reach的P50耗時指標很快捕捉到了異常但由于閾值設(shè)置過寬沒有觸發(fā)自動摘除。后來我把LatencyScore的異常閾值收緊并加了一條“連續(xù)5次P99延遲超過3秒就強制摘除”的規(guī)則這類故障現(xiàn)在基本幾秒內(nèi)就能自動隔離。還有個細節(jié)Agent端時間不同步會導致心跳時間錯亂。Reach校準時間是以自己的服務(wù)器時鐘為準Agent上報的時間僅作參考不參與租約計算。如果環(huán)節(jié)里有人直接用了Agent端的系統(tǒng)時間做過期判斷很容易出現(xiàn)誤殺或漏殺。后來我統(tǒng)一了所有服務(wù)的NTP同步租約計算只用Reach本地時間戳。6. 后續(xù)可以怎么擴展Agent-Reach現(xiàn)在對我這邊的多Agent平臺來說夠用了但有幾塊我還在籌劃升級。第一是加上容器化環(huán)境下的自動注冊K8s的Pod重建很快如果Reach沒有及時感知到新Pod注冊的實例流量會短暫丟失。我把這個做成一個單獨的控制器監(jiān)聽Pod的Ready狀態(tài)之后自動調(diào)用注冊接口。第二是路由策略加上語義標簽目前capability匹配是對標簽做集合運算下一步想接入向量相似度讓Agent能力描述更自然不再依賴人工打標。還有一個方向是給Agent做調(diào)用配額管理。目前Reach只管調(diào)度不管“誰來調(diào)”。如果某個調(diào)用方寫了個死循環(huán)瘋狂請求會把整個Agent池打爆。我計劃增加一個配額層按調(diào)用方身份限流類似網(wǎng)關(guān)里的Rate Limit避免單個調(diào)用方把基礎(chǔ)設(shè)施拖垮。不過這些都是迭代計劃當前的Agent-Reach已經(jīng)解決了最重要的問題Agent不再是一個個孤島而是能被統(tǒng)一發(fā)現(xiàn)、統(tǒng)一調(diào)度、統(tǒng)一治理的集群能力。如果你正好也在做類似的多Agent調(diào)度層建議先別急著堆功能把注冊協(xié)議、心跳租約、路由打分這三件事想透后面再加什么都順手。最后分享一個我自己的體會。做Agent基礎(chǔ)設(shè)施最忌諱的就是“把Agent當普通服務(wù)”來管理。Agent有狀態(tài)、有偏好、有性能差異單純用負載均衡的思路去路由短期能跑規(guī)模一大必然出問題。我這次把“Agent自身狀態(tài)上報”放到了調(diào)度決策的中心收到的效果比預想好得多。如果你也卡在Agent集群管理這塊可以試試從“讓Agent主動說自己的情況”這個思路入手很多調(diào)度難題會一下變得簡單很多。