Python 2026 重大更改指南

本文档列出了自2026年初开始的Python版本中的所有重大更改，包括不兼容性变更和可能影响您的代码的重要增强功能。 每个更改都标记为：

• 🔴 重大更改 - 需要更改代码才能升级
• 🟡 增强 — 新功能或改进;现有代码继续工作

本文档跟踪 2026 年预览版到 1.0.0 转换的重大 Python 更改，因此请在版本之间升级时参考它，以确保不会错过任何重要更改。 有关特定主题（例如选项迁移）的详细升级说明，请参阅链接的升级指南或链接的 PR。

python-1.0.0

本部分记录了在 python-1.0.0rc6 之后实现并且现在属于 python-1.0.0 的重要 Python 更改。

🔴 Message(..., text=...) 构造现已完全删除

PR：#5062

PR #5062 通过删除仍使用 Message 构造text=...对象的最后一个框架端代码路径，完成早期 Python 消息模型清理。

• 将文本消息构建为 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或AzureAIInferenceEmbeddingSettingsAzureAISettings。
• 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"],
)

🔴 工作流现在通过显式存储桶传递运行时关键字参数

PR：#5010

PR 更新 Python ，使运行时的 kwargs 显式作为 和 传递，而不是作为 泛型 转发。

• 平面映射被视为全局映射，并转发到工作流中的每个匹配代理执行程序。
• 如果一个或多个顶级键与执行程序 ID 匹配，则整个映射将被视为每个执行程序的目标，并且每个执行程序只接收其自己的条目。
• 自定义 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 上解析为与 JSON 兼容的 Python 值（通常为 dict 或 list）。
• 从流收集最终响应时，相同的分析规则适用。

这是一个增强功能，而不是破坏性更改，但了解你是否已将架构存储为类似于 JSON 的字典十分有用。

python-1.0.0rc6

此部分记录了与 python-1.0.0rc6 相关的 Python 重要更新。

🔴 模型选择在 model 上已标准化

PR：#4999

PR #4999 完成跨构造函数、类型化选项、代理默认值、响应对象和环境变量的 Python 端模型选择清理。

• 在您以前使用model_id的每个地方都使用model。
• Agent.default_options 和每次运行 options={...} 现在预期 "model"，而不是 "model_id"。
• 响应对象显示 response.model，而不是 response.model_id。
• OpenAI 设置现在使用OPENAI_MODEL、OPENAI_CHAT_MODEL和OPENAI_CHAT_COMPLETION_MODELOPENAI_EMBEDDING_MODEL。
• Azure OpenAI 设置现在使用AZURE_OPENAI_MODEL、AZURE_OPENAI_CHAT_MODEL和AZURE_OPENAI_CHAT_COMPLETION_MODELAZURE_OPENAI_EMBEDDING_MODEL。
• 人类现在使用 ANTHROPIC_CHAT_MODEL，Foundry Local 使用 FOUNDRY_LOCAL_MODEL。
• 人类程序包还会添加由提供者托管的包装器，例如 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 完成了#4818的提供程序主导迁移，此次迁移通过删除之前保留在早期预览版本中的剩余已弃用的 Python 兼容性接口来实现。

• agent_framework.azure 不再导出 AzureOpenAI* 或较旧的 AzureAI* 代理/客户端/提供程序界面。
• Python OpenAI 助手兼容性类型不再是当前 agent_framework.openai 图面的一部分。
• 使用 OpenAIChatClient、OpenAIChatCompletionClient 和 OpenAIEmbeddingClient 用于 OpenAI 或 Azure OpenAI 方案。
• 请使用 FoundryChatClient 进行 Foundry 项目的推理，使用 FoundryAgent 进行 Prompt Agents 或 HostedAgents。
• 当前 agent_framework.azure 命名空间现在涵盖剩余的 Azure 集成，例如 Azure AI 搜索、Cosmos 历史记录、Azure Functions 和持久工作流。 Foundry 聊天、代理、内存和嵌入客户端位于该处 agent_framework.foundry。

如果要迁移较旧的 Python 代码，请使用以下替换项：

• AzureOpenAIResponsesClient → OpenAIChatClient
• AzureOpenAIChatClient → OpenAIChatCompletionClient
• AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
• AzureAIAgentClient / AzureAIClient / AzureAIProjectAgentProvider / AzureAIAgentsProvider → FoundryChatClient ，还是 FoundryAgent取决于应用是否拥有代理定义
• OpenAIAssistantsClient / OpenAIAssistantProvider 用于当前的 Python OpenAI 工作，或者如果您在 Foundry 中需要一个由服务管理的代理，则使用FoundryAgent

🔴 领先的提供者客户端设计和软件包拆分

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 用于 Prompt Agents 和 HostedAgents，使用 FoundryLocalClient 用于本地运行时。
• AzureAIClient、AzureAIProjectAgentProvider、AzureAIAgentClient、AzureAIAgentsProvider 和 Python 助手的兼容性界面在此重构期间被移到兼容性路径，后来在 #4990 中被删除。
• 示例覆盖率已经重新组织，以匹配新的以提供商为主导的布局，包括 Foundry 示例samples/02-agents/providers/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→用于直接响应 API 迁移，或者FoundryAgent如果需要服务托管的 Foundry 代理

代码更改主要是类名移动和 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 的图面：

之前（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 OpenAI 资源的 URL 请使用azure_endpoint，如果您已经拥有完整的base_url URL，请使用.../openai/v1，并为所用的 Azure OpenAI API 接口设置api_version
• 为 Cloud Foundry 客户端使用 Foundry 特定的设置，例如 FOUNDRY_PROJECT_ENDPOINT、FOUNDRY_MODEL、FOUNDRY_AGENT_NAME 和 FOUNDRY_AGENT_VERSION。
• 使用 ANTHROPIC_CHAT_MODEL Anthropic 和 FOUNDRY_LOCAL_MODEL Foundry Local

此更改首先在 python-1.0.0rc6 周期中实现。

🔴 核心依赖项现在有意精简

PR：#4904

PR #4904 遵循从#4818中分拆提供程序包的方法，通过精简agent-framework-core并进一步删除核心包中的传递性提供程序依赖项。

• 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。
• 如果您想要“包含所有功能”的体验，请安装元包 agent-framework。

这 不会 再次重新设计提供方界面；只是当您仅引入核心组件时，它会更改默认安装的内容。

之前（仅核心安装通常以可传递方式引入更多提供程序功能）：

pip install agent-framework-core

在安装您实际使用的提供程序包后，进行以下操作：

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

或：

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 AZURE_OPENAI_* 。
• 如果 OPENAI_API_KEY 已配置，则泛型客户端将保留在 OpenAI 上，除非传递显式 Azure 路由信号，例如 credential 或 azure_endpoint。
• 如果只有 AZURE_OPENAI_* 设置存在，通用客户端仍可退回到基于 Azure 环境的路由策略。
• 首选的 Azure OpenAI 模式现在是传递显式 Azure 设置以及应用于credential=AzureCliCredential()、OpenAIChatClient、OpenAIChatCompletionClient的嵌入客户端。
• 弃用的 AzureOpenAI* 包装器会保留其兼容性行为，因此，基于包装的现有代码不遵循新的泛型客户端优先规则。

之前（OpenAIChatClient 可能会路由到 Azure，因为 Azure env vars 存在）：

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 嵌入现在遵循相同的路由模型：

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 的一层。

🔴 公共运行时 kwargs 拆分为显式存储桶

PR：#4581

公共 Python 代理和聊天 API 不再将公开 **kwargs 转发视为主要运行时数据机制。 运行时值现在按用途拆分：

• 仅限于工具或函数中间件看到的值, 使用function_invocation_kwargs。
• 使用 client_kwargs 来设置客户端层的关键字参数（kwargs）和客户端中间件配置。
• 通过 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 正式版

PR：#4536

Python Azure AI 集成现在假设 GA 2.0 azure-ai-projects 图面。

• 支持的依赖项范围现在为azure-ai-projects>=2.0.0,<3.0。
• foundry_features Azure AI 代理创建中已移除 passthrough 功能。
• 预览功能现在对支持的客户端/提供程序使用 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数据类。
• 使用snake_case字段（如ToolResult和result_type）返回 text_result_for_llm 。
• 该 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.types 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之预览/内部代码，请切换到当前公共 API 接口：

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 参数/助手已在所有与 Azure 相关的 Python 包中统一为 credential 参数。 新方法使用 azure.identity.get_bearer_token_provider 来实现自动令牌缓存和刷新。

受影响的类：AzureOpenAIChatClient、、AzureOpenAIResponsesClientAzureOpenAIAssistantsClientAzureAIClientAzureAIAgentClientAzureAIProjectAgentProviderAzureAIAgentsProviderAzureAISearchContextProvider、PurviewClient、。。 PurviewPolicyMiddlewarePurviewChatPolicyMiddleware

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，或者一个可调用的令牌提供程序。 自动处理令牌缓存和刷新。

🔴 重新设计的 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、、ServiceInitializationErrorServiceResponseExceptionServiceContentFilterExceptionServiceInvalidAuthErrorServiceInvalidExecutionSettingsErrorServiceInvalidRequestErrorServiceInvalidResponseErrorAgentExecutionExceptionAgentInvocationError、AgentInitializationError、AgentSessionException、。 ChatClientInitializationErrorCheckpointDecodingError

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
    ...

🔴 由范围定义的提供程序状态 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 vs get_response）

PR：#3920

聊天客户端 get_response 的实现现在可以一致地接收 Sequence[Message]。 agent.run(...) 在调用聊天客户端之前保持灵活（str、 Content或 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()

PR：#3843、 #4032

基于pydantic-settingsAFBaseSettings的类已被一个新的基于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.openai import OpenAISettings, load_settings

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

🟡 修复推理模型工作流移交和历史记录序列化

PR：#4083

修复了在多代理工作流中使用推理模型（例如 gpt-5-mini、gpt-5.2）时的多个故障。 响应 API 中的推理项现在已正确序列化，并且仅在存在 `function_call` 时才包含在历史记录中，从而防止 API 错误。 加密/隐藏推理内容现在已正确生成，并且 summary 字段格式已更正。 在交接时，也会清除service_session_id，以防止跨代理状态泄漏。

🟡 基岩已添加到 core[all] 中，并修正了工具选择的默认设置。

PR：#3953

Amazon Bedrock 现在包含在附加组件 agent-framework-core[all] 中，可通过 agent_framework.amazon 惰性导入界面获得。 工具选择行为也已修复：未设置的工具选项值现在保持未修改，提供程序将使用其服务默认值，而显式设置的值则会被保留。

from agent_framework.amazon import BedrockClient

🟡 AzureAIClient 警告不受支持的运行时重载

PR：#3919

更改时，如果运行时的 tools 或 structured_output 与代理的创建时配置不一致，AzureAIClient 会记录一条警告。 此后，该 Python 图面已被删除。 对于当前的 Python 代码，使用 FoundryChatClient 当您需要应用拥有的工具/运行时配置时，或使用 OpenAIChatClient 用于需要动态替代的直接响应 API 场景。

🟡 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.

🟡 传播到 MCP 请求的 OpenTelemetry 跟踪上下文

PR：#3780

安装 OpenTelemetry 后，跟踪上下文（例如 W3C traceparent）会通过 params._meta 自动注入到 MCP 请求中。 这样就可以跨代理→ MCP 服务器调用进行端到端分布式跟踪。 无需更改代码 - 这是在有效跨度上下文存在时激活的累加行为。

🟡 Azure Functions 的持久性工作流支持

PR：#3630

该 agent-framework-azurefunctions 包现在支持在 Azure Durable Functions 上运行 Workflow 图。 将参数传递给workflow以自动注册代理实体、活动函数和 HTTP 终结点AgentFunctionApp。

from agent_framework.azurefunctions 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

为了支持客户端作用域的工厂方法，已移除托管工具类。 这使工具的可用性由提供者显式化。

Before:

from agent_framework import HostedCodeInterpreterTool, HostedWebSearchTool

tools = [HostedCodeInterpreterTool(), HostedWebSearchTool()]

After:

from agent_framework.openai import OpenAIResponsesClient

client = OpenAIResponsesClient()
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=[...]

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_edges、add_chain、add_switch_case_edge_group、add_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

通过删除冗余 Chat 前缀，简化了核心 Python 类型。 未提供任何后向兼容别名。

更新导入

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")])

🔴 类型 API 查看响应/消息模型中的更新

PR：#3647

此版本包括消息/响应键入和帮助程序 API 的广泛中断性清理。

• Role和FinishReason现在是NewType包装器，包裹str，适用于已知值的RoleLiteral/FinishReasonLiteral。 将它们视为字符串（无 .value 用法）。
• Message 的构造按照 Message(role, contents=[...]) 标准化；contents 中的字符串会自动转换为文本内容。
• ChatResponse 和 AgentResponse 构造函数现在以 messages=（单个 Message 或一系列 Message）为中心，旧 构造函数的使用情况已从响应中删除。
• ChatResponseUpdate 和 AgentResponseUpdate 不再接受 text=，请使用 contents=[Content.from_text(...)]。
• 更新合并助手名称已简化。
• try_parse_value已从ChatResponse和AgentResponse中移除。

辅助方法重命名

更新响应更新构造

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)

🔴 核心上下文/协议类型重命名

PR：#3714、 #3717

相应地更新导入和类型注释。

🔴 中间件延续参数已重命名为 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 builder 方法转移至构造函数参数

PR：#3693

跨 6 个生成器（WorkflowBuilder、SequentialBuilder、ConcurrentBuilder、GroupChatBuilder、MagenticBuilder、HandoffBuilder）的单一配置Fluent方法已迁移到构造函数参数中。 为了优先使用构造函数参数，删除了作为唯一配置路径的 Fluent 方法。

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 作为构造函数参数（以前通过 fluent 方法设置）
• SequentialBuilder、ConcurrentBuilder、GroupChatBuilder和MagenticBuilder现在在构建时需要要么participants，要么participant_factories——如果两者都不传递，将引发ValueError。

🔴将工作流事件通过WorkflowEvent区分器统一到单一的type

PR：#3690

所有单个工作流事件子类都已替换为单个泛型 WorkflowEvent[DataT] 类。 现在，你无需使用isinstance()检查来标识事件类型，而是检查event.type字符串文本（例如，"output"、"request_info"）。 "status" 这种情况与Content的类python-1.0.0b260123合并所遵循的模式相同。

已删除的事件类

以下导出的事件子类不再存在：

更新导入

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_stream(input_message):
    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_stream(input_message):
    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_stream("Write a blog post about AI agents."):
    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

🔴 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],
):
    ...

🔴 SharedState 重命名为 State;工作流状态 API 是同步的

PR：#3667

状态 API 不再需要 await，并且命名已标准化：

🔴 编排构建器转移到 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、 ChatResponse和 AgentResponse 现在由响应格式类型参数化的泛型类型。 当使用结构化输出与 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!)

🟡 BaseAgent 添加了对 Claude 代理 SDK 的支持

PR：#3509

Python SDK 现在包含了 BaseAgent Claude Agent SDK 的实现，使其在 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.core import tool, FunctionTool

@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)

🔴 向 GroupChat 和 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.workflows 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 类，以创建特定类型。

完整迁移参考

附加的新方法（没有直接先导）：

• 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.core 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.core 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 的定义。

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"
}

🔴 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 AGUIEndpoint

endpoint = AGUIEndpoint(agent=agent)
result = await endpoint.run(
    request=request,
    streaming=True,
    timeout=30
)

🟡 人类客户端现在支持 response_format 结构化输出

PR：#3301

现在，可以通过与 OpenAI 和 Azure 客户端类似的方式将结构化输出分析与 response_formatAnthropic 客户端配合使用。

🟡 扩展的 Azure AI 配置 （reasoning， rai_config）

PR：#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.core import ChatClient

client = ChatClient(...)
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(...):
    if isinstance(event, WorkflowOutputEvent):
        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， ， GroupChatOrchestratorAgentBasedGroupChatOrchestrator）。 使用广播模型简化为星形拓扑。
• 交接：删除了单层级、协调器和自定义执行程序支持。 已迁移到广播模型并使用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.workflows import (
    GroupChatOrchestrator,
    HandoffAgentExecutor,
    AgentApprovalExecutor
)

# 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 （复数，接受列表）更改为 context_provider （单数，只允许 1 个）
• 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.core import Agent

# Only one context provider allowed; combine manually if needed
agent = Agent(
    name="my-agent",  # display_name removed
    context_provider=provider1,  # singular, only 1
    middleware=[my_middleware],  # must be a list now
)

# For multiple context providers, 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

此版本中没有重大更改。

摘要表

后续步骤