Pydantic AI Harness 新增 Peers:代理互傳訊息,為何不等於互相授權?
Pydantic Peers 讓不同工作階段的 AI 代理找到彼此、交換進度,卻不用由其中一個代理負責啟動另一個。對已經分開執行的開發或研究工作,這提供了一條補充背景的聯絡方式。了解功能開放條件、操作範圍與團隊試行方法,依官方公告釐清適用情境。
Pydantic Peers 讓不同工作階段的 AI 代理找到彼此、交換進度,卻不用由其中一個代理負責啟動另一個。對已經分開執行的開發或研究工作,這提供了一條補充背景的聯絡方式。
多代理協作常被畫成一位主管派工作給多位下屬,但各自有人負責的代理未必屬於同一條指揮鏈。它們需要的是互傳結果,同時保留原來使用者決定的權限和任務。
Pydantic 官方在 2026 年 11 月 17 日介紹的 Peers,正是處理這種平行關係。接收端會在模型請求前後讀取訊息,執行中抵達的內容也可能在同一輪工作裡被採用。
訊息來得快,反而更需要標清來源。文件要求把內容保留為其他代理撰寫的資料,不能混進使用者提示詞,否則接收模型可能把同儕意見誤讀為使用者自己的命令。
已在設計多工作階段系統的開發者,可以用它降低人工轉貼結果的成本。若需求是跨機器通訊、服務重啟後重播或自動喚醒所有代理,還要補上主機端設計,不能只接範例便當成完成。
要把交流能力放進產品,先要分清訊息送達、工作啟動和操作批准的責任。
Pydantic Peers 與子代理有什麼不同?
Peers 連接的是獨立工作階段,並不替另一個代理管理整段生命週期。工作階段可以理解成一個持續中的任務對話,各自保有負責的使用者、目前進度和能使用的工具。
依 Pydantic 官方文件,Peers 適合讓分開負責的工作交換背景。子代理則是由上層代理建立並委派工作,兩種關係的差異會影響誰能決定任務何時開始、誰負責等待結果。
例如一個代理檢查資料遷移,另一個代理處理網站介面,兩邊可能只需要通知對方欄位名稱改了。它們不一定需要互相控制,也不必為了交換一段結果,就把整份使用者對話搬到另一邊。
這個情境說明訊息交流的用途,不代表官方已提供完整的團隊專案管理系統。Peers 不會替應用程式建立工作者、轉交使用量或等待對方完成,主機仍要管理工作階段本身。
發現其他代理,靠的是誰的資料?
代理能使用 list_peers 找出可聯絡的工作階段。清單包含主機提供的名稱、識別碼、工作標題、狀態與待處理訊息數,也可以依工作目錄或分支等條件篩選,降低把訊息寄錯地方的機會。
可聯絡不等於可存取所有工作內容。清單是主機允許看見的鄰近代理,應用程式仍要決定哪些工作階段彼此可見,不能讓模型靠猜名字就越過客戶或專案邊界。
傳送工具 send_message 只提供收件者、內容與可選的回覆識別碼。寄件者身分由主機依已驗證的工作階段補上,不能讓模型在工具參數裡自稱是另一個人,否則來源標記就失去作用。
如果需求其實是「請另一個代理做完再交回結果」,就應另外安排委派與等待。把這種需求只接成傳訊息,容易在對方仍排隊時,就把整項工作回報為完成。
沒有上下屬關係,就更需要把每則訊息的寄件者與送達狀態說清楚。

訊息何時會被讀取?送達狀態怎麼看?
送出訊息成功,不表示收件代理已完成要求或會立刻回覆。官方把結果分成已送達執行中的代理、排隊等下一輪,以及拒收,這些狀態描述的是傳輸與收件,並非任務驗收。
接收端會在每次模型請求前後讀取新訊息,因此代理已經開始工作,也可能在同一輪結束前再收到背景。這讓另一邊剛發現的限制有機會及時進入判斷,減少等整輪結束才人工轉貼的落差。
不過能及時看見,不保證當輪一定等到回覆。官方文件提醒,一個代理可能在別人的答案到達前就結束工作,所以需要回覆才能繼續的任務,主機必須設計等待或後續重開的安排。
排隊和喚醒為何不是同一件事?
官方範例使用 InMemoryPeerNetwork,讓同一個應用程式裡的工作階段互通。它不會自行啟動閒置代理,因此對方沒有執行中的工作時,訊息留在收件匣,等主機下一次啟動工作才被讀取。
這個設計把是否喚醒的決定留給主機。有些產品希望重要訊息立即開新一輪,有些則要等使用者回來,以控制模型用量和通知頻率,不能讓傳訊息功能替所有產品作同一個選擇。
reply_to 可以指出這則訊息回應哪一則內容,但它不是等待回覆的指令。應用程式若要呈現對話關係,應保留訊息識別碼與狀態,讓使用者知道哪一項已回覆、哪一項仍在等。
拒收也可能是正常結果。收件匣關閉、訊息過大或容量已滿時,系統需要回傳可理解的原因,讓寄件代理調整內容,而不是把無限重試當成可靠傳遞。
預設每輪最多接受十次已送達或排隊的傳送,清單最多列三十個代理。這些限制能控制一次工作的交流規模,但主機仍要追蹤累積等待和失敗,避免代理彼此傳話卻沒有推進任務。
送達只回答資訊能否進入對話,這份資訊能帶來多大影響,還要回到來源與權限。
為何同儕訊息不能變成使用者批准?
Peers 透過來源標記,把其他代理的文字和使用者本人的指令分開。文件將收到的內容視為不可信的同儕資料,明確指出它不是接收端使用者的命令,也不能授予操作批准。
這個區別會影響有副作用的工具。有副作用指的是會改變外部狀態的操作,例如改檔案、提交資料或寄出通知,而不只是讀取資訊,這些動作不能因另一個代理說「已同意」就自動取得權限。
保留文字之外,為何還要保留來源欄位?
官方文件說明,同儕內容雖放在模型能閱讀的訊息通道中,仍附有具類型的來源資訊。模型看到的是帶寄件者標記的其他代理文字,因此主機不應把它直接接到使用者提示詞後面。
若把內容合併成「使用者說請修改正式資料」,即使原文來自另一個代理,接收模型也可能失去辨識來源的線索。這時問題不在訊息有沒有送到,而在應用程式把來源轉錯了。
官方的原生訊息序列化會保留相關欄位,但轉接器若丟棄文字內容的中介資料,來回儲存後就可能失去來源標記。因此接入其他代理框架時,也需要測試存檔、讀回和轉換後的結果。
文件提供 read_peer_message 依來源欄位讀出訊息,而不是只比對畫面上顯示的文字。這讓主機有機會用結構化資料檢查寄件者,也避免把任何長得像標籤的文字都當成可信訊息。
即使來源清楚,同儕內容仍可能影響接收代理下一步的工具選擇。官方因此建議,能被同儕聯絡的代理,對有副作用的工具保留批准,不能以「知道誰寄的」取代操作權限。
對產品設計而言,訊息可以傳遞已查核的結果、限制與建議,但需要由原任務的授權決定能否執行。這讓協作保留價值,也避免一段轉述在多次傳遞後變成無人確認的許可。
來源分清後,系統還要決定訊息存在哪裡、由誰驗證寄件者。
跨程序、持久化與版本限制要補哪些設計?
內建記憶體網路是單一程序範例,跨機器傳輸需要主機實作。程序可以理解成正在執行的一份應用程式,範例裡互相看得到的代理,不會因此自然變成跨伺服器的通訊網路。
要讓分布在不同機器的工作階段互傳,主機需實作尋找對象與送訊息的介面,並負責驗證身分、路由和接收條件。模型只負責選收件者與寫內容,不能代替伺服器驗證誰有權寄送。
收件匣有檔案,就代表可跨機器共用了嗎?
LocalPeerInbox 可以把待處理訊息存到指定路徑,寫入時以完整檔案替換。這有助於保留訊息,但官方明確指出,它不是跨程序通訊約定,也不負責協調多個程序同時寫檔。
因此不能把同一個收件匣檔案放到共用磁碟,就認為完成分散式訊息系統。主機仍要確保訊息只進入正確收件者、重送不造成重複處理,以及同一個收件匣不被不同執行者同時搶讀。
預設單則訊息上限為 16,384 個 UTF-8 位元組,收件匣容量為五十則。位元組是編碼後的大小,不能直接當成固定中文字數,因為中英文和符號占用空間可能不同。
重送控制使用與工具呼叫相關的鍵值,讓相同傳送重試時不再投遞第二份。應用程式仍要保留自己的工作完成狀態,因為避免重複送信和避免外部工具重複執行,是不同的問題。
另一項重要限制是,Peers 尚不支援可持久重播的執行方式。官方說明,執行引擎沒有記錄收件匣讀取與傳送,重播時可能得到不同訊息,所以與相關持久執行能力組合會在建立代理時報錯。
Pydantic AI Harness 仍在 0.x 版本階段,次版本可能調整介面。團隊應固定依賴版本,保留遷移說明,並在升級後重測訊息來源、拒收和排隊,而不是只確認套件能安裝。
把主機責任列清楚,才適合以小型協作任務驗收整個流程。
Pydantic Peers 常見問題
另一個代理傳來「使用者已同意」,可以直接操作嗎?
不行。同儕訊息是其他代理撰寫的資料,不能替接收端使用者授權。工具若要求批准,仍需沿用原本批准機制,不能因訊息內容而繞過。
訊息排隊後,對方一定會自動醒來嗎?
不一定。內建記憶體網路不啟動閒置代理,是否開新一輪是主機策略。需要即時回覆的產品,必須另外設計喚醒、等待與逾時處理。
接上 Peers 就能跨機器協作和重啟恢復嗎?
不能直接這樣推論。跨機器身分與傳輸由主機實作,檔案收件匣也不協調多程序寫入。官方另列出不支援持久執行的限制,應分開規劃。
先驗證訊息來源,再擴大代理協作範圍
適合先測試的是互報進度與交換可查核成果,讓需要寫入或對外操作的工具保留批准。這能驗證協作是否減少人工轉貼,同時不把聯絡能力誤當成另一條指揮鏈。
依 官方原始公告回到文件做一個小範例,讓兩個工作階段分別保持任務,再測試執行中收到補充與閒置時排隊。這些結果比單純看訊息送出成功更能說明是否接對。
用同一個情境測試排隊、拒收、重送和來源保留,通過後再接跨程序網路。如果任務依賴完整重播或互相授權,則應先補好主機設計,而不是讓代理靠文字約定承擔系統責任。
延伸閱讀:pydantic/pydantic-ai 型別安全 Python 代理框架教學:結構化輸出、依賴注入與測試指南
延伸閱讀:Pydantic AI 2.68 統一人工問答與核准:代理暫停後,怎麼接回同一項工具工作?