1. 從一場(chǎng)聯(lián)調(diào)事故說(shuō)起Agent 之間為什么總失聯(lián)上個(gè)月我們內(nèi)部做一次多 Agent 協(xié)作的壓測(cè)場(chǎng)景很簡(jiǎn)單一個(gè)規(guī)劃 Agent 接到用戶需求后拆出三個(gè)子任務(wù)分發(fā)給檢索 Agent、代碼生成 Agent 和質(zhì)檢 Agent。聽起來(lái)很常規(guī)對(duì)吧結(jié)果第一次跑通就翻了車。規(guī)劃 Agent 拿著子任務(wù)的執(zhí)行結(jié)果去做匯總發(fā)現(xiàn)三個(gè)子 Agent 的響應(yīng)里有兩個(gè)超時(shí)一個(gè)返回了別的主線的中間結(jié)果。日志里全是Connection refused和Task not found。當(dāng)時(shí)我們幾個(gè)工程師對(duì)著監(jiān)控面板面面相覷每個(gè) Agent 單測(cè)都是好的服務(wù)也都活著為什么一協(xié)作就變成一鍋粥問(wèn)題出在一個(gè)被絕大多數(shù)人忽視的環(huán)節(jié)Agent 之間的尋址和投遞完全是裸奔的。單體 Agent 內(nèi)部怎么調(diào)函數(shù)都行一旦拆成多個(gè) Agent 獨(dú)立部署、各自維護(hù)狀態(tài)你面對(duì)的就是一個(gè)分布式系統(tǒng)最經(jīng)典的三個(gè)難題——服務(wù)發(fā)現(xiàn)、可靠投遞、失敗恢復(fù)。當(dāng)時(shí)市面上有不少編排框架但要么太重強(qiáng)制你上全套工作流引擎要么太輕只做 HTTP 轉(zhuǎn)發(fā)真正適合中小團(tuán)隊(duì)自建 Agent 網(wǎng)絡(luò)的通信底座幾乎是空白。我花了三周時(shí)間寫了一個(gè)叫 Agent-Reach 的協(xié)調(diào)層組件用來(lái)解決上面這堆破事。這篇文章就把它的設(shè)計(jì)思路、核心實(shí)現(xiàn)、以及我在真實(shí)壓測(cè)中踩過(guò)的坑全部攤開講。適合正在搭多 Agent 系統(tǒng)、被互聯(lián)互通折磨得想罵人的同學(xué)參考。它不是銀彈但能讓你從天天救火變成睡個(gè)安穩(wěn)覺。2. 設(shè)計(jì)之前先把Agent 通信這件事拆明白2.1 三種通信模式你混用了嗎動(dòng)手寫代碼之前我先把 Agent 之間的通信模式梳理了一遍。幾乎所有協(xié)作場(chǎng)景都逃不出這三種第一種是請(qǐng)求-響應(yīng)規(guī)劃 Agent 派活給執(zhí)行 Agent等它干完把結(jié)果拿回來(lái)。這是最常見的模式也是最容易出問(wèn)題的因?yàn)橐淮握?qǐng)求的完整鏈路包含派活、執(zhí)行、回傳、確認(rèn)任何一環(huán)斷了對(duì)調(diào)用方來(lái)說(shuō)都是超時(shí)。第二種是事件廣播比如一個(gè) Agent 監(jiān)測(cè)到配置變更需要通知所有相關(guān) Agent 刷新緩存。這種模式對(duì)送達(dá)的要求沒(méi)那么嚴(yán)格漏一兩個(gè)訂閱方可以接受但你不能把關(guān)鍵事件也做成廣播——那純粹是給自己埋雷。第三種是流式推送適合長(zhǎng)時(shí)間運(yùn)行的任務(wù)比如代碼生成 Agent 每產(chǎn)出一個(gè)文件就往倉(cāng)庫(kù) Agent 推一條消息。流式場(chǎng)景里真正難的不是推而是斷點(diǎn)續(xù)傳和消費(fèi)位點(diǎn)管理。Agent-Reach 的核心思路很簡(jiǎn)單所有模式統(tǒng)一抽象成消息只不過(guò)消息的投遞語(yǔ)義不同。請(qǐng)求-響應(yīng)是request類型廣播是event類型流式推送是stream類型再加上一個(gè)ack類型專門做確認(rèn)回執(zhí)。類型一收攏后面的存儲(chǔ)、路由、重試邏輯就都能統(tǒng)一處理了。當(dāng)時(shí)我自己的踩坑經(jīng)歷是第一版把所有通信都 HTTP 同步調(diào)以為最簡(jiǎn)單。結(jié)果廣播一多Agent 之間互相等鏈路一長(zhǎng)就雪崩。后來(lái)才意識(shí)到同步調(diào)用只能用于請(qǐng)求-響應(yīng)事件廣播和流式推送必須走異步隊(duì)列這是架構(gòu)層面的紅線不是優(yōu)化層面的喜好。2.2 注冊(cè)中心不Agent-Reach 用路由表 租約很多人的第一反應(yīng)是上 ZooKeeper 或者 etcd 做服務(wù)發(fā)現(xiàn)。但我做 Agent-Reach 時(shí)的約束條件很明確不想引入額外的基礎(chǔ)設(shè)施團(tuán)隊(duì)里沒(méi)人愿意專門維護(hù)一個(gè)注冊(cè)中心集群。所以我把服務(wù)發(fā)現(xiàn)做成了基于租約lease的輕量路由表直接嵌在協(xié)調(diào)節(jié)點(diǎn)進(jìn)程里。每個(gè) Agent 啟動(dòng)時(shí)向 Agent-Reach 的協(xié)調(diào)節(jié)點(diǎn)注冊(cè)自己注冊(cè)信息包括Agent 編號(hào)、服務(wù)名、能力標(biāo)簽比如capability:codegen、回調(diào)地址、以及一個(gè) TTL 租約。協(xié)調(diào)節(jié)點(diǎn)維護(hù)一張內(nèi)存路由表Agent 每隔 TTL/2 的時(shí)間續(xù)租一次。租約過(guò)期沒(méi)續(xù)上路由表就把這個(gè) Agent 標(biāo)記為不可用再等一個(gè)寬限期就徹底剔除。這套機(jī)制跟注冊(cè)中心比犧牲了跨節(jié)點(diǎn)容災(zāi)和歷史變更追溯換來(lái)了零依賴、毫秒級(jí)感知故障對(duì)小規(guī)模 Agent 網(wǎng)絡(luò)幾十個(gè)節(jié)點(diǎn)以內(nèi)完全夠用。你要問(wèn)我什么時(shí)候該上 etcd當(dāng) Agent 數(shù)量超過(guò)一百、協(xié)調(diào)節(jié)點(diǎn)需要多活、或者你需要嚴(yán)格的版本兼容管理的時(shí)候再考慮不遲。路由表里還有一個(gè)容易被忽略的設(shè)計(jì)能力路由。調(diào)用方不指定具體 Agent 編號(hào)只聲明我要一個(gè)能做代碼生成的 Agent。協(xié)調(diào)節(jié)點(diǎn)會(huì)根據(jù)能力標(biāo)簽、當(dāng)前負(fù)載、租約新鮮度三個(gè)維度打分選一個(gè)最合適的投遞目標(biāo)。這個(gè)設(shè)計(jì)讓 Agent 網(wǎng)絡(luò)具備了一定的彈性——某個(gè) Agent 掛了能力路由會(huì)自動(dòng)把任務(wù)分給同能力的另一臺(tái)。2.3 為什么必須引入收件箱我見過(guò)不少團(tuán)隊(duì)做 Agent 通信直接在回調(diào)地址上做 POST然后把任務(wù) ID 掛在 URL 上。表面看能跑但有一個(gè)致命問(wèn)題Agent 執(zhí)行任務(wù)期間可能重啟、可能斷網(wǎng)重啟之后回調(diào)地址可能都變了。這時(shí)候任務(wù)狀態(tài)就丟了你根本不知道它執(zhí)行到哪一步。Agent-Reach 給每個(gè) Agent 維護(hù)一個(gè)持久化收件箱。所有發(fā)往該 Agent 的消息先進(jìn)收件箱Agent 處理完一條彈出一條。收件箱的存儲(chǔ)我用的是本地嵌入式數(shù)據(jù)庫(kù)SQLite 就夠用單機(jī)場(chǎng)景沒(méi)必要上 PostgreSQL每條消息記錄message_id、type、payload、status、create_time、attempts六個(gè)字段。消息的流轉(zhuǎn)狀態(tài)機(jī)是pending → processing → done或者pending → processing → failed → pending待重試。收件箱的價(jià)值在于Agent 的消費(fèi)進(jìn)度不依賴進(jìn)程內(nèi)存重啟后從數(shù)據(jù)庫(kù)里接著干。這本質(zhì)上就是 Outbox 模式在 Agent 場(chǎng)景的應(yīng)用。我當(dāng)時(shí)想明白這一點(diǎn)之后很多任務(wù)神秘消失的問(wèn)題都迎刃而解了。3. Agent-Reach 的核心實(shí)現(xiàn)注冊(cè)、路由、投遞、回執(zhí)3.1 注冊(cè)與租約續(xù)期的代碼骨架Agent 端的啟動(dòng)注冊(cè)邏輯我用 Python 寫了個(gè)示例實(shí)際項(xiàng)目里不管什么語(yǔ)言套路是一樣的import asyncio import time import httpx class AgentClient: def __init__(self, agent_id, coordinator_url, callback_url, ttl30): self.agent_id agent_id self.coordinator_url coordinator_url self.callback_url callback_url self.ttl ttl self.lease_task None async def register(self, capabilities): payload { agent_id: self.agent_id, callback_url: self.callback_url, capabilities: capabilities, ttl: self.ttl } async with httpx.AsyncClient() as client: resp await client.post(f{self.coordinator_url}/register, jsonpayload) if resp.status_code 200: self.lease_task asyncio.create_task(self._keep_lease()) async def _keep_lease(self): interval self.ttl / 2 while True: await asyncio.sleep(interval) async with httpx.AsyncClient() as client: await client.post( f{self.coordinator_url}/renew, json{agent_id: self.agent_id} )這里有一個(gè)細(xì)節(jié)續(xù)租間隔我特意設(shè)為 TTL 的一半而不是 TTL。網(wǎng)絡(luò)抖動(dòng)是常態(tài)如果間隔設(shè)成接近 TTL一次偶發(fā)超時(shí)就會(huì)導(dǎo)致 Agent 被誤判下線然后能力路由把任務(wù)發(fā)給別的 Agent造成重復(fù)執(zhí)行。TTL30 秒、每 15 秒續(xù)租一次既能容忍一定網(wǎng)絡(luò)波動(dòng)又能讓故障感知控制在 30 秒內(nèi)算是一個(gè)經(jīng)過(guò)壓測(cè)驗(yàn)證的平衡值。協(xié)調(diào)節(jié)點(diǎn)那端維護(hù)租約的數(shù)據(jù)結(jié)構(gòu)也很直接class LeaseRegistry: def __init__(self): # agent_id - {capabilities, callback_url, last_renew, status} self.agents {} def renew(self, agent_id): if agent_id in self.agents: self.agents[agent_id][last_renew] time.time() self.agents[agent_id][status] online def sweep(self, now, ttl, grace_period): # 定期清掃過(guò)期租約 for agent_id in list(self.agents.keys()): last self.agents[agent_id][last_renew] if now - last ttl: self.agents[agent_id][status] suspect if now - last ttl grace_period: del self.agents[agent_id]grace_period這個(gè)參數(shù)我吃過(guò)虧后面專門講。現(xiàn)在先記住一個(gè)原則判定下線要慢標(biāo)記可疑要快真正剔除要更慢。寧可讓一個(gè) Agent 被短暫重復(fù)投遞也不能讓一個(gè)活著的 Agent 被永久剔除。3.2 消息投遞的三段式入隊(duì)、分揀、回執(zhí)消息從調(diào)用方發(fā)出到被 Agent 消費(fèi)Agent-Reach 的處理管線是三段式的第一段入隊(duì)。調(diào)用方調(diào)用POST /dispatch協(xié)調(diào)節(jié)點(diǎn)把消息寫入目標(biāo) Agent 的收件箱狀態(tài)置為pending然后立刻返回一個(gè)message_id。注意這里不是同步轉(zhuǎn)發(fā)無(wú)論目標(biāo) Agent 是否在線消息都已經(jīng)落庫(kù)了。這個(gè)設(shè)計(jì)保證調(diào)用方不需要等目標(biāo) Agent 就緒消息一定不會(huì)丟。第二段分揀。Agent 端有一個(gè)長(zhǎng)輪詢的消費(fèi)者線程每隔幾百毫秒向協(xié)調(diào)節(jié)點(diǎn)拉取自己收件箱里statuspending的消息。為什么用拉而不是推因?yàn)橥颇Ｊ较?Agent 重啟期間推送的消息會(huì)堆積在協(xié)調(diào)節(jié)點(diǎn)的內(nèi)存緩沖里Agent 恢復(fù)后容易重復(fù)消費(fèi)或漏消費(fèi)。拉模式天然支持?jǐn)帱c(diǎn)續(xù)傳Agent 重啟后從數(shù)據(jù)庫(kù)里恢復(fù)自己的消費(fèi)位點(diǎn)再繼續(xù)拉。這就是前面說(shuō)收件箱的價(jià)值落地。第三段回執(zhí)。Agent 處理完消息后調(diào)用POST /ack傳message_id和處理結(jié)果。協(xié)調(diào)節(jié)點(diǎn)把消息狀態(tài)從processing改為done。如果 Agent 處理失敗調(diào)用POST /nack協(xié)調(diào)節(jié)點(diǎn)根據(jù)attempts字段判斷是重試還是進(jìn)入死信。調(diào)用方怎么拿到最終結(jié)果每個(gè)request類型消息都有一個(gè)reply_to字段指向調(diào)用方自己的收件箱。目標(biāo) Agent 處理完結(jié)果作為一條reply消息進(jìn)調(diào)用方的收件箱調(diào)用方拉取即可。你會(huì)發(fā)現(xiàn)每個(gè) Agent 既是消息的生產(chǎn)者也是消費(fèi)者整個(gè)網(wǎng)絡(luò)是對(duì)稱的。這個(gè)設(shè)計(jì)讓 Agent-Reach 天然支持多級(jí)流水線Agent A 派活給 BB 的回復(fù)進(jìn) A 的收件箱A 繼續(xù)往下派。3.3 重試策略指數(shù)退避與死信隊(duì)列消息重試是最容易拍腦袋設(shè)計(jì)的部分。我第一版寫的是固定間隔重試 3 次每次間隔 5 秒。實(shí)測(cè)下來(lái)問(wèn)題很大如果目標(biāo)服務(wù)因?yàn)檫^(guò)載而拒絕固定 5 秒重試三次等于在人家最忙的時(shí)候又捅了三刀。正確姿勢(shì)是指數(shù)退避加抖動(dòng)。重試間隔 base_interval * 2^attempt再乘以一個(gè)隨機(jī)因子比如在 0.8 到 1.2 之間浮動(dòng)。base_interval 建議 2 秒起最大間隔封頂 120 秒。同時(shí)設(shè)置max_attempts超過(guò)之后進(jìn)死信隊(duì)列由人工或其他兜底 Agent 處理。這是我實(shí)測(cè)下來(lái)的重試參數(shù)表可以直接抄參數(shù)值說(shuō)明base_interval2s首次重試的基礎(chǔ)等待時(shí)間max_interval120s重試間隔封頂避免無(wú)限拉長(zhǎng)backoff_factor2指數(shù)增長(zhǎng)的底數(shù)jitter0.8 ~ 1.2隨機(jī)抖動(dòng)避免驚群max_attempts5超過(guò)進(jìn)死信隊(duì)列dead_letter_ttl7d死信消息保留時(shí)間還有一個(gè)坑重試要盡量在協(xié)調(diào)節(jié)點(diǎn)做不要在 Agent 端做。如果你讓 Agent 自己重試Agent 重啟后重試狀態(tài)就丟了而且無(wú)法全局控制重試頻率。協(xié)調(diào)節(jié)點(diǎn)統(tǒng)一管重試才能和路由表聯(lián)動(dòng)——目標(biāo) Agent 已經(jīng)下線了就直接把消息重新路由給另一個(gè)能力相同的 Agent而不是傻等。4. 壓測(cè)中踩過(guò)的三個(gè)坑你以為穩(wěn)了其實(shí)全是隱患4.1 坑一租約寬限期設(shè)置不當(dāng)導(dǎo)致的腦裂式重復(fù)消費(fèi)第一次壓測(cè)跑 50 個(gè)并發(fā)任務(wù)時(shí)我觀察到一個(gè)詭異現(xiàn)象同一份任務(wù)被執(zhí)行了兩遍而且兩個(gè)執(zhí)行 Agent 都不認(rèn)為自己有問(wèn)題。查下來(lái)的根因是租約寬限期設(shè)太短。我當(dāng)時(shí) TTL 設(shè) 15 秒寬限期設(shè) 5 秒。某次壓測(cè)時(shí)協(xié)調(diào)節(jié)點(diǎn)的 GC 停頓了 8 秒期間所有 Agent 的續(xù)租請(qǐng)求都沒(méi)處理。等 GC 結(jié)束協(xié)調(diào)節(jié)點(diǎn)認(rèn)為所有 Agent 都過(guò)期了把任務(wù)重新路由給備用 Agent。原 Agent 其實(shí)只是沒(méi)續(xù)上租任務(wù)還在正常執(zhí)行于是兩邊同時(shí)處理產(chǎn)生重復(fù)結(jié)果。修復(fù)方案分兩層。第一層寬限期改成 TTL 的兩倍也就是至少 30 秒讓 GC 之類的偶發(fā)停頓不至于引起大規(guī)模誤判。第二層投遞時(shí)帶上execution_tokenAgent 每次真正開始執(zhí)行前要把 token 從pending搶到processing這個(gè)操作是原子的。誰(shuí)搶到 token 誰(shuí)執(zhí)行搶不到的自動(dòng)放棄。這相當(dāng)于給消息投遞加了一把分布式鎖重復(fù)路由的問(wèn)題從根上被堵住了。4.2 坑二Agent 間循環(huán)調(diào)用引發(fā)的消息風(fēng)暴Agent 協(xié)作系統(tǒng)有一個(gè)特別隱蔽的陷阱循環(huán)調(diào)用。A 給 B 派活B 處理不了轉(zhuǎn)給 CC 覺得應(yīng)該找 A于是一圈一圈轉(zhuǎn)下去。由于每條消息都在收件箱里有記錄這個(gè)循環(huán)不會(huì)造成傳統(tǒng)意義上的死循環(huán)——它是會(huì)結(jié)束的但每一步都在產(chǎn)生新消息最終把協(xié)調(diào)節(jié)點(diǎn)的消息表?yè)蔚綆资f(wàn)行。我在壓測(cè)里設(shè)計(jì)了一個(gè)查不到數(shù)據(jù)就轉(zhuǎn)給上一個(gè) Agent 補(bǔ)充的流程結(jié)果三條消息在四個(gè) Agent 之間轉(zhuǎn)了幾十輪消息表膨脹到十幾萬(wàn)條SQLite 的寫入性能崩了。解法有兩個(gè)缺一不可。第一個(gè)是跳數(shù)上限每條消息加一個(gè)max_hops字段默認(rèn) 10每經(jīng)過(guò)一次轉(zhuǎn)發(fā)減一歸零就把消息丟進(jìn)死信。第二個(gè)是轉(zhuǎn)發(fā)軌跡追蹤協(xié)調(diào)節(jié)點(diǎn)在消息的trace字段里記錄所有經(jīng)過(guò)的 Agent 編號(hào)每次轉(zhuǎn)發(fā)前檢查 trace如果發(fā)現(xiàn)目標(biāo) Agent 已經(jīng)在自己這條軌跡里說(shuō)明出現(xiàn)了環(huán)直接終止并告警。這兩個(gè)機(jī)制加起來(lái)循環(huán)調(diào)用最多造成一條死信消息不會(huì)拖垮整個(gè)系統(tǒng)。4.3 坑三回調(diào)地址漂移收件箱成了幽靈信筒第三個(gè)坑來(lái)自一個(gè)很日常的操作某個(gè) Agent 因?yàn)橐獢U(kuò)容用同樣的 Agent ID 在新機(jī)器上重新部署。新機(jī)器 IP 變了回調(diào)地址自然變了。老機(jī)器的進(jìn)程沒(méi)完全退干凈還在續(xù)租于是路由表里出現(xiàn)了兩個(gè)相同 Agent ID 的條目一個(gè)指向新地址一個(gè)指向舊地址。舊地址的收件箱消息全部投遞失敗新地址的 Agent 卻完全不知道有人給它發(fā)過(guò)消息。排查了很久才發(fā)現(xiàn)問(wèn)題出在注冊(cè)協(xié)議太寬松Agent ID 相同就直接覆蓋注冊(cè)信息不做版本校驗(yàn)。修復(fù)方案是給注冊(cè)請(qǐng)求加一個(gè)instance_id機(jī)器級(jí)唯一 ID協(xié)調(diào)節(jié)點(diǎn)發(fā)現(xiàn)同一 Agent ID 重復(fù)注冊(cè)時(shí)強(qiáng)制要求新的注冊(cè)帶上epoch字段epoch 必須大于舊實(shí)例否則拒絕。老實(shí)例的租約續(xù)期請(qǐng)求也會(huì)被拒絕因?yàn)樗鼣y帶的 instance_id 已經(jīng)不是當(dāng)前活躍實(shí)例了。這個(gè)坑給我的教訓(xùn)是Agent ID 只能標(biāo)識(shí)邏輯身份不能標(biāo)識(shí)物理實(shí)例。凡是涉及物理實(shí)例的注冊(cè)、續(xù)租、回調(diào)都必須以 instance_id 為準(zhǔn)。有點(diǎn)類似 HTTP 的 ETag 機(jī)制——光靠 URL 尋址不夠還得校驗(yàn)版本。5. 穩(wěn)定性之外的進(jìn)階優(yōu)化負(fù)載感知、局部分片、可觀測(cè)性5.1 負(fù)載感知路由別把所有任務(wù)堆給同一個(gè) Agent能力路由如果只看在線有對(duì)應(yīng)能力壓測(cè)時(shí)就會(huì)暴露一個(gè)問(wèn)題所有任務(wù)被均勻地其實(shí)是輪詢地分發(fā)給所有 Agent但每個(gè)任務(wù)的復(fù)雜度差別巨大。處理簡(jiǎn)單任務(wù)只要 200 毫秒的 Agent 和處理 5 分鐘重度任務(wù)的 Agent 被同樣對(duì)待忙的忙死閑的閑死。我在 Agent-Reach 里加了一個(gè)體重指標(biāo)每個(gè) Agent 在續(xù)租時(shí)上報(bào)自己的實(shí)時(shí)負(fù)載包括隊(duì)列深度收件箱 pending 消息數(shù)、最近一分鐘處理耗時(shí) P95、當(dāng)前并發(fā)數(shù)。協(xié)調(diào)節(jié)點(diǎn)在能力路由打分時(shí)這三個(gè)指標(biāo)各占權(quán)重 30%、40%、30%選得分最優(yōu)的 Agent 投遞。這個(gè)優(yōu)化上線后壓測(cè)里的 P95 延遲直接降了 37%。原理不復(fù)雜從誰(shuí)有空轉(zhuǎn)給誰(shuí)變成誰(shuí)最快把活干完轉(zhuǎn)給誰(shuí)。負(fù)載感知本質(zhì)上做的是全局調(diào)度而不是簡(jiǎn)單的負(fù)載均衡。5.2 收件箱局部分片單 Agent 收件箱的一百萬(wàn)條消息問(wèn)題壓力測(cè)試做到單個(gè) Agent 收件箱超過(guò) 100 萬(wàn)條消息時(shí)SQLite 的select * from inbox where statuspending limit N開始出現(xiàn)明顯的性能退化。原因是 pending 消息和已處理消息混在同一張表里沒(méi)有索引覆蓋全表掃描越來(lái)越慢。修復(fù)方法很粗暴但很有效按status做局部分區(qū)。pending消息存一張只有幾百條記錄的熱表done消息定期歸檔到冷表failed消息單獨(dú)存放。熱表因?yàn)轶w積小查詢永遠(yuǎn)是毫秒級(jí)冷表只做歷史追溯不在乎慢。這個(gè)優(yōu)化帶出一個(gè)通用經(jīng)驗(yàn)任何消息系統(tǒng)熱數(shù)據(jù)和冷數(shù)據(jù)必須物理分離。不要因?yàn)閿?shù)據(jù)量還沒(méi)那么大就偷懶等到 100 萬(wàn)條再處理代價(jià)是幾小時(shí)的遷移和一堆線上事故。5.3 消息軌跡的三種監(jiān)控視圖最后一個(gè)大家容易忽略的模塊是可觀測(cè)性。Agent 通信鏈路比單體接口長(zhǎng)得多出問(wèn)題的時(shí)候如果沒(méi)有軌跡追蹤排查一天都不一定有結(jié)果。Agent-Reach 里我實(shí)現(xiàn)了三種監(jiān)控視圖都是在消息的trace字段基礎(chǔ)上做的鏈路視圖輸入一個(gè)message_id畫出它從發(fā)出、經(jīng)過(guò)哪些 Agent、最終完成的完整時(shí)間線每一跳的耗時(shí)都標(biāo)出來(lái)。排查任務(wù)到底卡在哪一步時(shí)這張圖是救命稻草。隊(duì)列視圖每個(gè) Agent 的收件箱 pending 數(shù)量、處理速率、平均等待時(shí)間實(shí)時(shí)展示。隊(duì)列深度暴漲往往比接口延遲更能提前暴露系統(tǒng)瓶頸。失敗歸因視圖所有 failed 消息按失敗類型聚類看看是超時(shí)、連接拒絕、還是處理異常。如果連續(xù)五分鐘超時(shí)占比超過(guò) 20%自動(dòng)告警。這三種視圖加起來(lái)讓我從事后看日志變成了事前看趨勢(shì)。有一次壓測(cè)中發(fā)現(xiàn)某個(gè) Agent 的隊(duì)列深度緩慢上漲但接口延遲正常順著隊(duì)列視圖往下查發(fā)現(xiàn)是這個(gè) Agent 在處理某個(gè)特定類型的消息時(shí)出現(xiàn)線性重試每次都要等滿 120 秒。如果沒(méi)有隊(duì)列視圖這個(gè)問(wèn)題要等用戶投訴才能發(fā)現(xiàn)。6. 收尾Agent-Reach 適用的邊界以及我最后的建議寫了這么多得說(shuō)點(diǎn)實(shí)在話收個(gè)尾。Agent-Reach 不是什么高大上的框架它的定位就是自建多 Agent 系統(tǒng)時(shí)的一塊通信拼圖。我最初做它是因?yàn)閷?shí)在受不了 Agent 之間裸連 HTTP 導(dǎo)致的各種玄學(xué)問(wèn)題其實(shí)一點(diǎn)都不玄全是分布式系統(tǒng)的基本問(wèn)題只是分散在 Agent 場(chǎng)景里顯得特別難查。適用邊界說(shuō)一下Agent 數(shù)量在幾十個(gè)量級(jí)、部署在同一個(gè)內(nèi)網(wǎng)、不需要跨數(shù)據(jù)中心強(qiáng)一致性的團(tuán)隊(duì)用它最合適。如果你的場(chǎng)景是幾百上千個(gè) Agent、要求多區(qū)域容災(zāi)、需要嚴(yán)格的消息事務(wù)語(yǔ)義那么建議直接考慮成熟的 MQ 或工作流引擎Agent-Reach 的能力模型會(huì)變成你的限制。最后分享幾個(gè)我實(shí)際用下來(lái)的體會(huì)第一先把失敗場(chǎng)景想清楚再寫正邏輯。Agent 通信 90% 的代碼都是在處理消息丟了怎么辦Agent 掛了怎么辦重復(fù)消費(fèi)怎么辦。我第一版把正邏輯寫得很漂亮后來(lái) 80% 的時(shí)間都在補(bǔ)失敗路徑。如果重來(lái)我會(huì)先寫故障注入測(cè)試。第二給每條消息留下足夠的元數(shù)據(jù)。message_id、trace、max_hops、execution_token這些字段看似廢話但每一個(gè)都在實(shí)際事故里救過(guò)我。別嫌消息頭重寧多重十個(gè)字段不要在排查時(shí)因?yàn)闆](méi)有 trace 而看半天。第三把重試、超時(shí)、路由這些邏輯統(tǒng)一收斂在協(xié)調(diào)節(jié)點(diǎn)。Agent 端保持無(wú)狀態(tài)是最好的這樣你隨便怎么縮擴(kuò)容都不用擔(dān)心 Agent 端的本地狀態(tài)丟失。Agent-Reach 的核心價(jià)值就是把穩(wěn)做到了協(xié)調(diào)層而不是指望每個(gè) Agent 自己自覺。如果你也在搭 Agent 網(wǎng)絡(luò)希望這篇分享能幫你少踩幾個(gè)坑。通信底座穩(wěn)了Agent 的智能才能真正發(fā)揮出來(lái)——不然再聰明的 Agent消息都送不到對(duì)方手里那不叫協(xié)作叫互相折磨。