Python 2026 重大變更指南

本文件列出自 2026 年初以來 Python 版本中的所有重大變更,包括可能影響程式碼的重要變更與重要改進。 每個變更都會標示為:

  • 🔴 重大變更 — 需要進行程式碼更改來升級
  • 🟡 增強 — 新能力或改進;現有程式碼仍然有效

這份文件追蹤了 2026 年所有版本中 Python 的重要變更,因此在不同版本間升級時請務必參考,以確保不會錯過任何重要變更。 關於特定主題的詳細升級指引(例如選項遷移),請參閱連結的升級指南或連結的PR。


未發行

在 Python 1.25.0 之後,沒有記錄到任何重大變更。


python-1.25.0(2026 年 11 月 6 日)

發行說明:python-1.25.0

🔴Python 3.11 現為最低支援版本

PR:#9948

Agent Framework 套件無法在 Python 3.10 上安裝。 在升級套件群組之前,請先將直譯器升級至 Python 3.11 或更新版本。 套件特定的上限仍然適用;Foundry Local 支援 Python 3.11 至 3.14。


🔴 MCP 的發現、逾時、核准以及會話擁有權都有限制

PRs:#10042、 #10136、 #10147、 #8662、 #10151

Framework 擁有的 MCP 請求現在預設使用 30 秒逾時。 工具與提示的發現限制為每目錄 100 頁及 1,000 個項目。 僅針對受信任的伺服器,才可增加或停用這些限制。

本地 MCP 工具與 Foundry Toolbox 支援可呼叫的核准政策。 當未提供呼叫者覆寫時,工具箱工具會尊重其核准元資料。 具有相同有效請求身分識別的呼叫可能會重疊;身分識別變更會等待目前進行中的工作完成,並在新工作開始前重新連線。

Declarative DefaultMCPToolHandler 現在會為每一次呼叫建立一個新的協定會話。 移除 context-manager 和 aclose() 的用法。 Legacy cache_max_size 參數是已棄用且不起任何作用的參數。 當工作流程需要伺服器工作階段連續性時,請使用明確的遠端狀態或自訂處理器。


🔴 AG-UI 工作流程執行器綁定於單一授權範圍

PR:#10035

AG-UI 工作流程執行器及其代理工作階段綁定到使用它們的第一個授權範圍。 跨授權範圍重複使用會在模型執行前失敗,並顯示 WORKFLOW_SCOPE_CONFLICT。 使用 workflow_factory 來建立已驗證或多使用者端點的新工作流程、執行器與工作階段。 AG-UI 端點也會以 WORKFLOW_AGENT_TOOL_UNSUPPORTED 拒絕 WorkflowAgent.as_tool();直接提供工作流程。


🔴 工作流程呼叫 span 遵循 OpenTelemetry GenAI 的慣例

PR:#9900

將完全相符的 workflow.run span 名稱篩選器取代為 gen_ai.operation.name == "invoke_workflow"。 命名 span 使用 invoke_workflow {workflow_name}。 未命名圖工作流程會使用 invoke_workflow 並省略 gen_ai.workflow.name。 將 workflow.name 屬性查詢替換為 gen_ai.workflow.name。


🔴 Foundry Local 使用 SDK 2.3.1 並準備已註冊模型

PR:#9322

在 Python 3.11 到 3.14 及受支援的平台上安裝foundry-local-sdk>=2.3.1,<3。 需要自訂設定時,請先設定共用管理器,再設定第一個用戶端。 bootstrap=False 需要已初始化的管理者和正在執行的服務。 prepare_model=False 將載入延遲至首次請求;它不會關閉載入功能。 移除不支援的 do_sample 和 early_stopping 選項。


🔴 CodeAct 預設會遮蔽主機工具的診斷內容

PR:#9971

Monty 和 Hyperlight 現在在主機工具失敗時,會向產生的程式碼回傳通用的 RuntimeError。 僅對需要原始例外類型與訊息的受信任通道設定 include_detailed_errors=True。


🟡 注入客戶端始終優先

PRs:#9977、 #9983、 #9984、 #9985、 #9987、 #9991、 #9996、 #9967

呼叫者提供的 Redis、Postgres、Oracle、Cosmos、Claude、Azure OpenAI、Foundry 嵌入與 Bedrock 客戶端現在優先於環境連線設定,並保持呼叫者擁有。 檢視同時提供注入用戶端與環境設定的應用程式;注入用戶端的連線、部署、區域或資源識別碼為權威。


🟡 驗證與核准邊界預設為封閉

PRs:#10036、 #9875、 #10090、 #10149

生成的代理程式 MCP 工具會在讀取會話狀態或呼叫代理程式之前,先驗證其完整的 JSON 架構。 FIDES 將核准綁定於精確已解決的參數、政策元資料、執行時上下文及呼叫權限。 GitHubCopilotAgent 拒絕提供者提供的函式中介軟體,且對 URL 請求的純核准會話決策會被縮窄為一次性核准,除非應用程式提供明確網域。


🟡Redis 支援 Python 3.15

PR:#10143

Redis 整合及其標準安裝相依關係現已支援 Python 3.15 及 RedisVL 至 0.31。


🟡 Monty 資源限制使用目前的執行時鍵值

PR:#10096

Monty 需要 pydantic-monty 1.0 或更新版本,且須在支援的 1.x 範圍內。 用於 max_feed_duration_secs 整體餵食時間。 舊有 max_duration_secs 別名已被棄用,且同時提供兩個名稱會造成錯誤。


python-1.23.0(2026年10月22日)

發佈說明:python-1.23.0

🔴 MCP 整合使用 MCP SDK 2.x 用戶端生命週期

PR:#9236

Agent Framework 現在需要 mcp>=2.2.0,<3 才能支援 MCP,並將標準操作路由至 MCP SDK 的高階 Client。 此變更使 SDK 能管理協定協商、處理多重往返請求、快取回應及訂閱管理。

對於由架構管理的連線,請繼續將 url= 或 command= 傳遞至 MCPStreamableHTTPTool 或 MCPStdioTool。 當連線由您的應用程式管理時,請先進入 mcp.Client 的內容管理範圍,再建構工具,並透過 mcp_client= 傳入該用戶端。 在 Agent 或工作流程的整個執行期間,請讓用戶端保持在內容管理範圍內。

呼叫者提供的 ClientSession 物件 和 MCPTool.session 是已淘汰的相容性路徑。 這些項目不會獲得高階快取或自動多次往返的行為。 WebSocket 傳輸已被移除,MCP 任務目前不支援,伺服器發起的取樣功能也已被棄用。 關於遷移範例,請參見 遷移至 MCP 2.x。


🔴 AG-UI 端點需要明確的授權所有權模式

PR:#9413

每個 add_agent_framework_fastapi_endpoint(...) 註冊現在必須選擇一種授權所有權模式:

  • 對於需要驗證的服務或共用服務,請提供 authorization_scope_resolver。
  • 保留現有受信任的 snapshot_scope_resolver 作為相容性路徑。
  • 僅針對本機或真正的單一使用者應用程式設定 single_user=True。

僅靠認證依賴無法界定快照、會話、檢查點、分離執行或批准狀態的範圍。 解析器必須回傳一個穩定且非空的作用域,源自可信的認證上下文。 關於遷移範例,請參見 宣告 AG-UI 授權所有權。


🔴 Docker shell extra 參數是明確不安全的

PR:#9453

將 DockerShellTool(extra_run_args=...) 重新命名為 DockerShellTool(unsafe_extra_run_args=...)。 值會逐字附加在容器執行指令後,能削弱或繞過隔離,且絕不可來自模型輸出或其他不受信任的輸入。 若 DockerShellTool 提供專用的建構函式選項,請優先使用。


🟡 A2A 可以轉發允許列出的執行脈絡

PRs:#9192, #9193

A2AAgent(forwarded_kwargs=[...]) 能夠在 A2A 請求中繼資料中傳送選定的 JSON 相容 function_invocation_kwargs 且 client_kwargs。 A2AExecutor 會透過 accepted_function_invocation_kwargs 和 accepted_client_kwargs,獨立控制服務接受的引數。 雙方都預設為不轉寄,也不接受任何內容。


🟡 循序 Agent 可新增與提供者相容的接續回合

PR:#8779

當聊天完成服務提供者對於以助理訊息結尾的輸入回傳空回應時,請在 SequentialBuilder 或 AgentExecutor 上設定 ensure_trailing_user_turn=True。 該選項會附加一個僅用於調用的合成使用者延續,並預設為 False。


🟡Python 3.15 支援擴展至 Hyperlight、A2UI 與 DuckDB

Python 1.23 新增了 Python 3.15 相容的相依路徑,適用於 Hyperlight 0.8、AG-UI A2UI Extra 及 DuckDB 2.x。 標準agent-framework安裝在 Python 3.15 上仍未包含 Redis,而宣告式 Power Fx 表達式在 Python 3.14 和 3.15 上仍然無法使用。


🟡 套件生命週期標籤獨立於元套件

根套件 agent-framework 會同時安裝處於穩定版和發行前版本生命週期的整合項目。 在 1.23 批次中,Core、OpenAI、Foundry、AG-UI、Declarative、GitHub Copilot 和 Orchestrations 是已發佈的套件。 元套件中包含的其他套件仍可為 alpha 或 beta。 使用 Python 套件狀態表,而不是根據pip install agent-framework是否包含套件來推斷其穩定性。


🟡可安裝的 Python 建置器技能,用於編碼代理

PR:#9374

Python 1.23 包含公開且由 Microsoft 維護的 agent-framework-builder-python consumer skill。 相容的編碼代理程式可安裝此技能,載入針對建置、檢閱、評估、整合及裝載 Python Agent Framework 應用程式的專門指引。 這個技能不是 PyPI 套件,也未載入到 Agent Framework 執行環境。

如需安裝方式、支援的用戶端指引及提示範例,請參閱使用編碼代理程式建置 Agent Framework 應用程式。


python-1.22.0(2026年10月15日)

發布說明:python-1.22.0

🔴 內容執行所有權、元資料與串流合併皆被整合

PR:#8886

Python Content 現在針對架構行為使用一級欄位。 函式呼叫內容序列化 hosted;當提供者或服務執行呼叫時,將其設為 True。 server_name 描述伺服器邊界,但不控制執行。 架構與提供者擁有的中繼資料現在使用一層 additional_properties 命名空間,如 core、openai、foundry 和 a2a。

串流介面卡必須設定 merge_mode="append" 為 delta 以及 merge_mode="replace" 為權威來源內容或訊息快照。 彙總會使用這些指示,包括對異質訊息內容進行更新層級的取代。

同時升級核心、提供者、協定介面卡、UI 套件和主機。 新的執行環境會讀取舊有 server_label 和元資料的位置,但舊的執行環境會拒絕新近序列化的 hosted 和 merge_mode 欄位。 寫入新記錄後,不要復原或同時對同一持續保存的工作階段或歷史存放區執行舊的和新的背景工作。


🟡支援 Python 3.15,而 Python 3.10 已被棄用

PR:#9363

相容代理框架套件現已支援 Python 3.15。 Python 3.10 仍支援並測試此版本,但因上游 Python 3.10 已終止支援,已軟棄用。 新環境請使用 Python 3.11 或更新版本。

在 1.22 版本中,標準agent-framework安裝在 Python 3.15 上省略了 Redis 和 Hyperlight,AG-UI A2UI 額外套件也無法使用。 Python 1.23 移除了 Hyperlight 和 A2UI 的限制,並新增了 DuckDB 支援。 Redis仍然被省略,宣告式 Power Fx 值在 Python 3.14 和 3.15 上仍不會被評估,並會顯示警告。


python-1.21.0(2026年10月8日)

發佈說明:python-1.21.0

🟡 OpenAI 用戶端支援最高推理強度

PR:#8857

OpenAI 相容的客戶端可在所選模型支援時請求提供者的最大推理工作量設定。


🟡 Oracle AI 資料庫向量儲存以 alpha 連接器形式提供

PR:#8676

此 agent-framework-oracle 套件新增了 Oracle AI 資料庫的原生向量儲存功能。 該套件處於 alpha 階段,且是與 agent-framework meta-package 分開安裝的。


🟡 當代理以工具形式運行時,提供者擁有的會話會保持隔離

PR:#8853

當一個代理被另一個代理作為工具呼叫時,Foundry 和 GitHub Copilot 的提供者工作階段狀態被隔離。 這種隔離防止外部對話意外重用巢狀代理的提供者擁有的服務會話。


python-1.20.0(2026年10月2日)

發行說明:python-1.20.0

🔴 Foundry Invocations 預設使用 JSON 與框架 SSE

PR:#8894

InvocationsHostServer 現在會將非串流成功回應以 {"response": "..."} 傳回,而非純文字。 串流現在使用具框架的伺服器傳送事件:delta 用於文字更新,done 用於最終回應定案且 AgentSession 已儲存後,error 用於失敗情況。 串流可能會在發生錯誤前傳送 delta,因此請將 done(而非 delta)視為成功完成。

更新客戶端來解析 JSON 和 SSE。 在 done 事件中的 session_id 是平台沙箱路由 ID,而不是序列化的 AgentSession.session_id。 同一會話請求僅在單一主機程序內序列化,且在外部工具影響後仍可能發生跨程序狀態衝突。

現有呼叫者可暫時設定 legacy_wire_format=True 保留舊有的成功純文字回應與原始文字區塊串流。 相容模式已棄用,且不會將失敗結果作為成功文字回傳。 應用程式也可以接受自訂酬載,由 parse_request 傳回 InvocationRun,並使用 prepare_options 篩選呼叫端選項;主機會在掛鉤函式執行後驗證保留控制項。 詳情請參閱 Foundry 託管代理程式。


🔴 宣告式工作流程物件屬性需要安全名稱

PR:#8893

Python WorkflowState獨立版與由工廠建立的宣告式工作流程狀態現在採用相同的物件屬性策略。 當點符號路徑遍歷 Python 物件時,每個屬性段必須相符[A-Za-z][A-Za-z0-9_]*。 不安全的區段,如 _private、 display-name,或帶有後方空白的值,會回傳查詢預設值,但不需存取該屬性。

字典鍵碼不變。 例如,Local.obj._private 不再讀取物件屬性,而 Local.bag._private 在 "_private" 為字典時仍會讀取 Local.bag 鍵。 可公開符合支援模式的公開物件屬性,或將不規則名稱(包括 UUID 與連字號值)儲存為字典鍵。 詳情請參見物件屬性路徑。


🔴 Foundry 回應主機將歷史、儲存與背景執行分開

PR:#8794

ResponsesHostServer 現在將呼叫者 store 欄位、外部回應儲存庫、模型歷史與提供者原生背景執行視為獨立選項。 將構造子 store= 的參數重新命名為 response_store=。 舊名稱仍是已棄用的別名,且不會設定呼叫端針對每個請求的儲存行為。

檢查你的 history_source 設定。 預設 "agent_server" 模式重建外部回應轉錄本並停用下游儲存。 使用 "service" 以繼續私人儲存提供者工作階段,或使用 "agent" 以保留由代理擁有的歷史提供者或下游儲存的預設設定。 store=false請求不再寫入主機管理狀態或下游服務歷史。

提供者原生的背景輪詢現在需要history_source="service"和background_source="provider"。 轉向功能暫時無法使用,且啟用 steerable_conversations 會在主機建構期間引發 RuntimeError。 關於遷移與設定細節,請參閱 Foundry 託管代理。


🔴 Gemini 使用 GOOGLE_* 設定並新增 Embedding 2

PR:#8798

GeminiChatClient 不再讀取 GEMINI_API_KEY 或 GEMINI_MODEL,匯 GeminiSettings 出資料也被移除。 將配置重新命名為 GOOGLE_API_KEY 和 GOOGLE_MODEL,或明確傳遞這些值。 使用 GOOGLE_EMBEDDING_MODEL 設定嵌入。

新的 GeminiEmbeddingClient 預設為 gemini-embedding-2。 文字嵌入呼叫需要明確的任務類型,例如 RETRIEVAL_DOCUMENT 索引與 RETRIEVAL_QUERY 搜尋。 向量上頁、搜尋及產生的搜尋工具現在接受每個操作的嵌入選項,而向量場維度仍具權威性。

關於設定與範例,請參閱 Google Gemini 與 Vector Store 整合。


🔴 Foundry 調用會話現在使用持久儲存

PR:#8593

InvocationsHostServer 現在會透過 AgentSession 儲存序列化後的 AgentSessionStoreProvider 狀態,而不是在程序的整個生命週期內保留任意的活動工作階段物件。 預設提供者在託管時使用 Foundry 儲存,本地則使用檔案備份儲存,並設有獨立 invocation_sessions 的邏輯儲存庫。

讓自訂會話狀態可序列化,並用 註冊自訂類型的 register_state_type()編解碼器。 還原狀態不會保留 Python 物件的身份。 新的預設儲存區會在工作階段最後一次寫入後 30 天使其過期;保留期限則由自訂提供者控制。 協調同一會話的重疊請求,並為獨立應用程式使用不同的本地儲存根或提供者。 詳情請參閱 Foundry 託管代理程式。


🔴本機工具核准需要簽發工作階段

PR:#8750

本機function_approval_response現在只有在符合記錄於同一個具權威性AgentSession中的待處理核准要求時,才會授權工具呼叫。 將同一個工作階段傳遞給產生核准要求的執行,以及接續該執行的執行。 如果沒有該工作階段,框架會捨棄未繫結的回應,並記錄警告訊息。

託管核准,以及工具呼叫已有終端結果的重新執行對話,均維持不變。 只有當你的應用程式在訊息到達代理前強制執行等效綁定時才設定 disable_approval_response_binding=True 。 關於推薦的會話支援流程,請參見 工具審核。


🔴 已保存的核准記錄必須使用輸入式核准控制項

PR:#8579

Python 現在將每個匹配function_result的視窗視為終端機,不論其文字內容為何。 包含 [APPROVAL_PENDING] 的結果不再表示待核准,且無法使核准權限保持可重放。

如果您的應用程式會持久化保存或手動重新播放無狀態轉錄記錄,請移除待處理的合成 function_result 內容。 以權威性的待處理狀態和具型別的 function_approval_request 控制項來表示待處理工作。 即使其文本包含 [APPROVAL_PENDING],也要將實際完成的函數結果記錄在歷史中。


🔴 MCP 執行時上下文與核准標頭現在分開了

PR:#8589

產生的 Python MCP 工具呼叫現在只會將受信任的主機執行階段關鍵字引數傳給 header_provider。 模型提供的工具參數不再流向提供者,即使名稱衝突。 請將標頭輸入移至 function_invocation_kwargs、提供者閉包或 ContextVar。 如果工具會在執行流程提供執行階段值之前先行連接,請使用閉包或其他在建構時可用的來源。

宣告式 InvokeAzureAgent 執行不再將外部工作流程和客戶關鍵字袋複製到 additional_function_arguments。 當工具需要時,明確在代理選項中傳遞工具參數。

對於需要批准的宣告式 InvokeMcpTool 動作,執行階段現在會將經評估的標頭綁定至該批准。 如果認證資訊或標頭變更、使用未繫結的舊版核准,或缺少驗證狀態,系統會在分派前產生新的核准要求,並指派新的要求 ID。 處理更換請求並保護工作流程檢查點儲存空間。 詳情請參閱 本地 MCP 認證 與 宣告式 MCP 工具。


🔴 宣告式 PowerFx 狀態會拒絕循環並強制遍歷限制

PR:#8511

Python 宣告式工作流程現在拒絕循環狀態,並對每個狀態遍歷強制固定限制:深度為 64,根節點為 0,訪過值為 10,000,以及 1,048,576 個聚合字串字元和二進位位元組。 重複的引用和別名每次出現都會分別計算。 在寫入狀態、建立快照或進行 PowerFx 轉換時,違規情形會引發 ValueError。

在寫入工作流程狀態前,先移除循環並減少或分割過大值。 對 PowerFx 表達式執行和應用程式定義的複製或轉換鉤子分別設限,因為遍歷限制不會限制它們。 詳情請參見 PowerFx 狀態遍歷限制。


🔴 工作流程 HTTP 請求需要絕對的 HTTP(S) URL。

PR:#8588

Python DefaultHttpRequestHandler 現在會拒絕相對且非 HTTP(S) 的網址。 它會正規化 URL 並在呼叫 client_provider前撰寫查詢。 提供者會在 info.url 中收到組合後的 URL,以及一個空的 info.query_parameters。 現有的 URL 查詢順序與位元組會被保留,選擇客戶端預設仍適用,且重定向仍由客戶端控制。

使用絕對的 HTTP 或 HTTPS 工作流程網址。 更新提供者,使其檢查 info.url 而非讀取 info.query_parameters,並在傳回的 httpx.AsyncClient 上設定預設值和重新導向行為。 詳情請參見 HttpRequestAction。


python-1.19.0(2026年9月18日)

發佈說明:python-1.19.0

🔴 MCP 技能檔案僅支援 ZIP,取樣功能已不再使用

PRs:#8290, #8401

MCP 技能檔案必須使用 ZIP 格式。 TAR、.tar.gz、.tgz及其他封存格式會被跳過。 由伺服器起始的 MCP 取樣和 sampling_callback 已被取代;MCP 伺服器應直接呼叫模型提供者的 API。


PR:#8371

由架構管理和由呼叫端管理的 HTTP 用戶端,其 Cookie 行為不再預設相同。 當 A2A、AG-UI、MCP 或宣告式整合需要驗證 Cookie、工作階段 Cookie 或負載平衡器同質性時,請提供已設定的 HTTP 用戶端,並設定其使用範圍。


🔴 Redis 的歷史金鑰包括提供者與會話身份

PR:#8236

Beta 版 Redis 歷程記錄提供者現在會同時依據提供者和工作階段識別,設定持續保存索引鍵的範圍。 在升級依賴先前鍵配置的應用程式前,先檢視現有的 Redis 資料與遷移需求。


🟡 擴充共用向量存放區 API 和連接器

Python 1.19 新增了通用向量存儲協議及 MongoDB、Azure DocumentDB 及 Azure Cosmos DB for NoSQL 的原生連接器。 有關目前套件生命週期與能力的詳細資訊,請參見向量儲存整合。


python-1.18.0(2026年9月10日)

發行說明:python-1.18.0

🔴 Lab 需另外安裝,Foundry 支援 Projects 2.6

PR:#8188

agent-framework 和 agent-framework-core[all] 不再安裝實驗性的 agent-framework-lab 套件。 明確安裝每個實驗室模組。

pip install "agent-framework-lab[gaia]"
pip install "agent-framework-lab[tau2]"
pip install "agent-framework-lab[lightning]"

Lab 現在可不再依賴已發布的 Agent Framework 套件,獨立解析其實驗性相依性。 該 agent-framework-foundry 套件支援 azure-ai-projects>=2.2.0,<2.7.0 並使用 OpenAI 3 相容 agent-framework-openai 版本。 這種分離讓 Foundry 應用程式能使用 Azure AI Projects 2.4 至 2.6,而不會違反 Lab 對 OpenAI 2 相容的依賴性限制。


🔴 GitHub Copilot 工作空間的檔案掛鉤需選擇啟用

PR:#7517

GitHubCopilotAgent 預設情況下不再從 .github/hooks/ 工作目錄載入。 僅為你信任的工作目錄啟用掛鉤。

from agent_framework.github import GitHubCopilotAgent, GitHubCopilotOptions

agent = GitHubCopilotAgent(
    default_options=GitHubCopilotOptions(enable_file_hooks=True),
)

檔案鉤子會在主機上執行指令,且不受 on_permission_request 或其他工具核准回呼的把關。 當 hooks 存在且你省略 enable_file_hooks時,代理程式會預設為 False ,並記錄一次警告。 明確設定 enable_file_hooks=False 會停用掛鉤,且不會出現該警告。 關於設定指引,請參閱 控制工作區檔案鉤子。


🔴 檔案備份儲存使用共享路徑正規化

PR:#8123

檔案支援會話、記憶體與待辦事項現在透過共用的儲存鍵映射來產生資料夾名稱。 包含大寫字母、路徑分隔符號、Unicode 或其他不安全字元的 ID 與範圍,在升級後可能會解析為不同的位置。

現有資料不會自動移動。 如果你需要保留,請將舊檔案或目錄遷移到新產生的位置。 請將其 FileMemoryProvider.scope 視為一個不透明的命名空間鍵,而非巢狀路徑。 例如,tenants/alice 會對應到一個經編碼的資料夾。

TodoFileStore 使用共享映射來設定擁有者 ID,但會拒絕包含或 /\的會話 ID 。 在遷移待辦資料之前,先將這些會話 ID 標準化。


🔴 SecretString 不再繼承自 str

PR:#8127

SecretString 現在可以遮蔽字串轉換、格式化和串接。 要求實際的 str (包括 JSON 序列化在內) 的 API,不再隱式接受包裝函數。 在需要憑證的邊界處明確提取該值:

Before:

payload = json.dumps({"api_key": secret})

After:

payload = json.dumps({"api_key": secret.get_secret_value()})

擷取的值為一般字串,不再防止意外記錄或格式化。


python-1.17.0(2026年9月3日)

發佈說明:python-1.17.0

🔴 中介軟體的輸入需要依序排列,而 Agent Hooks 則需另外安裝

PR:#7918

代理建構子、每次執行的中介軟體輸入,且 create_harness_agent() 不再接受單一中介軟體值。 將中介軟體以序列方式傳遞。 Agent Hooks 套件仍受支援,作為該序列中的其中一個元素。

多餘的部分 agent-framework-core[agent-hooks] 被移除。 直接安裝 agent-hooks-sdk 。

Before:

agent = Agent(client=client, middleware=hooks)

After:

pip install agent-hooks-sdk
agent = Agent(client=client, middleware=[hooks])

python-1.16.0(2026年8月27日)

發行說明:python-1.16.0

🟡 程式化 OpenTelemetry 提供者配置

PR:#7703

configure_otel_providers() 現在可直接接受服務元資料、資源屬性及 OTLP 匯出器選項。 明確的服務元資料優先於環境值。 資源屬性會合併到環境屬性上。 訊號專屬的 OTLP 端點與標頭變數仍比基礎程式設定更為具體。


python-1.15.0(2026年8月21日)

發行說明:python-1.15.0

🔴 OpenTelemetry GenAI 語意慣例已整併

PR:#7673

代理框架現在預設使用最新的實驗性 GenAI span 屬性,包括以 gen_ai.provider.name 取代 gen_ai.system。 將 OTEL_SEMCONV_STABILITY_OPT_IN 設定為省略大小寫區分 gen_ai_latest_experimental 權杖的值,以選取 v1.36 的 span 屬性。 v1.36 的訊息與選擇事件會獨立選擇,當敏感資料被擷取時預設保持啟用狀態,並持續使用 gen_ai.system。 設定 ENABLE_MESSAGE_EVENTS=false 為壓制它們。


🟡 函式中介軟體可以使用 MiddlewareFailure 中止

PR:#7562

當執行必須停止,而不是成為可復原的工具錯誤時,函式中介軟體可以引發 MiddlewareFailure。 函式呼叫迴圈會將此例外傳播給呼叫者,並取消執行中的兄弟工具呼叫。 不要在中介軟體中遇到這個例外,因為這樣可以讓遊戲繼續。

代理程式和聊天中介軟體已會傳遞一般例外。 當函式中介軟體特別需要嚴重且以封閉方式失敗的行為時,請使用 MiddlewareFailure。


python-1.14.0(2026年8月14日)

發行說明:python-1.14.0

🟡 Foundry 聊天功能中的加密推理需由使用者主動啟用

PR:#7536

FoundryChatClient 預設不再要求 reasoning.encrypted_content。 預設設定可避免在不支援的型號上失敗。 對於支援的部署環境,請使用 default_options={"include": ["reasoning.encrypted_content"]} 選擇加入。


🔴 [測試版] Foundry 託管代理程式狀態移至 Foundry 狀態存放區

PR:#7533

PR #7533 從測試agent-framework-foundry-hosting包中移除FoundrySessionStore(path)。 主機現在針對代理程式工作階段、工作流程檢查點和函式核准程序,使用 FoundryAgentSessionStore 以及以 Foundry 狀態存放區支援的預設設定。

  • 移除 FoundrySessionStore 的匯入與建構。
  • 讓 ResponsesHostServer 建立預設提供者。 若要使用自訂儲存,請傳入 agent_session_store_provider、checkpoint_store_provider 或 function_approval_store_provider。
  • 現有的檔案備份狀態不會自動遷移。

針對目前的提供者模型,請參閱保存狀態和處理長時間執行的交談。


🔴 在執行前先建立功能性工作流程定義

PR:#7521

PR #7521 將 @workflow 變更為回傳無狀態的 FunctionalWorkflowDefinition。 呼叫 .build() 以建立一個有狀態的 FunctionalWorkflow。 在呼叫 .run() 或 .as_agent()之前先建立工作流程,並將檢查點儲存空間傳給 .build()。

Before:

@workflow(checkpoint_storage=storage)
async def pipeline(data: str) -> str:
    return await process(data)

result = await pipeline.run("input")
agent = pipeline.as_agent()

After:

@workflow
async def pipeline(data: str) -> str:
    return await process(data)

workflow_instance = pipeline.build(checkpoint_storage=storage)
result = await workflow_instance.run("input")
agent = workflow_instance.as_agent()

為每個邏輯呼叫者或會話建立獨立的工作流程實例,讓執行與重播狀態保持隔離。


🟡 Agent Hooks 會新增以封閉方式失敗的攔截機制

PR:#7515

Agent Framework 透過 create_agent_hooks_middleware() 和 create_agent_hooks_middleware_from_emitter() 新增對 AGENT-HOOKS-0.1 合約的實驗性支援。 中介軟體套件涵蓋代理、模型與函式攔截點,並具備失敗時封閉式判定強制執行、轉換結果回寫、緩衝式串流,以及由判定結果把關的持久化。

對於目前的套件與中介軟體合約,直接安裝 agent-hooks-sdk 並依序傳遞回傳的套件,例如 middleware=[hooks]。 詳情請參見 代理人鉤子。


python-1.8.0(2026年6月4日)

發佈說明:python-1.8.0

🔴 github-copilot-sdk 已升級至 v1.0.0,並包含破壞性 API 變更

PR:#6292

PR #6292 將 agent-framework-github-copilot 從 github-copilot-sdk 1.0.0b2 升級至穩定版 1.0.0,並因應 GA 版本引入的所有破壞性 API 變更。

  • SubprocessConfig 已移除 — 在 RuntimeConnection.for_stdio(path=...) 上使用 CopilotClient + 關鍵字參數(connection、log_level、base_directory)。
  • 進口路徑移動 —— copilot.generated.session_events → copilot.session_events。
  • 設定已重新命名 — copilot_home → base_directory;環境變數現在為 GITHUB_COPILOT_BASE_DIRECTORY(原為 GITHUB_COPILOT_COPILOT_HOME)。
  • 權限處理程式 — 使用具體決策類型而非 PermissionRequestResult(kind=...)。 內建 PermissionHandler.approve_all 的模式取代了手動核准的模式。
  • 預設拒絕處理常式 — 現在會傳回 PermissionDecisionUserNotAvailable()(與 SDK 的後備行為一致)。
  • 權限處理類型 — 現在同時支援同步與非同步回調(Callable[..., PermissionRequestResult | Awaitable[PermissionRequestResult]])。

Before:

from copilot import CopilotClient, SubprocessConfig
from copilot.generated.session_events import PermissionRequest
from copilot.session import PermissionRequestResult

# Client construction
client = CopilotClient(SubprocessConfig(cli_path="/path/to/cli", log_level="debug", copilot_home="/custom/home"))

# Permission handler
def approve_shell(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
    if request.kind == "shell":
        return PermissionRequestResult(kind="approved")
    return PermissionRequestResult(kind="denied-interactively-by-user")

# Agent
agent = GitHubCopilotAgent(default_options={"copilot_home": "/custom/home", "on_permission_request": approve_shell})

After:

from copilot import CopilotClient, RuntimeConnection
from copilot.generated.rpc import PermissionDecisionDeniedInteractivelyByUser, PermissionDecisionUserNotAvailable
from copilot.session import PermissionHandler, PermissionRequestResult
from copilot.session_events import PermissionRequest

# Client construction
client = CopilotClient(connection=RuntimeConnection.for_stdio(path="/path/to/cli"), log_level="debug", base_directory="/custom/home")

# Permission handler — use concrete decision types or PermissionHandler.approve_all
def approve_shell(request: PermissionRequest, context: dict[str, str]) -> PermissionRequestResult:
    if request.kind == "shell":
        return PermissionHandler.approve_all(request, context)
    return PermissionDecisionUserNotAvailable()

# Agent
agent = GitHubCopilotAgent(default_options={"base_directory": "/custom/home", "on_permission_request": approve_shell})

🟡 透過 FunctionInvocationContext 公開漸進式工具

PR:#6233

新增支援以在執行期間使用 FunctionInvocationContext 逐漸公開工具。 工具現在可以根據先前工具的結果,在同一代理執行中動態新增或移除。

完整文件包括模式、注意事項及工具訂購範例,請參見 工具可用性控制。


🟡 基於 MCP 的技能發現(McpSkillsSource)

PR:#6169

新增 McpSkillsSourceagent-framework-core,允許透過 MCP 伺服器發現與載入技能。


🟡 Bedrock 原生結構化輸出支援,透過 Converse API

PR:#6052

agent-framework-bedrock 現已透過 AWS Bedrock Converse API 實現原生結構化輸出支援,允許 response_format 與 Bedrock 模型合作。


🟡 Foundry 調適型評估整合 (評分標準產生)

PR:#6101

為 agent-framework-foundry 新增 Foundry Adaptive Evals 整合,以便在評估工作流程中自動產生評分規準。


🟡 Mistral AI 嵌入客戶端套件

PR:#5480

新增提供 Mistral AI 嵌入用戶端的 agent-framework-mistral 套件。


🟡 agent-framework-declarative 已提升為候選版

PR:#6256

該 agent-framework-declarative 套件從測試版升級為候選版。


python-1.7.0(2026年5月28日)

發布說明:python-1.7.0

🔴 聲明式:移除僅限 Python 的動作,並將別名種類重新命名為 C# 正式名稱

PR:#6126

PR #6126 移除僅Python宣告式動作,並將別名類型重新命名為符合 C# 標準名稱以實現跨語言一致性。

  • 僅有 Python 且沒有 C# 對應的宣告式動作類型會被移除。
  • 動作別名類型現在與 C# 命名規則對齊;相應地更新現有的宣告式 YAML/JSON 檔案。

🟡 HarnessAgent 以及背景代理程式執行框架提供者

PRs:#6041, #6069

將 HarnessAgent 新增至 agent-framework-core,讓由 harness 支援、用於背景處理的代理模式得以實現。


🟡 A2AAgentSession 具有參考的工作識別碼與需要輸入的支援

PR:#5980

將 A2AAgentSession 新增至 agent-framework-a2a 和 agent-framework-core,支援參考的工作識別碼與 A2A 通訊協定互動中需輸入的流程。


🟡 實驗性提示代理轉換與部署 API

PR:#5959

為 agent-framework-foundry 新增實驗性 API,用於將提示詞定義轉換為代理,並以程式設計方式部署。


python-1.6.0(2026年5月21日)

發布說明:python-1.6.0

🔴 預設啟用檢測功能

PR:#5865

PR #5865 在 agent-framework-core 和 agent-framework-foundry 中預設啟用 OpenTelemetry 儀表化。

  • 現在代理程式執行時會自動發出遙測追蹤跨度,無需明確選擇加入。
  • 如果你之前關閉了儀器或有自訂遙測管線,請確認預設行為沒有衝突。
  • 若要停用,請在適用處傳遞 enable_instrumentation=False。

Before:

from agent_framework import Agent
from agent_framework.observability import configure_otel_providers

# Had to explicitly enable instrumentation
configure_otel_providers(enable_console_exporters=True)

agent = Agent(client=client, enable_instrumentation=True)

After:

from agent_framework import Agent

# Instrumentation is now on by default — no opt-in needed
agent = Agent(client=client)

# To explicitly disable:
agent = Agent(client=client, enable_instrumentation=False)

🟡 具備本地與 Docker 執行支援的 Shell 工具

PR:#5664

新增內建 shell 工具 agent-framework-core ,支援本地執行及基於 Docker 的沙盒執行。


🟡 全新 agent-framework-monty CodeAct 提供者套件

PR:#5915

介紹用於由 Monty 支援的 CodeAct 整合的 agent-framework-monty 套件(Alpha 階段)。


python-1.4.0(2026年5月14日)

發行說明:python-1.4.0

🔴 [實驗技能 API] 將檔案技能資料夾探索與 agentskills.io 規格保持一致

PR:#5807

PR #5807 更新了實驗技能 API,使基於檔案的技能資料夾發現與 agentskills.io 規範保持一致。

  • 技能資料夾解析邏輯已經改變;如果使用 Experimental Skills API,請更新自訂技能目錄的佈局。

🔴 [實驗技能 API] 將技能規格中繼資料擷取至 SkillFrontmatter

PR:#5775

PR #5775 將技能規格的元資料移入專用 SkillFrontmatter 資料類別。

  • 如果您直接存取技能中繼資料欄位,請更新參考以使用 SkillFrontmatter 屬性。

🔴 DevUI:加強預設存取控制與 CORS 態勢

PR:#5740

PR #5740 收緊了 agent-framework-devui 的預設存取控制與 CORS 設定。

  • 預設的 CORS 來源現在更為嚴格。
  • 如果你的 DevUI 設定依賴自訂網域的跨來源存取,請明確設定允許的來源。

🔴 A2A:遷移到 a2a-sdk v1.0

PR:#5752

PR #5752 將 agent-framework-a2a 遷移至 a2a-sdk v1.0。

  • A2A 協定類型與傳輸 API 遵循 a2a-sdk 1.0 慣例。
  • 更新任何直接與 A2A 協定類型互動的程式碼。

🟡 AG-UI:工具結果顯示通道與候選版本推廣

PRs:#5762, #5844

在 agent-framework-ag-ui 中新增工具結果顯示通道,並將套件提升至發行候選階段。


python-1.3.0(2026年5月7日)

發布說明:python-1.3.0

🔴 [實驗技能 API]將代理技能重組為多來源架構

PR:#5584

PR #5584 重新架構了實驗技能 API,以支援多來源技能載入。

  • 實驗技能功能的技能註冊與發現邏輯有所改變。
  • 若使用 experimental skills API,請檢視新的多源碼載入慣例。

🟡 ClassSkill 針對以類別為基礎的技能定義

PR:#5678

將 ClassSkill 新增至 agent-framework-core,以支援具備宣告式中繼資料與自動方法探索功能的類別型技能定義。


🟡 資訊流控制提示注入防禦

PR:#5331

新增資訊流控制機制 agent-framework-core ,有助於防禦即時注入攻擊。


🟡 github-copilot-sdk 升級至 v1.0.0b2

PR:#5665

agent-framework-github-copilot升級至 github-copilot-sdk>=1.0.0b2、新增instruction_directories、copilot_home配置及執行時選項在會話恢復時轉發。


🟡 在 Claude 和 GitHub Copilot 代理程式中強制套用 approval_mode

PR:#5562

agent-framework-claude 和 agent-framework-github-copilot 現在會在函式工具上強制套用 approval_mode 裝飾器,與其他代理程式實作一致。


🟡 OpenAI 與 Gemini allowed_tools 工具選擇支援

PR:#5322

新增對 allowed_tools 工具選擇的支援,讓您可以在 agent-framework-openai 中限制模型可呼叫哪些工具。


python-1.2.2(2026年4月29日)

發佈說明:python-1.2.2

🔴 編排終端輸出標準化為 AgentResponse

PR:#5301

PR #5301 標準化了編排終端的輸出,因此AgentResponseWorkflow.as_agent()只回傳最終答案。

  • 循序核准(with_request_info)與並行(intermediate_outputs=True)流程現在遵循相同的輸出規格。
  • 如果你直接取用編排結果,應預期取得的是 AgentResponse 物件,而不是原始文字或混合型別資料。

Before:

# Orchestration returned mixed types (raw strings, dicts, etc.)
result = await workflow.as_agent().run("Draft a report")
text = str(result)  # had to handle various types

After:

# Orchestration now always returns AgentResponse
result = await workflow.as_agent().run("Draft a report")
text = result.text  # consistent AgentResponse API

🟡 Azure AI 內容理解情境提供者

PR:#4829

全新 alpha 套件 agent-framework-azure-contentunderstanding — 自動分析檔案附件(文件、圖片、音訊、影片),並將結構化結果注入 LLM 上下文中。


🟡 透過 Foundry 託管提供的託管式 Durable Workflow 支援

PR:#5531

為 agent-framework-foundry-hosting 新增託管 Durable Workflow 支援,並將完整對話歷史傳遞給工作流程代理程式。


python-1.1.0(2026年4月21日)

發布說明:python-1.1.0

🔴 CosmosCheckpointStorage 預設限制 pickle 還原序列化

PR:#5200

CosmosCheckpointStorage 現在預設使用受限制的 pickle 還原序列化,與 FileCheckpointStorage 的行為一致。

  • 如果你的檢查點包含應用程式定義的型別,請透過 allowed_checkpoint_types=["my_app.models:MyState"]傳遞。
  • 若沒有這個,自訂類型的還原序列化將會引發 WorkflowCheckpointException。

Before:

from agent_framework.azure.cosmos import CosmosCheckpointStorage

storage = CosmosCheckpointStorage(endpoint=endpoint, database="mydb", container="checkpoints")

After:

from agent_framework.azure.cosmos import CosmosCheckpointStorage

storage = CosmosCheckpointStorage(
    endpoint=endpoint,
    database="mydb",
    container="checkpoints",
    allowed_checkpoint_types=["my_app.models:MyState"],
)

🟡 GeminiChatClient 新增內容

PR:#4847

新的 agent-framework-gemini 套件,支援 GeminiChatClientGoogle Gemini API 和 Vertex AI。


🟡 超輕量 CodeAct 套件

PR:#5185

用於以 Hyperlight 為基礎的 CodeAct 沙盒程式碼執行的全新 agent-framework-hyperlight 套件。


🟡 Foundry 工具箱支援

PR:#5346

新增對 agent-framework-foundry Foundry 工具箱的支援,允許從 Azure AI Foundry 進行受管工具配置。


🟡 finish_reason 在 AgentResponse 和 AgentResponseUpdate 上

PR:#5211

在finish_reason和AgentResponse中加入AgentResponseUpdate欄位,讓使用者能查看模型為何停止生成。


🟡 Foundry 中的託管代理 V2 支援

PR:#5379

在 agent-framework-foundry 中新增對託管代理程式 V2 的支援,以支援最新的 Foundry 代理程式服務功能。


python-1.0.1(2026年4月9日)

發行說明:python-1.0.1

🔴 FileCheckpointStorage 限制 pickle 還原序列化 (安全性強化)

PR:#4941

檢查點的反序列化現在預設會透過受限的 Unpickler 進行,該 Unpickler 只允許一組內建的安全 Python 類型以及所有 agent_framework 框架類型。

  • 如果您的應用程式在檢查點中儲存自訂型別,請透過新的 "module:qualname" 建構參數傳遞其 allowed_checkpoint_types 識別碼,否則載入時將引發 WorkflowCheckpointException。
  • 詳情請參見 安全考量 。

Before:

from agent_framework.workflows import FileCheckpointStorage

storage = FileCheckpointStorage(directory="./checkpoints")

After:

from agent_framework import FileCheckpointStorage

storage = FileCheckpointStorage(
    directory="./checkpoints",
    allowed_checkpoint_types=["my_app.models:MyState", "my_app.models:TaskResult"],
)

🔴 轉接工作流程的內容管理修正

PR:#5136

PR #5136 解決了交接工作流程的情境管理。 這是一項行為變更 — 轉接代理程式現在可在轉換過程中正確維持隔離的內容。


工作流程的 🟡 Cosmos DB NoSQL 檢查點儲存體

PR:#4916

全新 agent-framework-azure-cosmos 套件,為 Python 工作流程提供以 Cosmos DB NoSQL 為後端的檢查點儲存體。


python-1.0.0(2026年4月2日)

發行說明:python-1.0.0

本節將記錄 Python 在 python-1.0.0rc6 之後引入的重大變更,並已成為 python-1.0.0 的一部分。

🔴 Message(..., text=...) 建築現已完全拆除

PR:#5062

PR #5062 完成了早期 Python 訊息模型的清理,移除了最後那些仍在架構端使用 text=... 建構 Message 物件的程式碼路徑。

  • 將簡訊建立為Message(role="user", contents=["Hello"])而非Message(role="user", text="Hello")。
  • 這適用於任何直接建構訊息的領域,包括工作流程請求、自訂中介軟體回應、編排輔助工具及遷移程式碼。
  • 內部 contents=[...] 的純字串仍會自動正規化成文字內容,因此 contents=["Hello"] 仍是最簡單的純文字形式。

Before:

message = Message(role="assistant", text="Hello")

After:

message = Message(role="assistant", contents=["Hello"])

🟡 已發布的 Python 套件不再需要 --pre

PR:#5062

PR #5062 將主要的 Python 套件推廣至 1.0.0,並更新安裝指引,以區分已發佈的套件與仍在預發布版本階段的套件。

  • agent-framework、agent-framework-core、agent-framework-openai和agent-framework-foundry現在都是已發布的套件,不再需要--pre。
  • Beta 連接器如 agent-framework-ag-ui、agent-framework-azurefunctions、agent-framework-copilotstudio、agent-framework-foundry-local、agent-framework-github-copilot、agent-framework-mem0、agent-framework-ollama 仍然需要 --pre。
  • 如果單一安裝命令包含任何搶鮮版 (Beta) 套件,請讓 --pre 持續使用該命令。

🔴 Foundry 現在擁有 Python 嵌入與模型端點設定

PR:#5056

PR #5056 移除了獨立 agent-framework-azure-ai 套件,並將 Python 嵌入表面移至 agent-framework-foundry 和 agent_framework.foundry。

  • 使用 FoundryEmbeddingClient、 FoundryEmbeddingOptions和 FoundryEmbeddingSettings 來自 agent_framework.foundry。
  • 安裝 agent-framework-foundry 以用於 Foundry 聊天、服務受控代理程式、記憶體提供者及內嵌功能。
  • agent_framework.azure 不再匯 AzureAIInferenceEmbeddingClient出 、 AzureAIInferenceEmbeddingOptions、 AzureAIInferenceEmbeddingSettings或 AzureAISettings。
  • Foundry 嵌入現在使用 FOUNDRY_MODELS_ENDPOINT、FOUNDRY_MODELS_API_KEY、FOUNDRY_EMBEDDING_MODEL 及可選的 FOUNDRY_IMAGE_EMBEDDING_MODEL。
  • FoundryChatClient 同時 FoundryAgent 仍使用專案端點設定,如 FOUNDRY_PROJECT_ENDPOINT 和 FOUNDRY_MODEL。

Before:

import os

from agent_framework.azure import AzureAIInferenceEmbeddingClient

client = AzureAIInferenceEmbeddingClient(
    endpoint=os.environ["AZURE_AI_SERVICES_ENDPOINT"],
    model=os.environ["AZURE_AI_EMBEDDING_NAME"],
    credential=credential,
)

After:

import os

from agent_framework.foundry import FoundryEmbeddingClient

client = FoundryEmbeddingClient(
    endpoint=os.environ["FOUNDRY_MODELS_ENDPOINT"],
    api_key=os.environ["FOUNDRY_MODELS_API_KEY"],
    model=os.environ["FOUNDRY_EMBEDDING_MODEL"],
)

🔴 工作流程現在會將執行階段 kwarg 路由到明確的貯體中

PR:#5010

PR #5010 更新了 Python workflow.run(...),因此執行時的 kwargs 會被明確地傳遞為 function_invocation_kwargs= 和 client_kwargs=,而不是泛型地轉發為 **kwargs。

  • 平面映射被視為全域,並會轉發給工作流程中所有匹配的代理執行者。
  • 如果一或多個頂層鍵符合執行程式識別碼,整個對應將被視為針對個別執行程式的目標設定,且每個執行程式只會接收到屬於自己的項目。
  • 自訂AgentExecutor(id="...")及其他明確的工作流程執行 ID 是你要鎖定的鍵。
  • 相同的全域與目標規則適用於 function_invocation_kwargs 和 client_kwargs。

Before:

await workflow.run(
    "Draft the report",
    db_config={"connection_string": "..."},
    user_preferences={"format": "markdown"},
)

After:

await workflow.run(
    "Draft the report",
    function_invocation_kwargs={
        "researcher": {
            "db_config": {"connection_string": "..."},
        },
        "writer": {
            "user_preferences": {"format": "markdown"},
        },
    },
)

🟡 GitHubCopilotAgent 現在在每次調用時會執行上下文提供者

PR:#5013

PR #5013 修正了一個 Python 行為差距,其中 GitHubCopilotAgent 接受了 context_providers,但實際上並未叫用它們。

  • before_run() 現在在發送 Copilot 提示前就已執行。
  • 提供者新增的訊息與指令會包含在送達 Copilot CLI 的提示中。
  • after_run() 現在會在最終回應組建完成後執行,包括串流路徑。

如果您已經將 context_providers 傳遞給 GitHubCopilotAgent,則不需要進行移轉 — 這些勾點現在的行為與 Python 代理程式介面的其餘部分一致。


🟡 結構化輸出現在除了 Pydantic 模型外,也接受 JSON 架構映射

PR:#5022

PR #5022 擴展了 Python 結構化輸出解析,可以 response_format 是 Pydantic 模型或 JSON 架構映射。

  • Pydantic 模型仍會剖析為 response.value 上具類型的模型執行個體。
  • JSON 結構描述對應現在會在 response.value (通常是 dict 或 list) 剖析為與 JSON 相容的 Python 值。
  • 當你從串流收集最終回應時,同樣的解析規則也適用。

這是改進而非破壞性變更,但知道你是否已經以類似 JSON 字典的方式儲存結構會很有用。


python-1.0.0rc6

本節記錄了隨 python-1.0.0rc6 一同發佈或針對它追蹤的重大 Python 變更。

🔴 模型選擇標準化為 model

PR:#4999

PR #4999 完成了 Python 端的模型選擇清理,涵蓋建構子、型別選項、代理預設值、回應物件及環境變數。

  • 將 model 用於你之前使用 model_id 的所有地方。
  • Agent.default_options 與每次執行的 options={...} 現在預期 "model",而非 "model_id"。
  • 回應物件顯示response.model,而不是response.model_id。
  • OpenAI 設定現在使用 OPENAI_MODEL、 OPENAI_CHAT_MODEL、 OPENAI_CHAT_COMPLETION_MODEL和 OPENAI_EMBEDDING_MODEL。
  • Azure OpenAI 設定現在會使用 AZURE_OPENAI_MODEL、AZURE_OPENAI_CHAT_MODEL、AZURE_OPENAI_CHAT_COMPLETION_MODEL 和 AZURE_OPENAI_EMBEDDING_MODEL。
  • Anthropic 現在使用 ANTHROPIC_CHAT_MODEL,而 Foundry Local 則使用 FOUNDRY_LOCAL_MODEL。
  • Anthropic 套件也新增了由提供者託管的包裝器,如 AnthropicFoundryClient、AnthropicBedrockClient 和 AnthropicVertexClient。

Before:

from agent_framework.anthropic import AnthropicClient

client = AnthropicClient(model_id="claude-sonnet-4-5-20250929")
response = await client.get_response(
    "Hello!",
    options={"model_id": "claude-sonnet-4-5-20250929"},
)

After:

from agent_framework.anthropic import AnthropicClient

client = AnthropicClient(model="claude-sonnet-4-5-20250929")
response = await client.get_response(
    "Hello!",
    options={"model": "claude-sonnet-4-5-20250929"},
)

🔴 情境提供者可新增中介軟體,並在每個模型呼叫中持續保存歷史紀錄

PR:#4992

PR #4992 更新了 Python 上下文提供者流程,以及框架管理歷史在多重呼叫執行中可持續保存的方式。

  • ContextProvider 和 HistoryProvider 現在是 Python 的典範基底類別。
  • BaseContextProvider 和 BaseHistoryProvider 為了相容性而暫時保留為棄用的代名,但新程式碼應該遷移至新名稱。
  • SessionContext 現在能透過 extend_middleware() 收集提供者新增的聊天或功能中介軟體,並透過 get_middleware() 公開扁平化清單。
  • Agent(..., require_per_service_call_history_persistence=True) 在每次模型呼叫前後執行歷史紀錄提供者,而不是在完整的 run() 之後才執行一次。
  • 此模式用於框架管理的地方歷史,無法與現有的服務管理對話(如 session.service_session_id 或 options={"conversation_id": ...})合併使用。

Before:

from agent_framework import BaseHistoryProvider

class CustomHistoryProvider(BaseHistoryProvider):
    ...

After:

from agent_framework import Agent, HistoryProvider

class CustomHistoryProvider(HistoryProvider):
    ...

agent = Agent(
    client=client,
    context_providers=[CustomHistoryProvider()],
    require_per_service_call_history_persistence=True,
)

🔴 已停用的 Azure/OpenAI 相容性界面已移除

PR:#4990

PR #4990 藉由移除在早期預覽版本中仍保持可用的剩餘已棄用 Python 相容性介面,完成了從 #4818 提供者主導的移轉。

  • agent_framework.azure 不再匯 AzureOpenAI* 出,舊 AzureAI* 的代理人/客戶/提供者也不再出現。
  • Python OpenAI 助理的相容性類型已不再是目前 agent_framework.openai 表面的一部分。
  • 直接使用 OpenAIChatClient、 OpenAIChatCompletionClient和 OpenAIEmbeddingClient 來處理直接的 OpenAI 或 Azure OpenAI 情境。
  • 使用 FoundryChatClient 進行 Foundry 專案推論,並將 FoundryAgent 用於提示代理程式或託管代理程式。
  • 目前agent_framework.azure的命名空間涵蓋了剩餘的 Azure 整合功能,例如 Foundry IQ(Azure AI 搜尋服務)、Cosmos 歷史、Azure Functions 以及耐用工作流程。 Foundry 聊天、代理、記憶體和嵌入客戶端都位於agent_framework.foundry。

如果你正在遷移較舊的 Python 程式碼,請使用以下替換程式:

  • AzureOpenAIResponsesClient → OpenAIChatClient
  • AzureOpenAIChatClient → OpenAIChatCompletionClient
  • AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
  • AzureAIAgentClient / AzureAIClient / AzureAIProjectAgentProvider / AzureAIAgentsProvider → FoundryChatClient 或 FoundryAgent,取決於你的應用程式是否擁有代理定義
  • OpenAIAssistantsClient / OpenAIAssistantProvider → OpenAIChatClient 用於目前的 Python OpenAI 工作,或 FoundryAgent 若您需要 Foundry 中由服務管理的代理。

🔴 具有領先地位的供應商的客戶導向設計與套件分拆

PR:#4818

PR #4818 會重新組織 Python 提供者表面,圍繞提供者專屬的套件與命名空間。

  • OpenAI 客戶端現在存在於 agent-framework-openai 封包中,但仍然可以從 agent_framework.openai 命名空間匯入。
  • Microsoft Foundry 用戶端現在都存在於套件 agent-framework-foundry 與 agent_framework.foundry 命名空間中。
  • Foundry Local 也從 agent_framework.foundry 公開為 FoundryLocalClient。
  • OpenAIResponsesClient 被重新命名為 OpenAIChatClient。
  • OpenAIChatClient 被重新命名為 OpenAIChatCompletionClient。
  • 用戶端配置標準化於 model,取代舊有參數如 model_id、 deployment_name、 model_deployment_name。
  • 對於新的 Azure OpenAI 程式碼,請使用 agent_framework.openai 用戶端。 早期 AzureOpenAI* 的相容墊片在 #4990 後期被移除。
  • 對於新的 Foundry 程式碼,請使用 FoundryChatClient 進行直接專案推論,將 FoundryAgent 用於提示代理程式與託管代理程式,並將 FoundryLocalClient 用於本機執行階段。
  • AzureAIClient、AzureAIProjectAgentProvider、AzureAIAgentClient、AzureAIAgentsProvider 以及 Python 助手的相容性界面在這次重構中已移至相容性路徑,後來在 #4990 中被移除。
  • 範例涵蓋範圍已重新組織,以符合新的提供者主導配置,包含 samples/02-agents/providers/foundry/ 底下的 Foundry 範例。

套件映射

情境 Install 主要命名空間
OpenAI 與 Azure OpenAI pip install agent-framework-openai agent_framework.openai
Microsoft Foundry 專案端點、代理服務、記憶體與嵌入 pip install agent-framework-foundry agent_framework.foundry
當地鑄造廠 pip install agent-framework-foundry-local --pre agent_framework.foundry

Before:

from agent_framework.openai import OpenAIResponsesClient

client = OpenAIResponsesClient(model_id="gpt-5.4")

After:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(model="gpt-5.4")

如果你之前直接使用 Azure OpenAI,請將舊有的專用類別對應到新的領先 OpenAI 類別:

  • AzureOpenAIResponsesClient → OpenAIChatClient
  • AzureOpenAIChatClient → OpenAIChatCompletionClient
  • AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
  • AzureOpenAIAssistantsClient → OpenAIChatClient 用於直接的 Responses API 移轉,或者如果您需要服務受控 Foundry 代理程式,則使用 FoundryAgent

這次代碼的改變主要是類別名稱的移動以及 deployment_name → model。 為了 Azure OpenAI 相容性,請在新的 OpenAI 用戶端使用明確的 Azure 輸入。 credential= 現在是偏好的 Azure 驗證介面,而可呼叫的 api_key 仍是相容性路徑:

之前(AzureOpenAIResponsesClient):

from agent_framework.azure import AzureOpenAIResponsesClient

client = AzureOpenAIResponsesClient(
    endpoint=azure_endpoint,
    deployment_name=deployment_name,
    credential=credential,
)

()OpenAIChatClient 之後:

from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

api_version = "your-azure-openai-api-version"

client = OpenAIChatClient(
    azure_endpoint=azure_endpoint,
    model=deployment_name,
    credential=AzureCliCredential(),
    api_version=api_version,
)

之前(AzureOpenAIChatClient):

from agent_framework.azure import AzureOpenAIChatClient

client = AzureOpenAIChatClient(
    endpoint=azure_endpoint,
    deployment_name=deployment_name,
    credential=credential,
)

()OpenAIChatCompletionClient 之後:

from agent_framework.openai import OpenAIChatCompletionClient
from azure.identity import AzureCliCredential

api_version = "your-azure-openai-api-version"

client = OpenAIChatCompletionClient(
    azure_endpoint=azure_endpoint,
    model=deployment_name,
    credential=AzureCliCredential(),
    api_version=api_version,
)

如果你想從 Azure OpenAI 端點轉移到 Microsoft Foundry 專案端點,請改用 Foundry 導向的表面:

Before (Azure OpenAI 端點):

from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential

client = AzureOpenAIResponsesClient(
    deployment_name="gpt-4.1",
    credential=AzureCliCredential(),
)

之後 (Foundry 專案):

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

client = FoundryChatClient(
    project_endpoint="https://your-account.services.ai.azure.com/api/projects/your-project",
    model="gpt-4.1",
    credential=AzureCliCredential(),
)

agent = Agent(client=client)

對於本地的 Microsoft Foundry 執行環境,請使用 Foundry 命名空間加上本地連接器:

from agent_framework.foundry import FoundryLocalClient

client = FoundryLocalClient(model="phi-4-mini")

如果你省略了 model,請設定 FOUNDRY_LOCAL_MODEL 在你的環境裡。

同時在適用時更新環境/設定名稱:

  • 使用OPENAI_CHAT_MODEL來替代OpenAIChatClient,OPENAI_CHAT_COMPLETION_MODEL來替代OpenAIChatCompletionClient,並使用OPENAI_MODEL作為共同的備援措施。
  • Azure OpenAI 現在使用 AZURE_OPENAI_CHAT_MODEL 對應 OpenAIChatClient、AZURE_OPENAI_CHAT_COMPLETION_MODEL 對應 OpenAIChatCompletionClient,並把 AZURE_OPENAI_MODEL 作為共用的備援。
  • 將 azure_endpoint 用於 Azure OpenAI 資源 URL,或者如果您已經有完整的 .../openai/v1 URL,則使用 base_url,並為您正在使用的 Azure OpenAI API 介面設定 api_version
  • 採用 Foundry 專屬設定,如 FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_MODEL、FOUNDRY_AGENT_NAME 和 FOUNDRY_AGENT_VERSION,以支援雲端 Foundry 客戶端。
  • 將 ANTHROPIC_CHAT_MODEL 用於 Anthropic,並將 FOUNDRY_LOCAL_MODEL 用於 Foundry Local

這個變化首次出現在週期 python-1.0.0rc6 中。


🔴 現在,核心相依性已經有意地變得更加精簡

PR:#4904

PR #4904 精簡 agent-framework-core 並從核心套件中移除更多提供者的傳遞相依性,藉此延續了 #4818 的提供者套件分割。

  • agent-framework-core 現在刻意保持最小化。
  • 如果你匯入 agent_framework.openai,請安裝 agent-framework-openai。
  • 如果您匯入 agent_framework.foundry,請安裝 agent-framework-foundry 以用於 Foundry 專案推論、服務受控代理程式、記憶體提供者及內嵌功能。 請用 agent-framework-foundry-local --pre 於本地執行時。
  • 如果你在目前的最小安裝中使用 MCP 工具、Agent.as_mcp_server() 或其他 MCP 整合,請手動安裝mcp>=2.2.0,<3。 MCP WebSocket 傳輸功能在 Python 1.23 中被移除。
  • 如果你想要全面的「全部包含」體驗,就安裝 Meta 套件 agent-framework。

這 不會 再次重新設計提供者介面;當你只啟用核心時,預設安裝的內容會有所改變。

之前(僅安裝核心時,常常會推導出更多提供者的功能):

pip install agent-framework-core

之後(安裝你實際使用的提供者套件):

pip install agent-framework-core
pip install agent-framework-openai

or:

pip install agent-framework-core
pip install agent-framework-foundry

如果您升級先前依賴於核心套件加上延遲提供者匯入的現有專案,請檢查您的匯入,並在您的環境或相依性檔案中明確指定提供者套件。 如果你依賴 MCP 工具或 MCP 伺服器主機,也要對 MCP 相依性做同樣的事。


🔴 一般的 OpenAI 用戶端現在偏好明確路由訊號

PR:#4925

PR #4925 變更了一般 agent_framework.openai 用戶端在 OpenAI 與 Azure OpenAI 之間進行抉擇的方式。

  • 一般的 OpenAI 用戶端不再因為 AZURE_OPENAI_* 環境變數存在而切換到 Azure。
  • 如果已設定 OPENAI_API_KEY,通用客戶端會留在 OpenAI,除非您傳遞明確的 Azure 路由訊號(例如 credential 或 azure_endpoint)。
  • 如果只有 AZURE_OPENAI_* 設定,通用用戶端仍可退回 Azure 環境路由。
  • 現在首選的 Azure OpenAI 模式是將明確的 Azure 設定以及 credential=AzureCliCredential() 傳遞至 OpenAIChatClient、OpenAIChatCompletionClient 和嵌入客戶端。
  • 已 AzureOpenAI* 棄用的包裝器會保留其相容性行為,因此現有的包裝程式碼不會遵循新的通用客戶端優先規則。

之前 (因為存在 Azure 環境變數,OpenAIChatClient 可以路由至 Azure):

import os
from agent_framework.openai import OpenAIChatClient

os.environ["OPENAI_API_KEY"] = "sk-openai"
os.environ["AZURE_OPENAI_ENDPOINT"] = "https://your-resource.openai.azure.com"
os.environ["AZURE_OPENAI_CHAT_MODEL"] = "gpt-4o-mini"

client = OpenAIChatClient(model="gpt-4o-mini")

之後 (一般 OpenAI 保持使用 OpenAI;傳遞明確的 Azure 輸入以強制執行 Azure 路由):

import os
from agent_framework.openai import OpenAIChatClient
from azure.identity import AzureCliCredential

client = OpenAIChatClient(
    model=os.environ["AZURE_OPENAI_CHAT_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

如果你的環境同時包含兩者 OPENAI_* 和 AZURE_OPENAI_* 價值觀,請審核任何通用 agent_framework.openai 的客戶端建構,並明確做出供應商選擇。 因此,Azure 提供者範例更新為直接傳遞 Azure 輸入。

Azure embeddings 現在採用相同的路由模型:

import os
from agent_framework.openai import OpenAIEmbeddingClient
from azure.identity import AzureCliCredential

client = OpenAIEmbeddingClient(
    model=os.environ["AZURE_OPENAI_EMBEDDING_MODEL"],
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    credential=AzureCliCredential(),
)

若為內嵌功能情境,請對應:

  • AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
  • AZURE_OPENAI_EMBEDDING_MODEL → model
  • OPENAI_EMBEDDING_MODEL 仍然是 OpenAI 端的嵌入環境變數

python-1.0.0rc5 / python-1.0.0b260319(2026年3月19日)

🔴 聊天用戶端管線已重新排序:現在由 FunctionInvocation 包裝 ChatMiddleware

PR:#4746

ChatClient 流程順序已經改變。 FunctionInvocation 現在是最外層並包裝了 ChatMiddleware,這表示對話中介軟體會在每次模型呼叫時執行 (包括工具呼叫迴圈的每次反覆運算),而不是在整個函式叫用序列周圍執行一次。

舊管線訂單:

ChatMiddleware → FunctionInvocation → RawChatClient

新的管線訂單:

FunctionInvocation → ChatMiddleware → ChatTelemetry → RawChatClient

如果您有自訂的聊天中介軟體,假設每次代理調用只運行一次(包裝整個工具調用迴圈),請更新其設計以確保可以安全地重複執行。 聊天中介軟體現在會在每個個別的 LLM 要求時被叫用,包含將工具結果傳回給模型的要求。

此外,ChatTelemetry 現在是管線中獨立於 ChatMiddleware 之外的一層,且最接近 RawChatClient。

🔴 公用執行階段 kwarg 已拆分為明確的貯體

PR:#4581

公開的 Python 代理程式與聊天 API 不再將全面公開 **kwargs 轉發視為主要的執行時資料機制。 執行時值現在依用途劃分:

  • 使用 function_invocation_kwargs 來處理僅限工具或函式中介軟體可見的值。
  • 使用 client_kwargs 來處理用戶端層級的 kwarg 與用戶端中介軟體組態。
  • 透過 FunctionInvocationContext (ctx.kwargs 和 ctx.session) 存取工具/執行時資料。
  • 定義以注入上下文參數 **kwargs代替的工具;注入上下文參數不會顯示在模型所見的結構中。
  • 當將子代理作為工具進行委派時,如果子代理必須共享呼叫者的會話,請使用 agent.as_tool(propagate_session=True)。

Before:

from typing import Any

from agent_framework import tool


@tool
def send_email(address: str, **kwargs: Any) -> str:
    return f"Queued email for {kwargs['user_id']}"


response = await agent.run(
    "Send the update to finance@example.com",
    user_id="user-123",
    request_id="req-789",
)

After:

from agent_framework import FunctionInvocationContext, tool


@tool
def send_email(address: str, ctx: FunctionInvocationContext) -> str:
    user_id = ctx.kwargs["user_id"]
    session_id = ctx.session.session_id if ctx.session else "no-session"
    return f"Queued email for {user_id} in {session_id}"


response = await agent.run(
    "Send the update to finance@example.com",
    session=agent.create_session(),
    function_invocation_kwargs={
        "user_id": "user-123",
        "request_id": "req-789",
    },
)

如果你實作自訂的公開 run() 或 get_response() 方法,請在那些簽名中加入 function_invocation_kwargs 和 client_kwargs 。 對於工具,建議使用標註為FunctionInvocationContext的參數,這個參數可以命名為ctx、context或任何其他標註名稱。 如果你提供明確的結構/輸入模型,也會識別一個普通且未註解的 ctx 參數名稱。 同一個上下文物件也可用於函式中介軟體,且執行時函式 kwargs 與會話狀態現存於此。 依賴 **kwargs 的工具定義現在僅使用舊版相容性路徑,並將被移除。


python-1.0.0rc4 / python-1.0.0b260311 (2026年3月11日)

發行說明:python-1.0.0rc4

🔴 Azure AI 整合現在目標指向 azure-ai-projects 2.0 GA

PR:#4536

Python Azure AI 整合現在假設使用 GA 2.0 azure-ai-projects 界面。

  • 目前支援的相依範圍為 azure-ai-projects>=2.0.0,<3.0。
  • foundry_features Passthrough 功能已從 Azure AI 代理建立中移除。
  • 目前,預覽行為在支援的客戶端/提供者上使用 allow_preview=True。
  • 混合的搶鮮版 (Beta)/GA 相容性填充碼已移除,請將所有匯入與類型名稱更新至 2.0 GA SDK 介面。

🔴 GitHub Copilot 工具處理常式現在使用 ToolInvocation / ToolResult 和 Python 3.11+

PR:#4551

agent-framework-github-copilot 現在追蹤 github-copilot-sdk>=0.1.32。

  • 工具處理者會接收一個 ToolInvocation 資料類別,而非原始 dict資料。
  • 使用 result_type 和 text_result_for_llm 等 snake_case 欄位傳回 ToolResult。
  • 此 agent-framework-github-copilot 套件現在需要 Python 3.11+。

Before:

from typing import Any


def handle_tool(invocation: dict[str, Any]) -> dict[str, Any]:
    args = invocation.get("arguments", {})
    return {
        "resultType": "success",
        "textResultForLlm": f"Handled {args.get('city', 'request')}",
    }

After:

from copilot.tools import ToolInvocation, ToolResult


def handle_tool(invocation: ToolInvocation) -> ToolResult:
    args = invocation.arguments
    return ToolResult(
        result_type="success",
        text_result_for_llm=f"Handled {args.get('city', 'request')}",
    )

python-1.0.0rc3 / python-1.0.0b260304(2026年3月4日)

發行說明:python-1.0.0rc3

🔴 技能提供者已圍繞程式碼所定義的 Skill / SkillResource 進行最終定案

PR:#4387

Python 智能代理技能現在支援以程式碼定義的 Skill 和 SkillResource 物件,以及基於檔案的技能,公開提供者界面也標準化於 SkillsProvider。

  • 如果你還匯入舊的預覽/內部 FileAgentSkillsProvider版本,請切換到 SkillsProvider。
  • 以檔案為基礎的資源查詢不再依賴 SKILL.md 中以反引號引用的參考;資源改從技能目錄中探索。

如果你有導入預覽版或內部程式碼FileAgentSkillsProvider,請切換到目前的公開介面:

from agent_framework import Skill, SkillResource, SkillsProvider

python-1.0.0rc2 / python-1.0.0b260226(2026年2月26日)

發行說明:python-1.0.0rc2

🔴 宣告式工作流程將替換 InvokeTool 為 InvokeFunctionTool

PR:#3716

宣告式 Python 工作流程不再使用舊有 InvokeTool 的動作類型。 將它替換為 InvokeFunctionTool ,並將 Python 可調用物件註冊為 WorkflowFactory.register_tool()。

Before:

actions:
  - kind: InvokeTool
    toolName: send_email

After:

factory = WorkflowFactory().register_tool("send_email", send_email)
actions:
  - kind: InvokeFunctionTool
    functionName: send_email

python-1.0.0rc1 / python-1.0.0b260219 (2026年2月19日)

發布:agent-framework-core和agent-framework-azure-ai 升級為1.0.0rc1。 其他所有套件均更新至 1.0.0b260219。

🔴 統一的 Azure 憑證處理涵蓋所有套件

PR:#4088

ad_token、ad_token_provider 和 get_entra_auth_token 參數和輔助參數已統一替換為 credential 參數,適用於所有與 Azure 相關的 Python 套件。 新方法採用 azure.identity.get_bearer_token_provider 進行自動憑證快取與更新。

受影響的職業:AzureOpenAIChatClient, AzureOpenAIResponsesClient, AzureOpenAIAssistantsClient, AzureAIClient。 AzureAIAgentClientAzureAIProjectAgentProviderAzureAIAgentsProviderAzureAISearchContextProviderPurviewClientPurviewPolicyMiddlewarePurviewChatPolicyMiddleware

Before:

from azure.identity import AzureCliCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    AzureCliCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAIResponsesClient(
    azure_ad_token_provider=token_provider,
    ...
)

After:

from azure.identity import AzureCliCredential

client = AzureOpenAIResponsesClient(
    credential=AzureCliCredential(),
    ...
)

參數 credential 接受 TokenCredential、 AsyncTokenCredential,或可呼叫的 token 提供者。 權杖快取與重新整理會自動處理。


🔴 重新設計的 Python 例外階層

PR:#4082

平面 ServiceException 族已被單一 AgentFrameworkException 根底下的域範圍例外分支所取代。 這讓來電者能精確地瞄準except目標並清晰地了解錯誤語義。

新階級制度:

AgentFrameworkException
├── AgentException
│   ├── AgentInvalidAuthException
│   ├── AgentInvalidRequestException
│   ├── AgentInvalidResponseException
│   └── AgentContentFilterException
├── ChatClientException
│   ├── ChatClientInvalidAuthException
│   ├── ChatClientInvalidRequestException
│   ├── ChatClientInvalidResponseException
│   └── ChatClientContentFilterException
├── IntegrationException
│   ├── IntegrationInitializationError
│   ├── IntegrationInvalidAuthException
│   ├── IntegrationInvalidRequestException
│   ├── IntegrationInvalidResponseException
│   └── IntegrationContentFilterException
├── ContentError
├── WorkflowException
│   ├── WorkflowRunnerException
│   ├── WorkflowValidationError
│   └── WorkflowActionError
├── ToolExecutionException
├── MiddlewareTermination
└── SettingNotFoundError

移除例外:ServiceException,ServiceInitializationError,ServiceResponseException,ServiceContentFilterException,ServiceInvalidAuthError,ServiceInvalidExecutionSettingsError,ServiceInvalidRequestError,ServiceInvalidResponseError,AgentExecutionException,AgentInvocationError,AgentInitializationError,AgentSessionException,ChatClientInitializationError,CheckpointDecodingError

Before:

from agent_framework.exceptions import ServiceException, ServiceResponseException

try:
    result = await agent.run("Hello")
except ServiceResponseException:
    ...
except ServiceException:
    ...

After:

from agent_framework.exceptions import AgentException, AgentInvalidResponseException, AgentFrameworkException

try:
    result = await agent.run("Hello")
except AgentInvalidResponseException:
    ...
except AgentException:
    ...
except AgentFrameworkException:
    # catch-all for any Agent Framework error
    ...

備註

Init 驗證錯誤現在使用內建例外 ValueError/TypeError,取代自訂例外。 Agent Framework 例外狀況僅保留給網域層級的失敗。


🔴 由 source_id 決定的提供者狀態範圍

PR:#3995

提供者勾點現在會獲得提供者範圍的狀態字典 (state.setdefault(provider.source_id, {})),而非完整的工作階段狀態。 這表示過去透過巢狀狀態 state[self.source_id]["key"] 存取的提供者實作,現在必須直接存取 state["key"] 。

此外,預設InMemoryHistoryProvider值source_id也從 "memory" 變成 "in_memory"。

Before:

# In a custom provider hook:
async def on_before_agent(self, state: dict, **kwargs):
    my_data = state[self.source_id]["my_key"]

# InMemoryHistoryProvider default source_id
provider = InMemoryHistoryProvider("memory")

After:

# Provider hooks receive scoped state — no nested access needed:
async def on_before_agent(self, state: dict, **kwargs):
    my_data = state["my_key"]

# InMemoryHistoryProvider default source_id changed
provider = InMemoryHistoryProvider("in_memory")

🔴 聊天/客服訊息輸入對齊(run 與 get_response)

PR:#3920

聊天客戶端 get_response 實作現在持續接收 Sequence[Message]。 agent.run(...)保持彈性(strContent、 、 Message或這些序列),並在呼叫聊天客戶端前正規化輸入。

Before:

async def get_response(self, messages: str | Message | list[Message], **kwargs): ...

After:

from collections.abc import Sequence
from agent_framework import Message

async def get_response(self, messages: Sequence[Message], **kwargs): ...

🔴 FunctionTool[Any] 移除架構直通的通用設定

PR:#3907

基於結構的工具路徑不再依賴先前 FunctionTool[Any] 的通用行為。 直接使用 FunctionTool,並在需要時提供 pydantic BaseModel 或明確的結構定義(例如,使用 @tool(schema=...))。

Before:

placeholder: FunctionTool[Any] = FunctionTool(...)

After:

placeholder: FunctionTool = FunctionTool(...)

🔴 Pydantic 設定被替換為 TypedDict + load_settings()

PRs:#3843、 #4032、 #8709

pydantic-settings 基於 AFBaseSettings 的類別已被使用 TypedDict 和 load_settings() 的輕量級、基於函數的設定系統取代。 pydantic-settings依賴性完全被移除了。

所有設定類別(例如、 OpenAISettings、 AzureOpenAISettings、 AnthropicSettings)現在 TypedDict 都是定義,設定值則透過字典語法而非屬性存取。

Before:

from agent_framework.openai import OpenAISettings

settings = OpenAISettings()  # pydantic-settings auto-loads from env
api_key = settings.api_key
model_id = settings.model_id

After:

from agent_framework import load_settings
from agent_framework.openai import OpenAISettings

settings = load_settings(OpenAISettings, env_prefix="OPENAI_")
api_key = settings["api_key"]
model = settings["model"]

這很重要

Agent Framework 不會 自動從檔案載入數值 .env 。 您必須明確地選擇以下方法之一來載入 .env:

  • 在應用程式啟動時,從 python-dotenv 套件中呼叫 load_dotenv()
  • 轉交 env_file_path=".env" 給 load_settings()
  • 直接在你的 shell 或 IDE 中設定環境變數

load_settings 解析順序為:明確覆寫 → .env 檔案值 (提供 env_file_path 時) → 環境變數 → 預設值。 如果你指定 env_file_path,檔案必須存在,否則 FileNotFoundError 會被觸發。

來自環境變數或 .env 檔案的無效數值或布林值會引發 ValueError,指出該設定及其來源。 它們不再默默地退回到不相容的數值。


🟡 修正推理模型工作流程交接與歷史序列化

PR:#4083

修正使用推理模型(例如 gpt-5-mini、gpt-5.2)於多代理工作流程時出現的多次故障。 來自回應 API 的推理項目現在會被正確序列化,只有在 a function_call 同時存在時才會被納入歷史記錄,從而避免 API 錯誤。 加密/隱藏的推斷內容現在會正確發出,summary 欄位的格式也已修正。 service_session_id 在交接時也會被清除,以防止跨代理狀態洩漏。


🟡 Bedrock 已新增至 core[all],並修正了 tool-choice 的預設值

PR:#3953

Amazon Bedrock 現已包含在 agent-framework-core[all] 額外內容中,並可透過 agent_framework.amazon 延遲匯入介面使用。 工具選擇行為也被修正:未設定的工具選擇值保持不變,提供者使用其服務預設值,而明確設定的值則被保留。

from agent_framework.amazon import BedrockChatClient

🟡 AzureAIClient 在遇到不支援的執行階段覆寫時會發出警告

PR:#3919

在此變更的時候,當執行時間的AzureAIClient或tools與代理程式建立時的設定不一致時,structured_output會記錄警告。 那個 Python 表面後來已經被移除了。 對於目前的 Python 程式碼,當你需要應用程式自有的工具/執行時設定時,請使用FoundryChatClient,或在直接回應 API 場景中需要動態覆寫時,使用OpenAIChatClient。


🟡 workflow.as_agent() 現在當提供者未設定時,這裡會預設本地歷史

PR:#3918

當建立 workflow.as_agent() 時若未包含 context_providers,現在預設會新增 InMemoryHistoryProvider("memory")。 若明確提供上下文提供者,該清單將保持不變。

workflow_agent = workflow.as_agent(name="MyWorkflowAgent")
# Default local history provider is injected when none are provided.

🟡 OpenTelemetry 追蹤內容已傳播至 MCP 要求

PR:#3780

當安裝 OpenTelemetry 時,追蹤上下文(例如 W3C traceparent)會自動注入到 MCP 請求中,透過params._meta。 這使得跨代理→MCP伺服器呼叫實現端對端分散式追蹤。 不需要程式碼變更——這是當存在有效區間上下文時會啟動的加法行為。


支援 Azure Functions 的 🟡 Durable 工作流程

PR:#3630

該 agent-framework-azurefunctions 套件現在支援在 Azure Durable Functions 上執行 Workflow 圖形。 將 workflow 參數傳遞到 AgentFunctionApp,以自動註冊代理實體、活動函數和 HTTP 端點。

from agent_framework.azure import AgentFunctionApp

app = AgentFunctionApp(workflow=my_workflow)
# Automatically registers:
#   POST /api/workflow/run          — start a workflow
#   GET  /api/workflow/status/{id}  — check status
#   POST /api/workflow/respond/{id}/{requestId} — HITL response

支援展開傳送/收合傳送、共用狀態,以及人機互動模式,並可設定逾時和在到期時自動拒絕的功能。


python-1.0.0b260212(2026年2月12日)

發行說明:python-1.0.0b260212

🔴 Hosted*Tool 類別被用戶端 get_*_tool() 方法取代

PR:#3634

託管工具類別被移除,改為使用屬於用戶端範圍的工廠方法。 這使得工具的可用性由供應商明確呈現。

已移除的類別 替換
HostedCodeInterpreterTool client.get_code_interpreter_tool()
HostedWebSearchTool client.get_web_search_tool()
HostedFileSearchTool client.get_file_search_tool(...)
HostedMCPTool client.get_mcp_tool(...)
HostedImageGenerationTool client.get_image_generation_tool(...)

Before:

from agent_framework import HostedCodeInterpreterTool, HostedWebSearchTool

tools = [HostedCodeInterpreterTool(), HostedWebSearchTool()]

After:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient()
tools = [client.get_code_interpreter_tool(), client.get_web_search_tool()]

🔴 會話/上下文提供者管道已完成AgentSession(context_providers)

PR:#3850

Python 會話及上下文提供者遷移已完成。 AgentThread 舊有的上下文提供者類型也被移除。

  • AgentThread → AgentSession
  • agent.get_new_thread() → agent.create_session()
  • agent.get_new_thread(service_thread_id=...) → agent.get_session(service_session_id=...)
  • context_provider= / chat_message_store_factory= 模式被替換為 context_providers=[...]
  • ChatMessageStore 被移除。 使用 HistoryProvider(或在預設的記憶體內情境中使用 InMemoryHistoryProvider),兩者皆由 agent_framework 匯出。 若未傳遞上下文提供者,代理會自動注入 InMemoryHistoryProvider。

Before:

thread = agent.get_new_thread()
response = await agent.run("Hello", thread=thread)

After:

session = agent.create_session()
response = await agent.run("Hello", session=session)

🔴 檢查點模型與儲存行為重構

PR:#3744

檢查點內部結構已重新設計,這影響了持久化檢查點的相容性及自訂儲存機制:

  • WorkflowCheckpoint 現在儲存活物件(序列化發生在檢查點儲存中)
  • FileCheckpointStorage 現在使用 pickle 序列化技術
  • workflow_id 被移除後 previous_checkpoint_id 又被加入
  • 已廢棄的檢查點掛鉤被移除

如果你在不同版本間保存檢查點,請在恢復工作流程前重新生成或遷移現有的檢查點檔案。


🟡 Foundry 專案端點最初出現於 AzureOpenAIResponsesClient

PR:#3814

此預覽功能最初允許 AzureOpenAIResponsesClient 連接 Foundry 專案端點。 目前 Python 指引使用 FoundryChatClient 進行 Foundry 專案推論或將 FoundryAgent 用於服務受控 Foundry 代理程式,而不是已移除的 AzureOpenAIResponsesClient。

from azure.identity import DefaultAzureCredential
from agent_framework.foundry import FoundryChatClient

client = FoundryChatClient(
    project_endpoint="https://<your-account>.services.ai.azure.com/api/projects/<your-project>",
    model="gpt-4o-mini",
    credential=DefaultAzureCredential(),
)

🔴 中介軟體 call_next 不再接受 context

PR:#3829

中介軟體接續現在不接受任何引數。 如果你的中介軟體還在呼叫 call_next(context),請更新成 call_next()。

Before:

async def telemetry_middleware(context, call_next):
    # ...
    return await call_next(context)

After:

async def telemetry_middleware(context, call_next):
    # ...
    return await call_next()

python-1.0.0b260210(2026年2月10日)

發佈說明:python-1.0.0b260210

🔴 工作流程工廠方法已從 WorkflowBuilder 移除

PR:#3781

register_executor()和register_agent()已從WorkflowBuilder中移除。 所有建構方法(add_edge、add_fan_out_edges、add_fan_in_edgesadd_chainadd_switch_case_edge_groupadd_multi_selection_edge_group)且start_executor不再接受字串名稱——它們需要執行者或代理實例直接使用。

為了狀態隔離,將執行者/代理實例化和工作流程建置包裝在輔助方法中,讓每次呼叫都能產生新的實例。

WorkflowBuilder 與執行程式

Before:

workflow = (
    WorkflowBuilder(start_executor="UpperCase")
    .register_executor(lambda: UpperCaseExecutor(id="upper"), name="UpperCase")
    .register_executor(lambda: ReverseExecutor(id="reverse"), name="Reverse")
    .add_edge("UpperCase", "Reverse")
    .build()
)

After:

upper = UpperCaseExecutor(id="upper")
reverse = ReverseExecutor(id="reverse")

workflow = WorkflowBuilder(start_executor=upper).add_edge(upper, reverse).build()

WorkflowBuilder 與經紀人合作

Before:

builder = WorkflowBuilder(start_executor="writer_agent")
builder.register_agent(factory_func=create_writer_agent, name="writer_agent")
builder.register_agent(factory_func=create_reviewer_agent, name="reviewer_agent")
builder.add_edge("writer_agent", "reviewer_agent")

workflow = builder.build()

After:

writer_agent = create_writer_agent()
reviewer_agent = create_reviewer_agent()

workflow = WorkflowBuilder(start_executor=writer_agent).add_edge(writer_agent, reviewer_agent).build()

使用輔助方法進行狀態隔離

對於每次叫用需要隔離狀態的工作流程,請用協助程式方法包裝建構:

def create_workflow() -> Workflow:
    """Each call produces fresh executor instances with independent state."""
    upper = UpperCaseExecutor(id="upper")
    reverse = ReverseExecutor(id="reverse")

    return WorkflowBuilder(start_executor=upper).add_edge(upper, reverse).build()

workflow_a = create_workflow()
workflow_b = create_workflow()

🔴 ChatAgent 重新命名為 Agent, ChatMessage 再命名為 Message

PR:#3747

核心 Python 類型透過移除冗餘 Chat 前綴而簡化。 不提供向下相容的別名。

之前 之後
ChatAgent Agent
RawChatAgent RawAgent
ChatMessage Message
ChatClientProtocol SupportsChatGetResponse

更新匯入

Before:

from agent_framework import ChatAgent, ChatMessage

After:

from agent_framework import Agent, Message

更新類型參照

Before:

agent = ChatAgent(
    chat_client=client,
    name="assistant",
    instructions="You are a helpful assistant.",
)

message = ChatMessage(role="user", contents=[Content.from_text("Hello")])

After:

agent = Agent(
    client=client,
    name="assistant",
    instructions="You are a helpful assistant.",
)

message = Message(role="user", contents=[Content.from_text("Hello")])

備註

ChatClient、ChatResponse 和 ChatOptions不會因這項變更而重新命名。


涵蓋回應與訊息模型的 🔴 Types API 審查更新

PR:#3647

此發行版本包含對訊息/回應類型與協助程式 API 的全面且具破壞性的清理。

  • Role 和 FinishReason 現在是基於 NewType 的 str 封裝器,並使用 RoleLiteral/FinishReasonLiteral 來處理已知值。 把它們當成弦來看待(不用 .value 用)。
  • Message 建構已標準化為使用 Message(role, contents=[...]);contents 中的字串會自動轉換為文字內容。
  • ChatResponse與 AgentResponse 建構函式現在以 messages= (單一 Message 或序列) 為中心;已從回應中移除舊版的 text= 建構函式用法。
  • ChatResponseUpdate 和 AgentResponseUpdate 不再接受 text=;請使用 contents=[Content.from_text(...)]。
  • 更新合併協助工具名稱已簡化。
  • try_parse_value從ChatResponse和AgentResponse中移除。

輔助方法的重新命名

之前 之後
ChatResponse.from_chat_response_updates(...) ChatResponse.from_updates(...)
ChatResponse.from_chat_response_generator(...) ChatResponse.from_update_generator(...)
AgentResponse.from_agent_run_response_updates(...) AgentResponse.from_updates(...)

更新回應-更新構建方法

Before:

update = AgentResponseUpdate(text="Processing...", role="assistant")

After:

from agent_framework import AgentResponseUpdate, Content

update = AgentResponseUpdate(
    contents=[Content.from_text("Processing...")],
    role="assistant",
)

將 try_parse_value 替換為 try/except 於 .value

Before:

if parsed := response.try_parse_value(MySchema):
    print(parsed.name)

After:

from pydantic import ValidationError

try:
    parsed = response.value
    if parsed:
        print(parsed.name)
except ValidationError as err:
    print(f"Validation failed: {err}")

🔴統一run/get_response模型與應用ResponseStream

PR:#3379

Python API 被整合為 agent.run(...) 和 client.get_response(...),串流則以 ResponseStream表示。

Before:

async for update in agent.run_stream("Hello"):
    print(update)

After:

stream = agent.run("Hello", stream=True)
async for update in stream:
    print(update)

🔴 核心上下文/協定類型重新命名

PRs:#3714, #3717

之前 之後
AgentRunContext AgentContext
AgentProtocol SupportsAgentRun

更新對應的匯入與類型註釋。


🔴 中介軟體延續參數已重新命名為 call_next

PR:#3735

中介軟體簽名現在應該用 call_next 來替換 next。

Before:

async def my_middleware(context, next):
    return await next(context)

After:

async def my_middleware(context, call_next):
    return await call_next(context)

🔴 TypeVar 名稱標準化(TName → NameT)

PR:#3770

程式碼庫現採用一致的 TypeVar 命名風格,並使用後綴 T 。

Before:

TMessage = TypeVar("TMessage")

After:

MessageT = TypeVar("MessageT")

如果你在框架泛型周圍維持自訂包裝,請將本地 TypeVar 名稱與新慣例對齊,以減少註解流失。


🔴 工作流程即代理程式的輸出與串流變更

PR:#3649

workflow.as_agent() 行為更新以使輸出與串流與標準代理反應模式對齊。 檢閱相依於舊版輸出/更新處理的工作流程即代理程式取用端,並將其更新至目前的 AgentResponse/AgentResponseUpdate 流程。


🔴 Fluent 建置器方法已移至建構函式參數

PR:#3693

跨 6 個建構器(WorkflowBuilder、SequentialBuilderConcurrentBuilderGroupChatBuilderMagenticBuilderHandoffBuilder)的單一配置流暢方法已遷移至建構參數。 原本是設定唯一配置路徑的流暢方法被移除,取而代之的是建構子參數。

WorkflowBuilder

set_start_executor() with_checkpointing() with_output_from(), 被移除。 改用建構參數。

Before:

upper = UpperCaseExecutor(id="upper")
reverse = ReverseExecutor(id="reverse")

workflow = (
    WorkflowBuilder(start_executor=upper)
    .add_edge(upper, reverse)
    .set_start_executor(upper)
    .with_checkpointing(storage)
    .build()
)

After:

upper = UpperCaseExecutor(id="upper")
reverse = ReverseExecutor(id="reverse")

workflow = (
    WorkflowBuilder(start_executor=upper, checkpoint_storage=storage)
    .add_edge(upper, reverse)
    .build()
)

SequentialBuilder / ConcurrentBuilder

participants()、 register_participants()with_checkpointing()with_intermediate_outputs() 都被移除。 改用建構參數。

Before:

workflow = SequentialBuilder().participants([agent_a, agent_b]).with_checkpointing(storage).build()

After:

workflow = SequentialBuilder(participants=[agent_a, agent_b], checkpoint_storage=storage).build()

GroupChatBuilder

participants()、、register_participants()、with_orchestrator()with_termination_condition()with_max_rounds()with_checkpointing()with_intermediate_outputs()都被移除。 改用建構參數。

Before:

workflow = (
    GroupChatBuilder()
    .with_orchestrator(selection_func=selector)
    .participants([agent1, agent2])
    .with_termination_condition(lambda conv: len(conv) >= 4)
    .with_max_rounds(10)
    .build()
)

After:

workflow = GroupChatBuilder(
    participants=[agent1, agent2],
    selection_func=selector,
    termination_condition=lambda conv: len(conv) >= 4,
    max_rounds=10,
).build()

MagenticBuilder

participants()、、register_participants()、 with_manager()with_plan_review()with_checkpointing()with_intermediate_outputs() 都被移除。 改用建構參數。

Before:

workflow = (
    MagenticBuilder()
    .participants([researcher, coder])
    .with_manager(agent=manager_agent)
    .with_plan_review()
    .build()
)

After:

workflow = MagenticBuilder(
    participants=[researcher, coder],
    manager_agent=manager_agent,
    enable_plan_review=True,
).build()

HandoffBuilder

with_checkpointing() 並 with_termination_condition() 被移除。 改用建構參數。

Before:

workflow = (
    HandoffBuilder(participants=[triage, specialist])
    .with_start_agent(triage)
    .with_termination_condition(lambda conv: len(conv) > 5)
    .with_checkpointing(storage)
    .build()
)

After:

workflow = (
    HandoffBuilder(
        participants=[triage, specialist],
        termination_condition=lambda conv: len(conv) > 5,
        checkpoint_storage=storage,
    )
    .with_start_agent(triage)
    .build()
)

驗證變更

  • WorkflowBuilder 現在 需要 start_executor 作為建構子參數(先前透過流流方法設定)
  • SequentialBuilder、ConcurrentBuilder、GroupChatBuilder 和 MagenticBuilder 現在在建構時必須提供 participants 或 participant_factories 其中之一 — 兩者皆未傳遞會引發 ValueError

備註

HandoffBuilder 當時已被接受 participants/participant_factories 為建造者參數,且在此方面未作更改。


🔴 工作流程事件統一為單一的 WorkflowEvent,並搭配 type 判別器

PR:#3690

所有個別的工作流程事件子類別都被一個通用 WorkflowEvent[DataT] 類別取代。 你不再用 isinstance() 檢查來識別事件類型,而是檢查 event.type 字串的文字(例如, "output", "request_info", "status")。 這遵循與來自 python-1.0.0b260123 的 Content 類別合併相同的模式。

移除的賽事級別

以下匯出的事件子類別已不復存在:

舊類別 新 event.type 價值
WorkflowOutputEvent "output"
RequestInfoEvent "request_info"
WorkflowStatusEvent "status"
WorkflowStartedEvent "started"
WorkflowFailedEvent "failed"
ExecutorInvokedEvent "executor_invoked"
ExecutorCompletedEvent "executor_completed"
ExecutorFailedEvent "executor_failed"
SuperStepStartedEvent "superstep_started"
SuperStepCompletedEvent "superstep_completed"

更新匯入

Before:

from agent_framework import (
    WorkflowOutputEvent,
    RequestInfoEvent,
    WorkflowStatusEvent,
    ExecutorCompletedEvent,
)

After:

from agent_framework import WorkflowEvent
# Individual event classes no longer exist; use event.type to discriminate

更新事件類型檢查

Before:

async for event in workflow.run(input_message, stream=True):
    if isinstance(event, WorkflowOutputEvent):
        print(f"Output from {event.executor_id}: {event.data}")
    elif isinstance(event, RequestInfoEvent):
        requests[event.request_id] = event.data
    elif isinstance(event, WorkflowStatusEvent):
        print(f"Status: {event.state}")

After:

async for event in workflow.run(input_message, stream=True):
    if event.type == "output":
        print(f"Output from {event.executor_id}: {event.data}")
    elif event.type == "request_info":
        requests[event.request_id] = event.data
    elif event.type == "status":
        print(f"Status: {event.state}")

使用 AgentResponseUpdate 串流

Before:

from agent_framework import AgentResponseUpdate, WorkflowOutputEvent

async for event in workflow.run_stream("Write a blog post about AI agents."):
    if isinstance(event, WorkflowOutputEvent) and isinstance(event.data, AgentResponseUpdate):
        print(event.data, end="", flush=True)
    elif isinstance(event, WorkflowOutputEvent):
        print(f"Final output: {event.data}")

After:

from agent_framework import AgentResponseUpdate

async for event in workflow.run("Write a blog post about AI agents.", stream=True):
    if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
        print(event.data, end="", flush=True)
    elif event.type == "output":
        print(f"Final output: {event.data}")

型別註解

Before:

pending_requests: list[RequestInfoEvent] = []
output: WorkflowOutputEvent | None = None

After:

from typing import Any
from agent_framework import WorkflowEvent

pending_requests: list[WorkflowEvent[Any]] = []
output: WorkflowEvent | None = None

備註

WorkflowEvent 是泛型(WorkflowEvent[DataT]),但用於混合事件集合,使用 WorkflowEvent[Any] 或未參數化 WorkflowEvent的。


🔴 workflow.send_responses* 移除;使用 workflow.run(responses=...)

PR:#3720

send_responses() 和 send_responses_streaming() 被從 Workflow 中移除。 透過直接將回應傳遞給 run(),繼續暫停的工作流程。

Before:

async for event in workflow.send_responses_streaming(
    checkpoint_id=checkpoint_id,
    responses=[approved_response],
):
    ...

After:

async for event in workflow.run(
    checkpoint_id=checkpoint_id,
    responses=[approved_response],
    stream=True,
):
    ...

🔴 SharedState 重新命名為 State;工作流程狀態 API 是同步的

PR:#3667

州級 API 不再要求 await,命名也已標準化:

之前 之後
ctx.shared_state ctx.state
await ctx.get_shared_state("k") ctx.get_state("k")
await ctx.set_shared_state("k", v) ctx.set_state("k", v)
checkpoint.shared_state checkpoint.state

🔴 協作編排工具已移至 agent_framework.orchestrations

PR:#3685

編排建構器現在存在專用的套件命名空間。

Before:

from agent_framework import SequentialBuilder, GroupChatBuilder

After:

from agent_framework.orchestrations import SequentialBuilder, GroupChatBuilder

🟡 長時間執行的背景回應與接續權杖

PR:#3808

Python 代理程式執行現在透過 options={"background": True} 與 continuation_token 支援背景回應。

response = await agent.run("Long task", options={"background": True})
while response.continuation_token is not None:
    response = await agent.run(options={"continuation_token": response.continuation_token})

🟡 會話/上下文提供者預覽類型並排新增

PR:#3763

新增的會話/上下文管線類型與舊有 API 一同引入,用於增量遷移,包括 SessionContext 和 BaseContextProvider。


🟡 程式碼解譯器串流現在包含遞增程式碼差異

PR:#3775

串流程式碼解譯器現在會在串流內容中執行介面程式碼差異更新,讓 UI 可以逐步轉譯產生的程式碼。


🟡 @tool 支援明確的結構處理

PR:#3734

工具定義現在可以在推斷出的結構輸出需要客製化時,使用明確的結構處理。


python-1.0.0b260130(2026年1月30日)

發布說明:python-1.0.0b260130

🟡 ChatOptions 和 ChatResponse/AgentResponse 現在都可用於一般的回應格式

PR:#3305

ChatOptions、、ChatResponseAgentResponse以及現在都是以回應格式類型為參數化的通用型別。 這使得在使用結構化輸出和 response_format 時,能更精確地進行型別推斷。

Before:

from agent_framework import ChatOptions, ChatResponse
from pydantic import BaseModel

class MyOutput(BaseModel):
    name: str
    score: int

options: ChatOptions = {"response_format": MyOutput}  # No type inference
response: ChatResponse = await client.get_response("Query", options=options)
result = response.value  # Type: Any

After:

from agent_framework import ChatOptions, ChatResponse
from pydantic import BaseModel

class MyOutput(BaseModel):
    name: str
    score: int

options: ChatOptions[MyOutput] = {"response_format": MyOutput}  # Generic parameter
response: ChatResponse[MyOutput] = await client.get_response("Query", options=options)
result = response.value  # Type: MyOutput | None (inferred!)

Tip

這是非破壞性的強化。 沒有型別參數的現有程式碼仍然能正常運作。 你不需要在上述程式碼摘要中指定選項和回應的類型;這裡展示這些資料以求清晰。


🟡 BaseAgent 新增對 Claude Agent SDK 的支援

PR:#3509

Python SDK 現已包含 Claude Agent SDK 的 BaseAgent 實作,可在 Agent Framework 中啟用第一級的介面卡型使用方式。


python-1.0.0b260128(2026年1月28日)

發行說明:python-1.0.0b260128

🔴 AIFunction更名為 FunctionTool 及@ai_function@tool

PR:#3413

為求清晰與符合業界術語的一致性,該類別與裝飾項目已重新命名。

Before:

from agent_framework.core import ai_function, AIFunction

@ai_function
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"Weather in {city}: Sunny"

# Or using the class directly
func = AIFunction(get_weather)

After:

from agent_framework import FunctionTool, tool

@tool
def get_weather(city: str) -> str:
    """Get the weather for a city."""
    return f"Weather in {city}: Sunny"

# Or using the class directly
func = FunctionTool(get_weather)

🔴 已將工廠模式新增至群組聊天與 Magentic;API 重新命名

PR:#3224

已將參與者工廠與協調者工廠新增至群組聊天。 同時包含重新命名:

  • with_standard_manager → with_manager
  • participant_factories → register_participant

Before:

from agent_framework.workflows import MagenticBuilder

builder = MagenticBuilder()
builder.with_standard_manager(manager)
builder.participant_factories(factory1, factory2)

After:

from agent_framework.orchestrations import MagenticBuilder

builder = MagenticBuilder()
builder.with_manager(manager)
builder.register_participant(factory1)
builder.register_participant(factory2)

🔴 Github 更名為 GitHub

PR:#3486

類別名稱和套件名稱已更新為使用正確的大小寫。

Before:

from agent_framework_github_copilot import GithubCopilotAgent

agent = GithubCopilotAgent(...)

After:

from agent_framework_github_copilot import GitHubCopilotAgent

agent = GitHubCopilotAgent(...)

python-1.0.0b260127(2026年1月27日)

發行說明:python-1.0.0b260127

🟡 BaseAgent 新增對 GitHub Copilot SDK 的支援

PR:#3404

Python SDK 現在包含 GitHub Copilot SDK 整合的 BaseAgent 實作。


python-1.0.0b260123(2026年1月23日)

發布說明:python-1.0.0b260123

🔴 內容類型簡化為單一類別,並且使用 classmethod 作為建構方式

PR:#3252

將所有舊有的內容型別(源自 BaseContent)替換為一個帶有 classmethods 的單一 Content 類別,以建立特定型別。

完整遷移參考

舊型 新的方法
TextContent(text=...) Content.from_text(text=...)
DataContent(data=..., media_type=...) Content.from_data(data=..., media_type=...)
UriContent(uri=..., media_type=...) Content.from_uri(uri=..., media_type=...)
ErrorContent(message=...) Content.from_error(message=...)
HostedFileContent(file_id=...) Content.from_hosted_file(file_id=...)
FunctionCallContent(name=..., arguments=..., call_id=...) Content.from_function_call(name=..., arguments=..., call_id=...)
FunctionResultContent(call_id=..., result=...) Content.from_function_result(call_id=..., result=...)
FunctionApprovalRequestContent(...) Content.from_function_approval_request(...)
FunctionApprovalResponseContent(...) Content.from_function_approval_response(...)

其他新方法(無直接前身):

  • Content.from_text_reasoning(...) — 用於推理/思維內容
  • Content.from_hosted_vector_store(...) — 向量存放區參考
  • Content.from_usage(...) — 用於使用/標記資訊
  • Content.from_mcp_server_tool_call(...) / Content.from_mcp_server_tool_result(...) — 針對 MCP 伺服器工具
  • Content.from_code_interpreter_tool_call(...) / Content.from_code_interpreter_tool_result(...) — 用於程式碼直譯器
  • Content.from_image_generation_tool_call(...) / Content.from_image_generation_tool_result(...) — 用於影像生成

型別檢查

不要使用 isinstance() 檢查,而是使用 type 屬性:

Before:

from agent_framework.core import TextContent, FunctionCallContent

if isinstance(content, TextContent):
    print(content.text)
elif isinstance(content, FunctionCallContent):
    print(content.name)

After:

from agent_framework import Content

if content.type == "text":
    print(content.text)
elif content.type == "function_call":
    print(content.name)

基本範例

Before:

from agent_framework.core import TextContent, DataContent, UriContent

text = TextContent(text="Hello world")
data = DataContent(data=b"binary", media_type="application/octet-stream")
uri = UriContent(uri="https://example.com/image.png", media_type="image/png")

After:

from agent_framework import Content

text = Content.from_text("Hello world")
data = Content.from_data(data=b"binary", media_type="application/octet-stream")
uri = Content.from_uri(uri="https://example.com/image.png", media_type="image/png")

🔴 註解類型簡化為 Annotation 和 TextSpanRegion TypedDicts

PR:#3252

以更 TypedDict 簡單的定義取代基於類別的註解類型。

舊型 新型
CitationAnnotation (類別) Annotation (具有 type="citation" 的 TypedDict)
BaseAnnotation (類別) Annotation (TypedDict)
TextSpanRegion (類別為 SerializationMixin) TextSpanRegion (TypedDict)
Annotations (類型別名) Annotation
AnnotatedRegions (類型別名) TextSpanRegion

Before:

from agent_framework import CitationAnnotation, TextSpanRegion

region = TextSpanRegion(start_index=0, end_index=25)
citation = CitationAnnotation(
    annotated_regions=[region],
    url="https://example.com/source",
    title="Source Title"
)

After:

from agent_framework import Annotation, TextSpanRegion

region: TextSpanRegion = {"start_index": 0, "end_index": 25}
citation: Annotation = {
    "type": "citation",
    "annotated_regions": [region],
    "url": "https://example.com/source",
    "title": "Source Title"
}

備註

由於 Annotation 與 TextSpanRegion 現在是 TypedDict,因此您必須將其建立為字典,而不是類別執行個體。


🔴 response_format 驗證錯誤現在對使用者可見

PR:#3274

ChatResponse.value 和 AgentResponse.value 現在在結構驗證失敗時觸發 ValidationError,而非靜默返回 None。

Before:

response = await agent.run(query, options={"response_format": MySchema})
if response.value:  # Returns None on validation failure - no error details
    print(response.value.name)

After:

from pydantic import ValidationError

# Option 1: Catch validation errors
try:
    print(response.value.name)  # Raises ValidationError on failure
except ValidationError as e:
    print(f"Validation failed: {e}")

# Option 2: Safe parsing (returns None on failure)
if result := response.try_parse_value(MySchema):
    print(result.name)

🔴 AG-UI 運行邏輯簡化;MCP 與 Anthropic 用戶端修正

PR:#3322

runAG-UI 中的方法簽名與行為已被簡化。

Before:

from agent_framework.ag_ui import AGUIEndpoint

endpoint = AGUIEndpoint(agent=agent)
result = await endpoint.run(
    request=request,
    run_config={"streaming": True, "timeout": 30}
)

After:

from agent_framework.ag_ui import AgentFrameworkAgent

agui_agent = AgentFrameworkAgent(agent=agent)
async for event in agui_agent.run(request):
    ...

🟡 Anthropic 用戶端現在支援 response_format 結構化輸出

PR:#3301

你現在可以透過 Anthropic 客戶端 response_format使用結構化輸出解析,類似 OpenAI 和 Azure 客戶端。


🟡 Azure AI 配置擴展 (reasoning, rai_config)

PRs:#3403, #3265

在代理程式創建過程中,Azure AI 支援已隨著推理配置支援及 rai_config 而擴展。


python-1.0.0b260116(2026年1月16日)

發布說明:python-1.0.0b260116

🔴 create_agent 更名為 as_agent

PR:#3249

方法名稱已更改,以更清楚說明其用途。

Before:

from agent_framework.core import ChatClient

client = ChatClient(...)
agent = client.create_agent()

After:

from agent_framework.openai import OpenAIChatClient

client = OpenAIChatClient(...)
agent = client.as_agent()

🔴 WorkflowOutputEvent.source_executor_id 更名為 executor_id

PR:#3166

為了 API 一致性,屬性重新命名。

Before:

async for event in workflow.run_stream(...):
    if isinstance(event, WorkflowOutputEvent):
        executor = event.source_executor_id

After:

async for event in workflow.run(..., stream=True):
    if event.type == "output":
        executor = event.executor_id

🟡 AG-UI 支援由服務管理的會話持續性

PR:#3136

AG-UI 現在會保留服務受控交談身分識別 (例如 Foundry 受控工作階段/執行緒),以維持多回合對話的連貫性。


python-1.0.0b260114(2026年1月14日)

發布說明:python-1.0.0b260114

🔴 協調流程已重構

PR:#3023

代理框架工作流程中對編排進行大規模重構與簡化:

  • 群組聊天:將編排器執行器拆分為專用代理型與功能型(BaseGroupChatOrchestrator, GroupChatOrchestrator, AgentBasedGroupChatOrchestrator)。 簡化為採用廣播模型的星狀拓撲。
  • Handoff:移除單層、協調器及自訂執行者支援。 轉為使用 HandoffAgentExecutor 的廣播模式。
  • 循序 & 並行:透過 AgentApprovalExecutor 與 AgentRequestInfoExecutor 簡化要求資訊機制,改為依賴子工作流程。

Before:

from agent_framework.workflows import GroupChat, HandoffOrchestrator

# Group chat with custom coordinator
group = GroupChat(
    participants=[agent1, agent2],
    coordinator=my_coordinator
)

# Handoff with single tier
handoff = HandoffOrchestrator(
    agents=[agent1, agent2],
    tier="single"
)

After:

from agent_framework.orchestrations import (
    GroupChatOrchestrator,
    HandoffAgentExecutor,
)

# Group chat with star topology
group = GroupChatOrchestrator(
    participants=[agent1, agent2]
)

# Handoff with executor-based approach
handoff = HandoffAgentExecutor(
    agents=[agent1, agent2]
)

🔴 以 TypedDict 與 Generic 形式引入的選項

PR:#3140

選項現在使用 TypedDict 進行類型定義,以提供更好的類型安全性和 IDE 自動完成功能。

📖 完整的遷移說明,請參閱 「類型化選項指南」。

Before:

response = await client.get_response(
    "Hello!",
    model_id="gpt-4",
    temperature=0.7,
    max_tokens=1000,
)

After:

response = await client.get_response(
    "Hello!",
    options={
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
    },
)

🔴 display_name 刪除; context_provider 更改為單數; middleware 必須為清單

PR:#3139

  • display_name 從代理人移除的參數
  • context_providers 仍是目前提供者的複數序列參數
  • middleware 現在需要一個清單(不再接受單一實例)
  • AggregateContextProvider 從程式碼中移除(如有需要,請使用範例實作)

Before:

from agent_framework.core import Agent, AggregateContextProvider

agent = Agent(
    name="my-agent",
    display_name="My Agent",
    context_providers=[provider1, provider2],
    middleware=my_middleware,  # single instance was allowed
)

aggregate = AggregateContextProvider([provider1, provider2])

After:

from agent_framework import Agent

agent = Agent(
    name="my-agent",  # display_name removed
    client=client,
    context_providers=[provider1, provider2],
    middleware=[my_middleware],  # must be a list now
)

# For reusable provider composition, create your own aggregate
class MyAggregateProvider:
    def __init__(self, providers):
        self.providers = providers
    # ... implement aggregation logic

🔴 AgentRunResponse* 更名為 AgentResponse*

PR:#3207

AgentRunResponse 並 AgentRunResponseUpdate 被重新命名為 AgentResponse 和 AgentResponseUpdate。

Before:

from agent_framework import AgentRunResponse, AgentRunResponseUpdate

After:

from agent_framework import AgentResponse, AgentResponseUpdate

🟡 新增宣告式工作流程執行環境,以支援 YAML 定義的工作流程

PR:#2815

新增了基於圖形的執行時,用於執行宣告式 YAML 工作流程,使多代理能在無需自訂執行時程式碼的情況下進行協調。


🟡 MCP 載入與可靠性改進

PR:#3154

MCP 整合改善了連接中斷行為、載入時的分頁支援,以及表示控制選項。


🟡 Foundry A2ATool 現在支援沒有目標 URL 的連線

PR:#3127

A2ATool 現在即使未設定直接目標 URL,也能透過專案連線元資料解析 Foundry 支援的 A2A 連線。


python-1.0.0b260107(2026年1月7日)

發布說明:python-1.0.0b260107

這次發行沒有重大變動。


python-1.0.0b260106(2026年1月6日)

發行說明:python-1.0.0b260106

這次發行沒有重大變動。


摘要表

Release 發行說明 類型 變更 PR
1.25.0 Notes 🔴 中斷 Python 3.11 是最低支援且可安裝的版本 #9948
1.25.0 Notes 🔴 中斷 MCP 發現、請求逾時、動態核准、並行性以及宣告式會話擁有權皆有限制 #10042、 #10136、 #10147、 #8662、 #10151
1.25.0 Notes 🔴 中斷 AG-UI 工作流程執行器與工作階段綁定於單一授權範圍 #10035
1.25.0 Notes 🔴 中斷 工作流程呼叫範圍使用 OpenTelemetry GenAI 操作與工作流程名稱 #9900
1.25.0 Notes 🔴 中斷 Foundry Local 使用 SDK 2.3.1 並準備已註冊模型 #9322
1.25.0 Notes 🔴 中斷 Monty 與 Hyperlight 預設會遮蔽主機工具診斷 #9971
1.25.0 Notes 🟡 強化 注入用戶端優先於環境連線設定 #9977、 #9983、 #9984、 #9985、 #9987、 #9991、 #9996、 #9967
1.25.0 Notes 🟡 強化 工具架構、FIDES、Copilot 中介軟體及 URL 核准邊界皆以封閉方式失敗 #10036、 #9875、 #10090、 #10149
1.25.0 Notes 🟡 強化 Redis 支援 Python 3.15 #10143
1.25.0 Notes 🟡 強化 Monty 資源限制使用目前的執行時鍵值 #10096
1.23.0 Notes 🔴 中斷 MCP 整合使用 MCP SDK 2.x 高階用戶端生命週期;WebSocket 與任務支援已被移除 #9236
1.23.0 Notes 🔴 中斷 AG-UI 端點需要授權範圍解析器或明確宣 single_user=True 告 #9413
1.23.0 Notes 🔴 中斷 DockerShellTool.extra_run_args 更名為 unsafe_extra_run_args #9453
1.23.0 Notes 🟡 強化 A2A 透過獨立的允許清單轉發並接受所選的執行上下文 #9192, #9193
1.23.0 Notes 🟡 強化 循序 Agent 可在結尾附加僅供本次叫用使用的使用者回合,以確保與提供者相容 #8779
1.23.0 Notes 🟡 強化 Python 3.15 支援擴展至 Hyperlight、A2UI 與 DuckDB —
1.23.0 Notes 🟡 強化 適用於相容程式碼撰寫代理程式的可安裝 agent-framework-builder-python 技能 #9374
1.22.0 Notes 🔴 中斷 內容執行所有權、元資料命名空間及串流合併語意被整合 #8886
1.22.0 Notes 🟡 強化 新增 Python 3.15 支援,Python 3.10 已棄用 #9363
1.21.0 Notes 🟡 強化 OpenAI 用戶端支援最高推理強度 #8857
1.21.0 Notes 🟡 強化 已新增 Oracle AI 資料庫向量儲存連接器,作為 alpha 套件 #8676
1.21.0 Notes 🟡 強化 當代理以工具形式運作時,提供者擁有的服務會話會保持隔離 #8853
1.20.0 Notes 🔴 中斷 Foundry Invocations 預設使用 JSON 與分幀式 SSE #8894
1.20.0 Notes 🔴 中斷 宣告式工作流程物件屬性需要安全的名稱 #8893
1.20.0 Notes 🔴 中斷 Foundry 回應裝載將歷程記錄、回應儲存和背景執行分開處理 #8794
1.20.0 Notes 🔴 中斷 Gemini 使用 GOOGLE_* 設定並新增 Embedding 2 #8798
1.20.0 Notes 🔴 中斷 Foundry 叫用工作階段改用持續性儲存體 #8593
1.20.0 Notes 🔴 中斷 本機工具核准需要簽發工作階段 #8750
1.20.0 Notes 🔴 中斷 持續保存的核准文字記錄使用具型別的核准控制項 #8579
1.20.0 Notes 🔴 中斷 MCP 執行階段內容與核准標頭分開處理 #8589
1.20.0 Notes 🔴 中斷 宣告式 Power Fx 狀態會拒絕循環並強制執行遍歷限制 #8511
1.20.0 Notes 🔴 中斷 工作流程 HTTP 請求需要絕對的 HTTP(S) URL #8588
1.19.0 Notes 🔴 中斷 MCP 技能檔案僅支援 ZIP,且取樣功能已棄用。 #8290, #8401
1.19.0 Notes 🔴 中斷 必須明確設定 HTTP Cookie 的持續保存 #8371
1.19.0 Notes 🔴 中斷 Redis 的歷史金鑰包括提供者與工作階段識別 #8236
1.19.0 Notes 🟡 強化 共用向量儲存 API 新增 MongoDB、Azure DocumentDB 和 Azure Cosmos DB 連接器 #8184、 #8185、 #8186
1.18.0 Notes 🔴 中斷 Lab 需另行安裝,且 Foundry 支援 Azure AI Projects 2.6 #8188
1.18.0 Notes 🔴 中斷 檔案型儲存體使用共用路徑標準化 #8123
1.18.0 Notes 🔴 中斷 SecretString 不再繼承 str #8127
1.18.0 Notes 🔴 中斷 GitHub Copilot 工作區檔案勾點需自行選擇啟用 #7517
1.17.0 Notes 🔴 中斷 中介軟體輸入必須為序列,且 Agent Hooks 需另行安裝 #7918
1.15.0 Notes 🟡 強化 MiddlewareFailure 為函式中介軟體新增致命且故障時關閉的行為 #7562
1.14.0 Notes 🟡 強化 Foundry Chat 的加密推理需由使用者選擇啟用 #7536
1.14.0 Notes 🟡 強化 Agent Hooks 新增實驗性的 AGENT-HOOKS-0.1 攔截中介軟體 #7515
1.8.0 Notes 🔴 中斷 github-copilot-sdk 升級至 v1.0.0: SubprocessConfig 移除(使用 RuntimeConnection + kwargs),匯入路徑移至 copilot.session_events、→ copilot_homebase_directory,權限處理程式使用 Concrete 決策類型 #6292
1.8.0 Notes 🟡 強化 透過 FunctionInvocationContext 公開漸進式工具 #6233
1.8.0 Notes 🟡 強化 以 MCP 為基礎的技能探索 (McpSkillsSource) #6169
1.8.0 Notes 🟡 強化 透過 Converse API 提供 Bedrock 原生結構化輸出支援 #6052
1.8.0 Notes 🟡 強化 Foundry 自適應評估整合(評分規準生成) #6101
1.8.0 Notes 🟡 強化 Mistral AI 嵌入客戶端套件 #5480
1.8.0 Notes 🟡 強化 agent-framework-declarative 已提升為候選版 #6256
1.7.0 Notes 🔴 中斷 宣告式:移除僅限 Python 的動作,並將別名類型重新命名為 C# 的標準名稱 #6126
1.7.0 Notes 🟡 強化 HarnessAgent 與背景代理程式執行框架提供者已新增 #6041
1.7.0 Notes 🟡 強化 A2AAgentSession 具有參考的工作識別碼與需要輸入的支援 #5980
1.6.0 Notes 🔴 中斷 核心與 Foundry 套件預設已啟用檢測 #5865
1.6.0 Notes 🟡 強化 具備本地與 Docker 執行支援的 Shell 工具 #5664
1.6.0 Notes 🟡 強化 全新 agent-framework-monty CodeAct 提供者套件 #5915
1.4.0 Notes 🔴 中斷 [實驗技能] 將檔案技能資料夾探索與 agentskills.io 規格保持一致 #5807
1.4.0 Notes 🔴 中斷 [實驗技能]將技能規格中繼資料萃取至 SkillFrontmatter #5775
1.4.0 Notes 🔴 中斷 DevUI:加強預設存取控制與 CORS 態勢 #5740
1.4.0 Notes 🔴 中斷 A2A:遷移到 a2a-sdk v1.0 #5752
1.3.0 Notes 🔴 中斷 [實驗技能]將代理技能重組為多來源架構 #5584
1.3.0 Notes 🟡 強化 ClassSkill 適用於以類別為基礎且具備宣告式中繼資料的技能定義 #5678
1.3.0 Notes 🟡 強化 資訊流控制提示注入防禦 #5331
1.3.0 Notes 🟡 強化 github-copilot-sdk已升級至 v1.0.0b2,並包含 instruction_directories 和 copilot_home #5665
1.2.2 Notes 🔴 中斷 編排終端輸出標準化為 AgentResponse; Workflow.as_agent() 僅回傳最終答案 #5301
1.2.2 Notes 🟡 強化 Azure AI Content Understanding 內容提供者套件 #4829
1.1.0 Notes 🔴 中斷 CosmosCheckpointStorage 預設限制 pickle 還原序列化 #5200
1.1.0 Notes 🟡 強化 GeminiChatClient 已新增 #4847
1.1.0 Notes 🟡 強化 超輕型CodeAct套件 #5185
1.1.0 Notes 🟡 強化 Foundry 工具箱支援 #5346
1.1.0 Notes 🟡 強化 finish_reason 在 AgentResponse 和 AgentResponseUpdate 上 #5211
1.0.1 Notes 🔴 中斷 FileCheckpointStorage 限制 pickle 還原序列化 (安全性強化) #4941
1.0.1 Notes 🔴 中斷 交接工作流程上下文管理修正 #5136
1.0.1 Notes 🟡 強化 適用於工作流程的 Cosmos DB NoSQL 檢查點儲存體 #4916
1.0.0 Notes 🔴 中斷 Message(..., text=...) 建構已完全移除;請改用 contents=[...] 建立文字訊息 #5062
1.0.0 Notes 🟡 強化 已發布的 Python 套件(agent-framework,agent-framework-core,agent-framework-openai,agent-framework-foundry)不再需要--pre;但 beta 連接器仍然需要。 #5062
1.0.0 Notes 🔴 中斷 Python 嵌入已移至 agent_framework.foundry;請使用 agent-framework-foundry、FoundryEmbeddingClient 和 FOUNDRY_MODELS_* 設定來取代已移除的 agent-framework-azure-ai 套件。 #5056
1.0.0 Notes 🔴 中斷 workflow.run() 現已使用明確的 function_invocation_kwargs / client_kwargs,全域與個別執行程式的目標設定則由執行程式識別碼決定 #5010
1.0.0 Notes 🟡 強化 GitHubCopilotAgent 現在調用上下文提供者 before_run / after_run 鉤子函式,並包含提供者新增的提示上下文 #5013
1.0.0 Notes 🟡 強化 Python 結構化輸出現在接受 JSON 結構映射為 response_format,解析後的 JSON 會顯示在 response.value #5022
1.0.0rc6 僅限公共關係使用 🔴 中斷 已移除已棄用的 Azure/OpenAI 相容性介面;請改用建議的 OpenAI 客戶端或 Foundry Python 客戶端。 #4990
1.0.0rc6 僅限公共關係使用 🔴 中斷 提供者主導的重構:分割 agent-framework-openai、agent-framework-foundry 和 agent-framework-foundry-local;重新命名 OpenAI 用戶端;將 Foundry 移至 agent_framework.foundry;並將 Azure AI 與 Assistants 相容性路徑標示為已取代 #4818
1.0.0rc6 僅限公共關係使用 🔴 中斷 agent-framework-core 現在刻意精簡;請安裝指定的提供者套件,如 agent-framework-openai 或 agent-framework-foundry,並在最少安裝時手動安裝 mcp 以獲得 MCP 工具,或使用 agent-framework 元套件以取得更全面的預設體驗。 #4904
1.0.0rc6 僅限公共關係使用 🔴 中斷 一般 agent_framework.openai 用戶端現在偏好明確的路由訊號;當設定 OPENAI_API_KEY 時,OpenAI 會保持使用 OpenAI,而 Azure 情境則應傳遞明確的 Azure 路由輸入 (例如 credential 或 azure_endpoint),然後再設定 api_version #4925
1.0.0rc5 / 1.0.0b260318 無(排定) 🔴 中斷 公用執行階段 kwarg 已分割為 function_invocation_kwargs 與 client_kwargs;工具現在使用 FunctionInvocationContext / ctx.session #4581
1.0.0rc4 / 1.0.0b260311 Notes 🔴 中斷 Azure AI 整合現在以 azure-ai-projects 2.0 GA 為目標;foundry_features 已移除,且 allow_preview 為預覽版選擇加入項目 #4536
1.0.0rc4 / 1.0.0b260311 Notes 🔴 中斷 GitHub Copilot 整合現使用 ToolInvocation / ToolResult; agent-framework-github-copilot 需要 Python 3.11+ #4551
1.0.0rc3 / 1.0.0b260304 Notes 🔴 中斷 技能提供者新增了程式碼定義的 Skill / SkillResource;舊版的 FileAgentSkillsProvider 匯入與反引號資源參考必須更新 #4387
1.0.0rc2 / 1.0.0b260226 Notes 🔴 中斷 宣告式工作流程將InvokeTool替換為InvokeFunctionTool和WorkflowFactory.register_tool() #3716
1.0.0rc1 / 1.0.0b260219 Notes 🔴 中斷 跨 Azure 套件的統一 Azure 憑證處理 #4088
1.0.0rc1 / 1.0.0b260219 Notes 🔴 中斷 Python 例外階層重新設計於 AgentFrameworkException #4082
1.0.0rc1 / 1.0.0b260219 Notes 🔴 中斷 提供者狀態現範疇限定於 source_id #3995
1.0.0rc1 / 1.0.0b260219 Notes 🔴 中斷 自訂 get_response() 實作必須接受 Sequence[Message] #3920
1.0.0rc1 / 1.0.0b260219 Notes 🔴 中斷 FunctionTool[Any] 結構描述傳遞填充碼已移除 #3907
1.0.0rc1 / 1.0.0b260219 Notes 🔴 中斷 設定從 AFBaseSettings / pydantic-settings 移到 TypedDict + load_settings() #3843, #4032
1.0.0rc1 / 1.0.0b260219 Notes 🟡 強化 推理模型工作流程交接和歷史序列化問題已修正 #4083
1.0.0rc1 / 1.0.0b260219 Notes 🟡 強化 Bedrock 已新增至 core[all];已修正 tool-choice 的預設值 #3953
1.0.0rc1 / 1.0.0b260219 Notes 🟡 強化 AzureAIClient 會針對不支援的執行階段覆寫發出警告 #3919
1.0.0rc1 / 1.0.0b260219 Notes 🟡 強化 workflow.as_agent() 當提供者未設定時,會注入本地歷史 #3918
1.0.0rc1 / 1.0.0b260219 Notes 🟡 強化 OpenTelemetry 追蹤內容傳播至 MCP 要求 #3780
1.0.0rc1 / 1.0.0b260219 Notes 🟡 強化 Azure Functions 增加了持久化工作流程支援 #3630
1.0.0b260212 Notes 🔴 中斷 Hosted*Tool 課程被取消;透過客戶端 get_*_tool() 方法建立託管工具 #3634
1.0.0b260212 Notes 🔴 中斷 會話/上下文提供者管線已完成:AgentThread 已移除,請使用 AgentSession + context_providers #3850
1.0.0b260212 Notes 🔴 中斷 檢查點模型/儲存重構(workflow_id 移除、 previous_checkpoint_id 新增、儲存行為變更) #3744
1.0.0b260212 Notes 🟡 強化 AzureOpenAIResponsesClient 可以從 Foundry 專案端點建立,或 AIProjectClient #3814
1.0.0b260212 Notes 🔴 中斷 中介軟體的延續功能不再接受context,請將call_next(context)更新為call_next()。 #3829
1.0.0b260210 Notes 🔴 中斷 send_responses() / send_responses_streaming() 移除; 使用 workflow.run(responses=...) #3720
1.0.0b260210 Notes 🔴 中斷 SharedState → State;工作流程狀態 API 是同步的,檢查點狀態欄位會重新命名 #3667
1.0.0b260210 Notes 🔴 中斷 協調流程建置器已移至 agent_framework.orchestrations 套件。 #3685
1.0.0b260210 Notes 🟡 強化 為 Python 代理回應新增背景回應與 continuation_token 支援 #3808
1.0.0b260210 Notes 🟡 強化 並排新增的會話/上下文預覽類型 (SessionContext, BaseContextProvider) #3763
1.0.0b260210 Notes 🟡 強化 串流程式碼解譯器更新現在包含遞增程式碼差異 #3775
1.0.0b260210 Notes 🟡 強化 @tool Decorator 新增了明確的結構處理支援 #3734
1.0.0b260210 Notes 🔴 中斷 register_executor() / register_agent() 已從 WorkflowBuilder 中移除; 直接使用實例,分離狀態的輔助方法 #3781
1.0.0b260210 Notes 🔴 中斷 ChatAgent → Agent, ChatMessage → Message, RawChatAgent → RawAgent, ChatClientProtocol → SupportsChatGetResponse #3747
1.0.0b260210 Notes 🔴 中斷 類型 API 審查:Role/FinishReason 類型變更、回應/更新建構函式收緊、協助程式重新命名為 from_updates,以及移除 try_parse_value #3647
1.0.0b260210 Notes 🔴 中斷 API 統一於 run/get_response 和 ResponseStream #3379
1.0.0b260210 Notes 🔴 中斷 AgentRunContext 更名為 AgentContext #3714
1.0.0b260210 Notes 🔴 中斷 AgentProtocol 更名為 SupportsAgentRun #3717
1.0.0b260210 Notes 🔴 中斷 中介軟體 next 參數重新命名為 call_next #3735
1.0.0b260210 Notes 🔴 中斷 TypeVar 命名標準化(TName → NameT) #3770
1.0.0b260210 Notes 🔴 中斷 工作流程即代理程式的輸出與串流行為已與目前的代理程式回應流程保持一致 #3649
1.0.0b260210 Notes 🔴 中斷 流暢構建器方法在 6 個構建器中轉換為建構子參數 #3693
1.0.0b260210 Notes 🔴 中斷 工作流程事件統一為單一 WorkflowEvent,並使用 type 做為判別器。isinstance() → event.type == "..." #3690
1.0.0b260130 Notes 🟡 強化 ChatOptions / ChatResponse / AgentResponse 通用響應格式 #3305
1.0.0b260130 Notes 🟡 強化 BaseAgent 新增對 Claude Agent SDK 整合的支援 #3509
1.0.0b260128 Notes 🔴 中斷 AIFunction → FunctionTool, @ai_function → @tool #3413
1.0.0b260128 Notes 🔴 中斷 GroupChat/Magentic 的工廠模式; with_standard_manager → with_manager, participant_factories → register_participant #3224
1.0.0b260128 Notes 🔴 中斷 Github → GitHub #3486
1.0.0b260127 Notes 🟡 強化 BaseAgent 新增對 GitHub Copilot SDK 整合的支援 #3404
1.0.0b260123 Notes 🔴 中斷 內容類型整合為 Content 單一類別,並搭配類別方法。 #3252
1.0.0b260123 Notes 🔴 中斷 response_format 驗證錯誤現在會引發 ValidationError #3274
1.0.0b260123 Notes 🔴 中斷 AG-UI 運行邏輯簡化版 #3322
1.0.0b260123 Notes 🟡 強化 Anthropic 用戶端新增 response_format 對結構化輸出的支援 #3301
1.0.0b260123 Notes 🟡 強化 Azure AI 組態已擴充,支援 reasoning 與 rai_config #3403, #3265
1.0.0b260116 Notes 🔴 中斷 create_agent → as_agent #3249
1.0.0b260116 Notes 🔴 中斷 source_executor_id → executor_id #3166
1.0.0b260116 Notes 🟡 強化 AG-UI 支援服務受控工作階段/執行緒連續性 #3136
1.0.0b260114 Notes 🔴 中斷 重構的協調流程 (群組聊天、轉接、循序、並行) #3023
1.0.0b260114 Notes 🔴 中斷 選項可做為 TypedDict 與 Generic #3140
1.0.0b260114 Notes 🔴 中斷 display_name 移除; context_providers → context_provider (單數); middleware 必須為列表 #3139
1.0.0b260114 Notes 🔴 中斷 AgentRunResponse / AgentRunResponseUpdate 更名為 AgentResponse/AgentResponseUpdate #3207
1.0.0b260114 Notes 🟡 強化 為 YAML 定義的工作流程新增宣告式工作流程執行階段 #2815
1.0.0b260114 Notes 🟡 強化 MCP 載入/可靠性改進(連線遺失處理、分頁、表示控制) #3154
1.0.0b260114 Notes 🟡 強化 Foundry A2ATool 支援沒有明確目標 URL 的連線 #3127
1.0.0b260107 Notes — 沒有顯著變化 —
1.0.0b260106 Notes — 沒有顯著變化 —

下一步