Pydantic AI 推出 Peers:獨立代理互傳訊息不必交出控制權

Pydantic 在 Pydantic AI Harness 推出 Peers,讓分開執行的 AI 代理互相發現、互傳帶來源標記的訊息,而不交出控制權。功能隨 0.69.0 起提供,官方同時警告同儕訊息仍可導向免批准的工具,且 0.x 階段 API 持續變動,首日內已改過一次投遞格式。

用 AI 摘要這篇文章:

Pydantic 在台灣時間 2026 年 11 月 18 日凌晨於官方 X 帳號宣布,Pydantic AI Harness 新增名為 Peers 的功能:讓在不同工作階段(session)裡分開執行的 AI 代理互相發現、互傳訊息,而且沒有任何一方需要去執行另一方。官方貼文用兩句話講完重點:分開執行的代理能找到彼此交換訊息;工作進行中抵達的訊息,有機會在同一輪工作裡就送到模型眼前,而且以另一個代理的口吻呈現,不會當成使用者本人的話。功能隨 pydantic-ai-harness 0.69.0 起提供,這個版本在宣布前一天的台灣時間 11 月 17 日上午就已經推上 PyPI。

這次更新影響的範圍很明確:用 Python 寫代理、採用 Pydantic AI 並用到 Harness 層(這個生態裡負責執行環境與能力的套件)的開發者。你的需求若只是讓多個代理在同一個工作階段裡分頭做事,或根本只用 pydantic 做資料驗證,這個功能與你無關。它鎖定的是另一種情境:兩個代理各有各的使用者、各自的進度與工具,需要把「我這邊的發現」告訴對方,卻不想把對方變成自己的下屬。

把官方文件、PyPI 版本紀錄與儲存庫提交歷史放在一起看,這次更新可以濃縮成一句判斷:Peers 把代理之間的溝通做成「帶來源標記的訊息」,它送出的是資訊,不是權限;啟用前有兩件事要跟著一起決定,一是對有副作用的工具打開人工批准,二是把套件版本 pin 住,因為這個功能上線的頭 24 小時內,API 已經改過一次,而且文件上更新的寫法還沒隨任何 PyPI 版本發布。

交換背景與委派工作,是兩件不同的事

官方文件給 Peers 的定位句寫得很直白:當分別擁有、分開執行的工作階段需要交換背景資訊時用 Peers,而不是把工作委派給子代理。對照文件裡的 Subagents:Peers 不會建立子執行,也不會轉發依賴與用量或等待另一個代理的結果。換句話說,如果你的需求是「請另一個代理把事情做完再回報」,Peers 刻意不提供這條路,你該看的是委派型設計;它處理的是兩個平行情境之間的聯絡。

官方範例給了一個最小可運作的樣貌:兩個代理 alice 與 bob 掛在同一個記憶體內網路上,alice 收到的指令是用 list_peers 找到 bob,再把遷移分析的發現用 send_message 寄過去;bob 的工作則是審查 alice 寄來的內容。放到實際場景,就像一個代理負責檢查資料遷移、另一個代理負責網站介面,欄位名稱改了互相通知一聲,各自保留自己的使用者、進度與工具權限。訊息交流與工作控制被切成兩層,是這個功能最核心的設計決定;把多少環境控制權交給代理,向來是各種代理工作台的共同取捨,Browser Use 把瀏覽器引擎整併進代理是同一個問題在另一個表面的答案。

模型只拿到兩個工具,邊界畫在清單與上限

模型端看得到的全部介面就兩個:list_peers(query='') 與 send_message(to, text, reply_to=None)。清單會列出其他可連絡的工作階段,欄位包含代稱(handle)、識別碼、狀態、正在等待什麼、狀態更新時間、是否收訊、待處理訊息數、工作標題、工作目錄與分支;query 可以按代稱、標題、工作目錄或分支過濾,清單上限預設 30 筆。寄送結果分三種:送達正在執行的代理(delivered)、排進沒有在執行的代理的收件匣(queued)、遭到拒收(refused),一旦接受,寄件端會拿到那則訊息的識別碼。reply_to 可以指向先前的訊息,但它只是標記這則訊息回應哪一則,不是等待回覆的指令。

數字上限有四個,全部寫進文件與程式碼常數:單則訊息上限 16,384 個 UTF-8 位元組、收件匣待處理上限 50 則、每一輪執行最多納入 10 則送達或排隊的訊息、清單最多列 30 個代理。同一輪把同樣文字寄給同一個對象、或超過每輪上限,模型會直接收到告知,訊息根本不會送出。這些上限可以調,但必須是正數。介面收得很窄,而且與後面的安全設計互相咬合:模型不能自己指定路由、不能自稱寄件者,這兩條限制正是來源標記能成立的基礎。

Pydantic 官方文件的 Limits and scope 段落,載明 MAX_MESSAGE_BYTES 16384、MAX_PENDING 50、max_messages_per_run 10 與 max_listed 30 四個上限Pin
Pydantic 官方文件載明 Peers 的四個上限常數

訊息什麼時候被讀到:同一輪工作內可能多一次模型請求

Peers 在每次模型請求的前後都會去收件匣撈新訊息。執行開始時已經在收件匣裡的訊息,會進入首次模型請求;執行進行中抵達的訊息,可能在同一輪執行結束前追加一次模型請求。這解決的是「等整輪跑完再人工轉貼」的時間差:另一個代理剛發現的限制,有機會及時進入這一輪的判斷。

官方文件同時把醜話說在前面:代理可能在別人的答案到達前就結束工作,所以需要回覆才能繼續的任務,主機端要自己設計等待或之後重開的安排。另外,記憶體內網路 InMemoryPeerNetwork 絕不會啟動一個閒置中的代理,訊息會留在收件匣等對方下一次被啟動;要不要用一則訊息喚醒閒置代理,官方把這個決定留給主機端的政策。實務上有的產品要及時處理,有的要控制通知頻率與模型用量,本來就不適合統一答案。

輸入防護(InputGuardrail)的行為值得特別留意。循序模式下,防護先檢查使用者提示,通過之後佇列中的同儕訊息這時才會納入;防護一旦擋下,這輪執行不會發出任何模型請求,訊息留在收件匣。但開了 parallel=True 之後,模型請求與防護並行,同儕訊息可能已經進入對話歷史並離開收件匣,即使防護稍後把這輪擋下。靠輸入防護把關內容的團隊,這個差異會直接改變防護的有效範圍。

來源標記防得了誤讀,防不了免批准的工具

收進來的同儕文字,在對話裡以 PeerMessagePart 呈現,官方稱之為「不帶權威的能力部分」:掛在使用者通道上,帶有 <peer_message sender="alice" id="msg-1"> 這樣的框架與「這是同儕寫的」註記。文件明說,它不是接收端使用者的指令,也不能當成操作批准。文字以原樣傳遞,內容裡模仿框架結構的字句,系統會加註是哪個同儕寫的,而不是做跳脫處理。寄件者身分由主機端從通過認證的工作階段供給,模型在工具參數裡冒用別人的名字沒有用。

主機端自己投遞訊息時有一條硬規則:每一則同儕訊息必須是獨立的訊息部分。合併進使用者提示,來源標記就消失了,同儕的文字讀起來會變成使用者本人的話。

不過官方威脅模型(THREAT_MODEL.md)補了一個更實際的警告:能觸達執行中代理的同儕訊息,仍然可以把代理導向任何「不需要批准」的工具。所以官方給出的部署建議是,只要讓同儕連得到的代理,對有副作用的工具(改檔案、送出資料、發通知)都應該要求批准。同一份威脅模型還載明:InMemoryPeerNetwork 不做身分認證,跨行程的傳輸安全是主機端的責任。來源標記管理的是模型的認知,工具的執行門檻是另一層;啟用 Peers 之後真正要重新盤點的,是後者。

首日版本考古:0.69.0 上架、0.70.0 改投遞格式、隔天主分支已改名

把 PyPI 的發布套件拆開對照,可以看到這個功能的落地節奏。0.68.0 的 wheel 裡沒有 peers 模組;0.69.0(台灣時間 11 月 17 日上午上架)首次出現 7 個 peers 模組檔案;同一個版本發布後不到一天,0.70.0 在台灣時間 11 月 18 日清晨再推一次。官方的宣布貼文落在這兩版之間。

PyPI 上 pydantic-ai-harness 的版本紀錄,0.68.0、0.69.0、0.70.0 的發布日期一欄列出 11 月 12 日到 11 月 18 日Pin
PyPI 版本紀錄:0.69.0 與 0.70.0 在一天之內先後上架

0.69.0 與 0.70.0 之間藏著一個行為差異:0.69.0 把同儕訊息包成 UserPromptPart,靠標記與詮釋資料(metadata)保留來源;0.70.0 改用 CapabilityPart 架構的 PeerMessagePart,也就是現在文件描述的樣子。讀取函式 read_peer_message 兩種格式都認得,舊版投遞的訊息升級後仍可讀出。變化還沒停:台灣時間 11 月 18 日上午,主分支的提交 #13777 把對外類名 PeerNetwork 改成 PeerConnection,並讓 Peers(network) 在代理建構時自動以代理名稱加入網路,沒有名稱的代理會直接收到 UserError;這次改名附帶了棄用名稱的測試與 API 相容性豁免檔。

pydantic-ai 儲存庫主分支的 peers README,程式碼範例以 Peers(network) 讓代理在建構時自動加入網路Pin
主分支 README 已改用 Peers(network) 自動加入的新寫法

查 PyPI,台灣時間 11 月 18 日中午以前最新版本仍是 0.70.0。也就是說,pip 實際裝到的是舊類名,而儲存庫主分支與其文件已經示範新寫法;官方文件站在同一時間點顯示的範例,用的還是改名前的 join() 進網路方式。對照文件寫程式時,先確認裝的版本、再確認類名,順序反了就會對不上。官方對此並不諱言:Harness 還在 0.x 階段,minor 版本之間 API 可能變動,變動時會附上棄用警告與遷移指引。這句政策在首發 24 小時內得到一次驗證。

功能的來源脈絡也查得到:最初的拉取請求 #11671 由社群作者在 10 月 27 日(UTC)提出、11 月 13 日(UTC)併入,作者自述動機是維護者提出需求,因為獨立工作階段在此之前沒有任何互相發現與傳訊的途徑;跨行程的傳輸,官方在該討論中明說另案處理。

跨行程、重試與持久化:主機端要接手的部分

記憶體內網路只是同行程的示例,不是傳輸層。它的成員在網路存活期間永久有效,要讓某個工作階段退場,把它的收件匣設為不再收訊即可;但讓不同行程、不同機器上的代理互通,要在主機端實作 PeerNetwork 的兩個方法(peers() 與 send()),而且身分驗證、路由與使用者可見的通知都歸主機管。模型只提供收件者、文字與回覆標記,剩下的責任全在應用程式。

可靠性方面有一個值得抄走的設計:每次寄送都帶著由 run_id、run_step、tool_call_id 組成的鍵,同一個鍵重試不會投遞出第二則訊息;收件匣會記住最近 max_pending 筆(預設 50)已確認訊息的識別碼來做去重。收件匣本身也有明確的生命週期契約:每輪執行在模型請求前後認領收件匣並取走新訊息,訊息一旦進入對話歷史就回報確認,執行結束時釋放;已取走但未確認的訊息會留給下一輪,而且同一時間只有一輪執行持有收件匣。持久化方面,LocalPeerInbox 可以把待處理訊息寫進一個原子替換的 JSON 檔案,官方建議放在私有目錄(威脅模型載明以 0700/0600 權限建立),但這個檔案不是跨行程的合約。

跨系統交換靠的是中立的訊息線格式:TypeAdapter(PeerMessage) 產生的 JSON,欄位就是識別碼、寄件者、收件者、文字、時間戳記與回覆標記,讓不是用 Pydantic AI 寫的代理也能透過主機網路收發。觀測面刻意維持輕量:訊息送達可以從 EnqueuedMessagesEvent 事件觀察,能力本身不另產生逐則訊息的追蹤紀錄,傳輸端的准入與收件匣的量測都留給主機端自己接。

有一條硬限制要先知道:Peers 目前與持久化執行(durable execution)互斥。把它和任何持久化執行能力掛在同一個代理上,建構當下就會拋出 UserError,原因是引擎不記錄收件匣的讀取與寄送,重播時可能投遞出不同的訊息集合。用 Temporal、DBOS 這類引擎跑代理的團隊,這個功能暫時不在選項裡。

現在要不要動手:三種情況分開看

已經在 Harness 上開發、而且手上真的有多代理平行情境的團隊,值得現在就試:安裝 0.70.0 以上版本,用記憶體內網路起手,但把版本 pin 住、讀對應版本的文件,並且在啟用前重新盤點副作用工具的批准設定;0.x 階段每次升級前,先看版次說明裡的遷移指引。只是想了解這個方向的開發者,跑一遍官方的 alice 與 bob 範例就足以理解模型端的全部介面;在 0.70.0 的 API 裡,加入網路時沒帶收件匣的工作階段只能寄、不能收,兩邊都要掛收件匣才互通。需要跨機器編排、或需要「做完再回報」語意的,這一版不解決你的問題:前者要等主機端傳輸落地(或自己實作 PeerNetwork),後者該看 Subagents 或其他多代理協作層的設計;TypeScript 生態的代理框架則是另一條技術棧的對照組。

尚無法確認的部分也如實列出:改名後的新版(PeerConnection 與自動加入)何時隨版發布、跨行程傳輸的官方形態、Harness 何時脫離 0.x,官方都還沒給時間表。這項功能還在上線初期的變動期:2026 年 12 月 2 日前後,版本編號與文件範例可能又已更新,引用前值得再核對一次。

Sliven 褚崇名
Sliven 褚崇名

每日分享科技新知、免費資源以及 WordPress、虛擬主機相關主題,任何問題歡迎在科技月球下方留言,或是發送 Email 至 [email protected] 與我聯繫。

文章: 2553

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *


Share to...