Python 2026 重大變更指南

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

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

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

未發行

🔴 中介軟體的輸入需要依序排列，而 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 整合，如 Azure AI 搜尋、Cosmos 歷史、Azure 函式及持久工作流程。 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`
Foundry Local	`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-project.services.ai.azure.com",
    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 --pre 。若要支援 WebSocket MCP，請安裝 mcp[ws] --pre。
如果你想要全面的「全部包含」體驗，就安裝 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

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 會被觸發。

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

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

🔴 `HostedTool` 類別被用戶端 `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-project>.services.ai.azure.com",
    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
未發行	—	🔴 中斷	中介軟體輸入項需要序列；請直接安裝 `agent-hooks-sdk`，而不要使用已移除的核心額外套件	#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	🔴 中斷	`HostedTool` 課程被取消;透過客戶端 `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	—	沒有顯著變化	—

下一步

支援概觀

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-03

Python 2026 重大變更指南

未發行

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

python-1.16.0（2026年8月27日）

🟡 程式化 OpenTelemetry 提供者配置

python-1.15.0（2026年8月21日）

🔴 OpenTelemetry GenAI 語意慣例已整併

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

python-1.14.0（2026年8月14日）

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

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

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

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

python-1.8.0（2026年6月4日）

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

 透過 FunctionInvocationContext 公開漸進式工具

🟡 基於 MCP 的技能發現（McpSkillsSource）

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

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

🟡 Mistral AI 嵌入客戶端套件

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

python-1.7.0（2026年5月28日）

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

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

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

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

python-1.6.0（2026年5月21日）

🔴 預設啟用檢測功能

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

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

python-1.4.0（2026年5月14日）

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

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

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

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

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

python-1.3.0（2026年5月7日）

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

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

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

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

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

🟡 OpenAI 與 Gemini allowed_tools 工具選擇支援

python-1.2.2（2026年4月29日）

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

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

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

python-1.1.0（2026年4月21日）

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

🟡 GeminiChatClient 新增內容

🟡 超輕量 CodeAct 套件

🟡 Foundry 工具箱支援

🟡 finish_reason 在 AgentResponse 和 AgentResponseUpdate 上

🟡 Foundry 中的託管代理 V2 支援

python-1.0.1（2026年4月9日）

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

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

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

python-1.0.0（2026年4月2日）

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

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

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

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

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

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

python-1.0.0rc6

🔴 模型選擇標準化為 model

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

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

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

套件映射

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

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

python-1.0.0rc5 / python-1.0.0b260319（2026年3月19日）

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

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

python-1.0.0rc4 / python-1.0.0b260311 （2026年3月11日）

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

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

python-1.0.0rc3 / python-1.0.0b260304（2026年3月4日）

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

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

 透過 `FunctionInvocationContext` 公開漸進式工具

🟡 基於 MCP 的技能發現（`McpSkillsSource`）

 `agent-framework-declarative` 已提升為候選版

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

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

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

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

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

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

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

🟡 OpenAI 與 Gemini `allowed_tools` 工具選擇支援

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

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

🟡 `GeminiChatClient` 新增內容

🟡 `finish_reason` 在 `AgentResponse` 和 `AgentResponseUpdate` 上

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

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

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

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

🔴 模型選擇標準化為 `model`

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

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

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

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

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

🔴 聊天/客服訊息輸入對齊（`run` 與 `get_response`）

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

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

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

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

🔴 `HostedTool` 類別被用戶端 `get__tool()` 方法取代

🔴 會話/上下文提供者管道已完成`AgentSession`（`context_providers`）

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

🔴 中介軟體 `call_next` 不再接受 `context`

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

`WorkflowBuilder` 與執行程式

`WorkflowBuilder` 與經紀人合作

🔴 `ChatAgent` 重新命名為 `Agent`， `ChatMessage` 再命名為 `Message`

將 `try_parse_value` 替換為 `try/except` 於 `.value`

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

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

🔴 TypeVar 名稱標準化（`TName` → `NameT`）

`WorkflowBuilder`

`SequentialBuilder` / `ConcurrentBuilder`

`GroupChatBuilder`

`MagenticBuilder`

`HandoffBuilder`

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

使用 `AgentResponseUpdate` 串流

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

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

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

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

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

🟡 `BaseAgent` 新增對 Claude Agent SDK 的支援

🔴 `AIFunction`更名為 `FunctionTool` 及`@ai_function@tool`

🔴 `Github` 更名為 `GitHub`

🟡 `BaseAgent` 新增對 GitHub Copilot SDK 的支援