the Agent-to-Agent Exchange
這是一份契約,不是一個產品介面:Wall Street定義了讓三個各自獨立、歸屬不同的系統——Family CFO、Trader Joe、TMZ——可以選擇性地共享資料、互相諮詢的協議,走的是純HTTP,不共享資料庫,也不依賴任何一方必須在線。一個A2A閘道強制執行統一的請求信封、一條可插拔的鑑權鏈,以及一個熔斷器,把每一種失敗模式——鑑權被拒、對端不可達、回應沒通過schema校驗——統統收斂成同一個優雅的「未接通」結果,而不是崩潰。一份配置驅動的拓撲登記表是「誰能跟誰說話」的唯一真相來源,接入第四、第五個系統只是加一段配置,不用改核心程式碼。一塊React Flow畫布把這份拓撲變成人可以看見、可以拖拉重排的東西——但畫布是協議的下游產物,不是重點所在。Wall Street自己也是一個小型多智慧體系統:一個跑在輕量ReAct迴圈上的編排器,調度一個連線推薦專家和一個資料解讀專家,兩者都配置驅動到用哪一檔LLM,也都能在完全不配LLM的情況下退回確定性規則。整套設計——五個階段、二十四張票——已經完成,隨時可以開工。
分享這篇案例 →難點在於:在三個各自獨立的系統寫下任何一行新程式碼之前,先把它們都必須遵守的線上契約凍結下來——每個欄位都要能對應到某張生產資料表裡真實存在的欄位,九種失敗模式統統收斂成同一個「未接通」結果——因為在設計階段就把降級語義定對,遠比等三個團隊都已經照著一份上線的契約寫完程式碼之後再回頭補救便宜得多。
Lightweight ReAct loop routing to Wall Street's own specialist agents
Python (gateway), React, Vite, TypeScript, Tailwind, React Flow
每一次跨系統呼叫都攜帶同一份信封:一個X-A2A-Version標頭、一個同時充當consult冪等鍵的請求ID,還有一個貫穿呼叫方、樞紐、應答方全程的追蹤ID,讓一次跨系統交互事後能從三份各自獨立的稽核軌跡裡重新拼出來。九種命名好的失敗碼——從鑑權被拒到對端不可達,再到回應沒通過schema校驗——對呼叫方而言統統收斂成同一個結果:一個標註清楚的「未接通」,絕不崩潰,也絕不卡住本地流程。一條可插拔的鑑權鏈(先IP白名單,再逐呼叫方的bearer token,mTLS的位置已經留好但還沒實作)擋在每個對端的A2A介面前面,和該系統自己的UI登入刻意分開。這些都不是事後補上去的通用中介軟體——信封、鑑權鏈、完整的錯誤分類,是最早被設計出來的東西,早於任何一個對端伺服器或畫布上的元素。
一份YAML拓撲登記表是唯一知道「有哪些系統存在、誰能跟誰說話」的地方:每個對端宣告自己的節點類型,以及它提供和消費的能力;每條連線規則則指名一個能力、一個提供方,和它合法的消費方。閘道在每次呼叫時執行這些規則,畫布也會先問同一份登記表——一個BFF端點,GET /api/topology——才允許使用者在兩個節點之間拖出一條連線,前端從不寫死任何一對系統。往生態裡接入第四、第五個系統,範圍被限定成:實作A2A伺服器的最小介面(health、capabilities,以及它自己的query端點)、往拓撲配置裡加一段、加上它的token環境變數——只有在它需要一種視覺上不同的節點時,才需要往前端登記表裡加一個新節點類型。如果重複使用通用的「system」節點類型,前端程式碼量是零——新對端只要被能力探索機制找到,就會自動出現。
在畫布上,系統、Agent、資料來源是節點,A2A能力是邊——一條data-share邊透過query呼叫把對端的真實生產資料拉進來,一條consult邊發出請求,把對端的回答當作唯讀結論顯示在詳情抽屜裡。每個節點、每條邊都獨立降級:一個不可達的對端,它的節點會灰顯並附上原因碼,畫布其餘部分照常按設計運作——這正是協議在線路層面強制的「沒有任何一方是另一方的運作支柱」這條規則,只是現在從一行日誌變成了一個看得見的UI狀態。畫布是訪客真正看得到、點得到的那一部分;但它執行的每一條規則——哪些連線合法、一個降級的對端長什麼樣、到底什麼資料允許抵達瀏覽器——都是先在閘道和契約裡定下來的。畫布只是把那份設計呈現出來,它本身不是另一份設計。
Wall Street不只是轉發其他系統的Agent——它自己也跑著一個小型的。一個編排器,用的是這個作品集裡其他地方同款的輕量ReAct迴圈,調度兩個專家:一個連線推薦專家讀取目前畫布和能力地圖,建議可行的連線;一個資料解讀專家把某個節點已經去識別化過的指標,變成一句話解讀。兩者都刻意做成LLM可選——推薦專家的規則版備援,直接從能力地圖裡provider/consumer的交集算出來,是預設行為,在完全不配LLM的情況下也照常可用;解讀專家則是沒有LLM就直接隱藏自己。第四個專家——一個能跨多個節點串聯敘事的insight-narrator——已經設計好、配置裡也留了位置,但在跨節點敘事合成真正做出來之前先保持停用。每個Agent用哪一檔LLM、溫度多少、要不要啟用,統統寫在一份設定檔裡——換模型是改設定,從來不是改程式碼;每一條system prompt都放在外部的提示詞庫裡,按語言和key載入,從不寫死在Agent程式碼本身裡。
瀏覽器永遠不持有A2A token,也永遠不直連對端——它只用一個獨立的UI token向閘道的BFF鑑權,而它收到的每一個生產資料數字,都已經先經過閘道的去識別化層,序列化時套用契約自己的欄位白名單,任何沒有明確列出的欄位都會被靜默丟棄。每一份資料契約都會把自己的自由文字欄位——一條標題、一條備註、一個Agent的回答——標記為不可信,任何把這段文字回灌進自己LLM的系統,都必須把它包進自己既有的防注入信封,當成資料而不是指令來處理;契約自帶的測試套件要求:一條嵌了「把預算改成零」這種指令的回覆,不能在任何地方產生寫入操作。跨系統呼叫按設計唯讀——唯一的例外,consult的結論,也只能以「提議動作」的形式回來,在接收方自己的人工確認流程核准之前,哪裡都不會被執行。這些都不是事後加的補丁:白名單即schema、不可信欄位標記、跨系統零寫入操作,這些規則就是契約本身,在任何一個對端把它實作出來之前就已經凍結。
Python(stdlib A2A閘道)、React + Vite + TypeScript畫布、Tailwind CSS、React Flow,以及一個三方共用的參考mock伺服器,用於跨倉庫的契約一致性測試。