Microsoft Agent Framework1.25收緊MCP探索與工作流共用：Python升級要改什麼？

把同一個代理接給多位使用者時，程式需要分清誰的會話、誰的工具權限，以及一個連線可以等多久。這些邊界若只靠呼叫者記得，升級後就容易出現不同解讀。

Microsoft Agent Framework1.25於2026年11月7日釋出Python1.25.0版本，把MCP工具探索、工作流授權範圍與部分逾時預設寫得更明確，也要求Python3.11以上。

這是一個建立代理與多步驟工作流的程式框架，並非新聊天模型。新版主要改變的是應用程式怎麼建立會話、發現外部工具，以及保留一次請求的身分。

例如工具清單探索預設最多100頁與1000項，框架管理的請求預設30秒逾時。大型目錄可以調整限制，但這些數字不是整個任務只能做30秒。

工作流的執行器與會話也綁定一個授權範圍，跨範圍重用會在呼叫模型前被拒絕。這能處理執行中物件的共用問題，卻沒有自動接管應用自己放進共享儲存的資料。

我認為這版適合把代理提供給多個身分、或接上大型MCP目錄的團隊優先檢查。升級把隱含假設變成可見條件，既有的物件重用與連線寫法也可能要調整。

先看工具目錄如何被發現，才能理解新限制與後續授權檢查為何會一起出現。

Microsoft Agent Framework1.25如何限制MCP工具探索？

新版替工具與提示目錄設上限，並在更新失敗時保留前一次完整快照。

MCP讓代理用共同介面找到外部工具。開始呼叫前，客戶端通常要向伺服器取得工具名稱、說明與輸入欄位，提示目錄則提供另一類可用的提示內容。

若伺服器把清單分成很多頁，探索就可能持續很久。這次目錄探索改動預設每份目錄最多讀100頁、1000項，讓框架不必無限制地追著下一頁讀取。

這兩個數字約束的是探索範圍，不是每天最多呼叫1000次工具。工具執行量、模型輸出與外部服務費用，不能從目錄項目上限直接推得。

大型目錄可以提高max_discovery_pages或max_discovery_items。也能設為None取消相應限制，但官方要求只對可信任的MCP伺服器這樣使用。

兩種上限可以各自調整，因此需要先知道卡住的是頁數，還是項目數。只把其中一個設得很大，不代表另一個限制也跟著放寬。

更新失敗時，系統會保留先前完整的目錄快照。這避免代理突然拿到只更新一部分的工具集合，卻也代表它當下看到的可能仍是上一份成功取得的內容。

因此，探索成功和工具內容最新是兩個條件。若服務端剛更名或新增工具，團隊需要留意目錄是否真的完成刷新，而不只看代理還能不能繼續回話。

目錄能讀完之後，工具要不要進入代理可用範圍，還有另外一層核准規則。

工具探索核准與執行身分怎麼分開？

探索政策可以依工具資料決定核准方式，但不會取代每次請求的身分隔離。

新版支援可呼叫的MCP探索核准政策，也會尊重Foundry Toolbox的相關核准資料。應用可以依工具名稱、唯讀標記等條件，安排哪些工具需要核准。

這比單一固定設定更細，因為查詢資料和修改資料不必永遠共用相同政策。不過，工具標成唯讀只是政策可以參考的資訊，不能推成模型往後的每個動作都已被人看過。

呼叫端明確指定的設定也會被尊重，保留的工具則會在政策刷新時更新處理。因此，授權政策改變後，既有工具不應永遠沿用最初那一份判斷。

同一連線的請求，怎麼保留各自身分？

另一項修正把HTTP標頭限制在每個送出請求的範圍。標頭是請求攜帶的資料，可能包含辨識呼叫者所需的內容，不能因為共用連線而混成另一個人的設定。

有效標頭相同的工具、提示與資源讀取仍可以重疊執行，身分改變時則隔離處理。這是在避免資料混用的同時，保留不必互相等待的請求能力。

不過，若多個操作依賴同一個伺服器會話的狀態，應用仍要安排先後順序。框架保留請求身分，沒有替業務決定哪個修改應先完成。

這個區別很實際。兩次查詢可能可以同時進行，但先建立遠端工作、再讀取結果，仍需要由流程保留相應關係，不能只依賴連線本身。

工具列表分清楚後，同一個工作流物件能不能交給另一位使用者，也需要明確答案。

為什麼跨使用者工作流要重新建立？

執行中的工作流執行器與會話只能屬於一個授權範圍，跨範圍重用會提前失敗。

執行器負責運轉工作流，會話則保留這次互動狀態。若伺服器把同一組物件交給不同使用者，應用就需要回答前一位留下的內容和權限應如何處理。

工作流範圍修正把相關物件綁定到一個授權範圍。若另一範圍嘗試重用，會在呼叫模型前回報WORKFLOW_SCOPE_CONFLICT，讓衝突先出現在程式入口。

官方建議使用workflow_factory，每次呼叫建立新的工作流、AgentExecutor與AgentSession。這裡的工廠可以理解成一個負責產生新物件的函式，而非共用一份既有實例。

只把cache_target設為False仍不夠。若多次呼叫背後沿用相同建構器，執行器仍可能被重用，所以要檢查的是最後產生的物件，而非只看到參數已關閉快取。

single_user=True則只適合所有呼叫者確實屬於同一個主體。它不是把多使用者服務改成相容模式的捷徑，否則應用前提仍和實際呼叫者不同。

哪些資料不在這道檢查裡？

這道保護涵蓋活著的執行器與會話身分，不包含應用自行從共用儲存載入的狀態。自訂工具函式若另外呼叫工作流，也不會因此自動取得相同保護。

所以，新的物件不能代替資料分區。假設每次都建新會話，卻從同一個未區分使用者的資料位置讀取內容，入口物件正確也沒有解決資料來源問題。

AG-UI端點另不再接受WorkflowAgent.as_tool()，會回報不支援錯誤。這個限制針對該入口的工作流代理工具，不是宣布整個框架取消工具呼叫。

需要提供這類工作流時，官方建議透過工廠直接供應。這讓服務入口與物件生命週期對齊，而不是在更深一層才發現它被另一個範圍使用。

建立新的工作流解決物件共用，MCP連線內部是否沿用狀態則是另一個問題。

新MCP會話與30秒逾時，會如何影響流程？

宣告式處理器每次呼叫建立新的協定會話，預設逾時也只約束框架管理的請求。

宣告式設定讓應用用設定描述要連哪些工具，DefaultMCPToolHandler則負責實際處理。新版在每次處理器呼叫建立並關閉新會話，連tools/list也包含在內。

因此，前一次工具呼叫在伺服器端留下的隱含會話狀態，不會保證跨到下一次呼叫、等待核准之後或檢查點恢復時繼續存在。

如果工作需要持續操作同一個遠端資源，就要明確保留遠端狀態的識別資訊，或使用範圍明確的自訂處理器。靠連線一直活著來記住工作，已不符合這條預設路徑。

舊的cache_max_size參數仍可傳入，但已棄用且不再產生效果。設定一個較大的快取數字，無法把原本的會話重用行為帶回來。

建立處理器的方式也跟著改變，應使用一般建構，不再包在async with裡，並移除處理器的aclose()呼叫。若借用應用自己的HTTP客戶端，仍要另外管理其關閉時機。

這項宣告式套件修正版本為1.5.0，核心版本則是1.25。不同子套件有各自版號，不能把兩者當成發行說明前後矛盾，也不能只更新其中一項就假定依賴已對齊。

另一項30秒預設，適用於框架管理的請求。呼叫者自己持有的客戶端，保留自己的傳輸與逾時政策，沒有被一律改寫。

官方也明說，請求進入與恢復各有自己的逾時預算，不是整段端到端工作的單一截止時間。因此，看到30秒不能直接推算最久多久一定拿到完整答案。

有需要可設request_timeout=None恢復無限等待，但這是明確改變請求政策。工作流檢查點與核准驗證沒有因此取消，也沒有新增必須套用的檢查點遷移旗標。

連線生命週期改變之後，既有觀測與錯誤處理也得能辨認新的輸出。

追蹤與沙箱錯誤為何需要同步調整？

工作流追蹤欄位改採OpenTelemetry慣例，主機工具錯誤則預設不把細節交回生成程式。

追蹤是記錄一次工作經過哪些步驟的資料。舊系統若只用精確名稱workflow.run尋找工作流，新版名稱改變後，就可能在畫面上看不到原本要看的執行紀錄。

官方建議改用gen_ai.operation.name等於invoke_workflow來篩選，工作流名稱屬性也改成gen_ai.workflow.name。這是觀測欄位遷移，執行時與檢查點的工作流識別並未一起改名。

因此，升級後若報表忽然少了工作流，先確認查詢欄位是否仍在找舊名稱，比直接認定工作沒有執行更能對準問題。

Hyperlight與Monty的改動則發生在主機工具出錯後。預設會把原始例外細節遮蔽，再讓生成的程式繼續，因此程式端會拿到一般RuntimeError診斷。

原本依特定例外類型分支的邏輯，可能因此需要調整。可信任通道可以由主機端開啟include_detailed_errors，但這和外層客戶端錯誤處理、敏感資料記錄是不同設定。

GitHub Copilot整合也縮小一種URL核准行為。沒有明確domain的會話核准，現在只當成單次核准，若確實要授權特定網域，必須把範圍寫出來。

這些變化有共同方向，讓程式依賴的範圍更明確。但它們作用在不同位置，不能只用一句「新版更安全」，就跳過實際要改的輸入和判斷。

這些行為變動最後還要和Python及整合套件的版本要求一起部署。

Python3.11與整合版本，升級要對齊什麼？

Python3.10已不再能安裝這版，各整合套件仍保留自己的上限與核心依賴。

對現有服務而言，先升級框架還是先升級執行環境，並不是任意順序。若伺服器仍停在Python3.10，套件安裝資格就已不符合，還沒走到工具設定那一步。

同時，「3.11以上」不代表每個整合都支援所有更新版本。Foundry Local這次支援3.11到3.14，還有其SDK與作業系統要求，需要依真正使用的整合確認。

框架版本也沒有決定模型、資料庫與外部工具的全部費用。這次公告談的是程式介面與依賴，不能從安裝套件直接推成整套服務免費。

延伸閱讀：AgentBug-Smith 是什麼？把 AI 代理框架錯誤變成可重現的測試

延伸閱讀：Hermes 提供 Grok Bot 遷移入口：搬設定之前，模型帳務與工具權限怎麼確認？

Microsoft Agent Framework1.25常見問題 FAQ

30秒表示整個代理工作必須結束嗎？

30秒是框架管理請求的預設逾時，進入與恢復也有各自預算。它不是整個多步驟工作的共同截止時間，自備客戶端則保留自己的傳輸政策。

關閉快取，就能共用原本的工作流嗎？

共用建構器仍可能重用執行器，即使cache_target=False也一樣。多身分服務需要由工廠建立新的工作流、執行器與會話，並另外區分儲存資料。

所有子套件都應改成1.25嗎？

子套件各有版號，宣告式處理器修正是1.5.0，核心是1.25。應依發行說明核對依賴，而非把每個套件都硬設成相同版本。

結論

Agent Framework1.25讓工具探索、工作流身分與會話存續有了更明確的預設。對既有應用來說，真正的升級工作是找出哪些地方仍依賴共用物件或隱含狀態。

可以先從一條實際使用的多使用者工作流，追到它的建構器、會話與MCP處理器，再對照請求逾時和觀測欄位。這樣比較容易把改動對回具體行為，而不是只確認版本號已更新。

資料來源

• Microsoft Agent Framework Python1.25.0完整發行說明