Guia de alterações significativas do Python 2026

Este documento lista todas as alterações significativas nas versões do Python desde o início de 2026, incluindo alterações significativas e aprimoramentos importantes que podem afetar seu código. Cada alteração é marcada como:

• 🔴 Interrupção – requer alterações de código para atualizar
• 🟡 Aprimoramento – nova funcionalidade ou melhoria; o código existente continua a funcionar

Este documento será removido quando chegarmos à versão estável 1.0.0, portanto, consulte-o ao atualizar entre as versões em 2026 para garantir que você não perca nenhuma alteração importante. Para obter instruções de atualização detalhadas sobre tópicos específicos (por exemplo, migração de opções), consulte os guias de atualização vinculados ou as PR vinculadas.

python-1.0.0rc1 / python-1.0.0b260219 (19 de fevereiro de 2026)

Lançamento:agent-framework-core e agent-framework-azure-ai promovido a 1.0.0rc1. Todos os outros pacotes atualizados para 1.0.0b260219.

🔴 Manipulação unificada de credenciais do Azure em todos os pacotes

PR:#4088

Os parâmetros/auxiliares ad_token, ad_token_provider e get_entra_auth_token foram substituídos por um único parâmetro credential em todos os pacotes relacionados ao Python no Azure. A nova abordagem usa azure.identity.get_bearer_token_provider para cache e atualização de token automático.

Classes afetadas:AzureOpenAIChatClient, AzureOpenAIResponsesClient, , AzureOpenAIAssistantsClient, AzureAIClient, AzureAIAgentClient, AzureAIProjectAgentProvider, AzureAIAgentsProvider, AzureAISearchContextProvider, , PurviewClient, , PurviewPolicyMiddleware. PurviewChatPolicyMiddleware

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(),
    ...
)

O credential parâmetro aceita TokenCredential, AsyncTokenCredentialou um provedor de token que pode ser chamado. O cache de token e a atualização são tratados automaticamente.

🔴 Hierarquia de exceções reprojetada do Python

PR:#4082

A família plana ServiceException foi substituída por ramificações de exceção com escopo de domínio sob uma única raiz AgentFrameworkException. Isso fornece aos chamadores destinos precisos except e semântica de erro clara.

Nova hierarquia:

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

Exceções removidas: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
    ...

🔴 Estado do provedor definido por source_id

PR:#3995

Os hooks do provedor agora recebem um dicionário de estado com escopo específico de provedor (state.setdefault(provider.source_id, {})) em vez do estado completo da sessão. Isso significa que as implementações do provedor que acessaram anteriormente o estado aninhado por meio de state[self.source_id]["key"] agora devem acessar state["key"] diretamente.

Além disso, InMemoryHistoryProvider o padrão source_id foi alterado de "memory" para "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")

🔴 Alinhamento de digitação de mensagem de chat/agente (run vs get_response)

PR:#3920

As implementações do cliente get_response de chat agora recebem Sequence[Message]consistentemente. agent.run(...) permanece flexível (str, Content, Messageou sequências deles) e normaliza as entradas antes de chamar clientes de chat.

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] configuração genérica removida para passagem de esquema

PR:#3907

Os caminhos de ferramenta baseados em esquema não dependem mais do comportamento genérico anterior FunctionTool[Any] . Use FunctionTool diretamente e forneça um pydantic BaseModel ou esquemas explícitos quando necessário (por exemplo, com @tool(schema=...)).

Before:

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

After:

placeholder: FunctionTool = FunctionTool(...)

🔴 Configurações pedantes substituídas por TypedDict + load_settings()

PRs:#3843, #4032

A classe baseada em pydantic-settingsAFBaseSettings foi substituída por um sistema leve de configurações baseado em funções usando TypedDict e load_settings(). A pydantic-settings dependência foi totalmente removida.

Todas as classes de configurações (por exemplo, OpenAISettings, , AzureOpenAISettings, AnthropicSettings) agora TypedDict são definições e os valores de configurações são acessados por meio da sintaxe do dicionário em vez de acesso ao atributo.

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_id = settings["model_id"]

🟡 Corrigir a entrega do fluxo de trabalho do modelo de raciocínio e a serialização do histórico

PR:#4083

Corrige várias falhas ao usar modelos de raciocínio (por exemplo, gpt-5-mini, gpt-5.2) em fluxos de trabalho de vários agentes. Os itens de raciocínio da API de Respostas agora são serializados corretamente e incluídos apenas no histórico quando um function_call também está presente, evitando erros de API. O conteúdo de raciocínio criptografado/oculto agora é emitido corretamente e o formato de summary campo é corrigido. O service_session_id também é liberado na entrega para evitar vazamento de estado entre agentes.

🟡 Bedrock adicionado a core[all] e padrões de escolha de ferramentas foram corrigidos

PR:#3953

A Amazon Bedrock agora está incluída nos agent-framework-core[all] extras e está disponível através da agent_framework.amazon superfície de importação lenta. O comportamento de escolha da ferramenta também foi corrigido: os valores de escolha de ferramenta não definidos agora permanecem não definidos para que os provedores usem seus padrões de serviço, enquanto os valores definidos explicitamente são preservados.

from agent_framework.amazon import BedrockClient

🟡 AzureAIClient alerta sobre substituições de tempo de execução sem suporte

PR:#3919

AzureAIClient agora registra um aviso quando o runtime tools ou structured_output difere da configuração de tempo de criação do agente. O Serviço do Agente de IA do Azure não dá suporte a alterações de formato de resposta ou ferramenta de runtime. Em vez disso, use AzureOpenAIResponsesClient se você precisar de substituições dinâmicas.

🟡 workflow.as_agent() agora, o histórico local é padrão quando os provedores não são definidos

PR:#3918

Quando workflow.as_agent() é criado sem context_providers, ele agora adiciona InMemoryHistoryProvider("memory") por padrão. Se os provedores de contexto forem fornecidos explicitamente, essa lista será preservada inalterada.

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

🟡 Contexto de rastreamento OpenTelemetry propagado para solicitações MCP

PR:#3780

Quando OpenTelemetry é instalado, o contexto de rastreamento (por exemplo, W3C traceparent) é injetado automaticamente em solicitações MCP por meio de params._meta. Isso permite o rastreamento distribuído de ponta a ponta entre chamadas de servidor MCP → agente. Nenhuma alteração de código é necessária: esse é um comportamento aditivo que é ativado quando há um contexto de intervalo válido.

🟡 Suporte de fluxo de trabalho durável para o Azure Functions

PR:#3630

O agent-framework-azurefunctions pacote agora dá suporte à execução Workflow de grafos no Azure Durable Functions. Passe um workflow parâmetro para AgentFunctionApp, a fim de registrar automaticamente entidades de agente, funções de atividade e pontos de extremidade HTTP.

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

Dá suporte a fan-out/fan-in, estado compartilhado e padrões humanos no loop com tempo limite configurável e rejeição automática na expiração.

python-1.0.0b260212 (12 de fevereiro de 2026)

Notas de versão:python-1.0.0b260212

🔴 Hosted*Toolclasses substituídas por métodos de cliente get_*_tool()

PR:#3634

As classes de ferramentas hospedadas foram removidas em favor de métodos de fábrica com escopo de cliente. Isso torna a disponibilidade da ferramenta explícita para cada provedor.

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

🔴 Pipeline do provedor de sessão e contexto finalizado (AgentSession, context_providers)

PR:#3850

A sessão do Python e a migração do provedor de contexto foram concluídas. AgentThread e os tipos de provedor de contexto antigos foram removidos.

• 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= os padrões são substituídos por 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)

🔴 Modelo de ponto de verificação e comportamento de armazenamento refatorados

PR:#3744

A estrutura interna do ponto de verificação foi redesenhada, o que afeta a compatibilidade dos pontos de verificação persistentes e as implementações personalizadas de armazenamento.

• WorkflowCheckpoint agora armazena objetos dinâmicos (a serialização ocorre no armazenamento de ponto de verificação)
• FileCheckpointStorage agora usa serialização pickle
• workflow_id foi removido e previous_checkpoint_id foi adicionado
• Ganchos de ponto de verificação obsoletos foram removidos

Se você persistir pontos de verificação entre versões, regenere ou migre artefatos de ponto de verificação existentes antes de retomar os fluxos de trabalho.

🟡 AzureOpenAIResponsesClient suporta endpoints de projeto do Microsoft Foundry

PR:#3814

Agora você pode criar AzureOpenAIResponsesClient com um endpoint de projeto do Foundry ou AIProjectClient, e não apenas endpoints diretos do Azure OpenAI.

from azure.identity import DefaultAzureCredential
from agent_framework.azure import AzureOpenAIResponsesClient

client = AzureOpenAIResponsesClient(
    project_endpoint="https://<your-project>.services.ai.azure.com",
    deployment_name="gpt-4o-mini",
    credential=DefaultAzureCredential(),
)

🔴 Middleware call_next não aceita mais context

PR:#3829

A continuação do middleware agora não usa argumentos. Se o middleware ainda chamar call_next(context), atualize-o para 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 (10 de fevereiro de 2026)

Notas de versão:python-1.0.0b260210

🔴 Métodos de fábrica de fluxo de trabalho removidos WorkflowBuilder

PR:#3781

register_executor() e register_agent() foram removidos de WorkflowBuilder. Todos os métodos do construtor (add_edge, add_fan_out_edges, add_fan_in_edges, , add_chain, add_switch_case_edge_group) add_multi_selection_edge_groupe start_executor não aceitam mais nomes de cadeia de caracteres – eles exigem instâncias de executor ou agente diretamente.

Para isolamento de estado, envolva a instanciação do executor/agente e a construção de fluxo de trabalho dentro de um método auxiliar para que cada chamada produza novas instâncias.

WorkflowBuilder com executores

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 com agentes

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

Isolamento de estado com métodos auxiliares

Para fluxos de trabalho que precisam de estado isolado por invocação, encapsule a construção em um método auxiliar:

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 renomeado como Agent, ChatMessage renomeado para Message

PR:#3747

Os principais tipos de Python foram simplificados removendo o prefixo redundante Chat . Nenhum alias de compatibilidade com versões anteriores são fornecidos.

Atualizar importações

Before:

from agent_framework import ChatAgent, ChatMessage

After:

from agent_framework import Agent, Message

Atualizar referências de tipo

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

🔴 Tipos de atualizações de revisão de API em modelos de resposta/mensagem

PR:#3647

Esta versão inclui uma limpeza ampla e significativa das APIs auxiliares e de digitação de mensagem/resposta.

• Role e FinishReason agora são wrappers sobre NewTypestr com RoleLiteral/FinishReasonLiteral para valores conhecidos. Trate-as como cadeias de caracteres (sem .value uso).
• Message a padronização da construção é feita em Message(role, contents=[...]); strings em contents são convertidas automaticamente para conteúdo de texto.
• ChatResponse e AgentResponse construtores agora centralizados ( messages= único Message ou sequência); o uso do construtor herdado text= foi removido das respostas.
• ChatResponseUpdate e AgentResponseUpdate não aceitam mais text=; use contents=[Content.from_text(...)].
• Os nomes auxiliares de combinação de atualizações foram simplificados.
• try_parse_value foi removido de ChatResponse e AgentResponse.

Renomeações de método auxiliar

Atualizar a construção da atualização de resposta

Before:

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

After:

from agent_framework import AgentResponseUpdate, Content

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

Substituir try_parse_value por try/except em .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}")

🔴Modelo e uso unificados run/get_responseResponseStream

PR:#3379

As APIs do Python foram consolidadas em torno de agent.run(...) e client.get_response(...), com streaming representado por 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)

🔴 Renomeações de tipo de protocolo/contexto principal

PRs:#3714, #3717

Atualize as importações e digite anotações adequadamente.

🔴 Parâmetro de continuação do middleware renomeado para call_next

PR:#3735

As assinaturas de middleware agora devem ser usadas call_next em vez de 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)

🔴 Nomes typeVar padronizados (TName → NameT)

PR:#3770

A base de código agora segue um estilo de nomenclatura TypeVar consistente em que o sufixo T é usado.

Before:

TMessage = TypeVar("TMessage")

After:

MessageT = TypeVar("MessageT")

Se você mantiver wrappers personalizados em torno de genéricos de framework, alinhe os nomes TypeVar locais com a nova convenção para reduzir a mudança nas anotações.

🔴 Alterações de saída e streaming de fluxo de trabalho como agente

PR:#3649

workflow.as_agent() o comportamento foi atualizado para alinhar a saída e o streaming com padrões de resposta do agente padrão. Examine os consumidores de fluxo de trabalho como agente que dependem do tratamento herdado de saída/atualização e atualize-os para o fluxo atual AgentResponse/AgentResponseUpdate .

🔴 Métodos de construção fluente convertidos em parâmetros do construtor

PR:#3693

Métodos fluentes de configuração única em seis construtores (WorkflowBuilder, , SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, MagenticBuilder, HandoffBuilder) foram migrados para parâmetros de construtor. Métodos fluentes que eram o único caminho para ajustar uma configuração são substituídos por argumentos de construtor.

WorkflowBuilder

set_start_executor(), with_checkpointing()e with_output_from() são removidos. Em vez disso, use parâmetros de construtor.

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()e with_checkpointing()with_intermediate_outputs() são removidos. Em vez disso, use parâmetros de construtor.

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()e with_checkpointing()with_intermediate_outputs() são removidos. Em vez disso, use parâmetros de construtor.

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()e with_checkpointing()with_intermediate_outputs() são removidos. Em vez disso, use parâmetros de construtor.

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() e with_termination_condition() são removidos. Em vez disso, use parâmetros de construtor.

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

Alterações de validação

• WorkflowBuilder agora requer start_executor como um argumento construtor (definido anteriormente por meio do método fluente)
• SequentialBuilder, ConcurrentBuilder, GroupChatBuilder e MagenticBuilder agora exigem ou participants ou participant_factories em tempo de construção — não passando nenhum deles gera ValueError

🔴 Eventos de fluxo de trabalho unificados em um único WorkflowEvent com type discriminador.

PR:#3690

Todas as subclasses de evento de fluxo de trabalho individuais foram substituídas por uma única classe genérica WorkflowEvent[DataT] . Em vez de usar isinstance() verificações para identificar tipos de evento, agora você verifica o literal da cadeia de caracteres event.type (por exemplo, "output", "request_info", "status"). Isso segue o mesmo padrão da Content consolidação da classe a partir de python-1.0.0b260123.

Classes de evento removidas

As seguintes subclasses de evento exportadas não existem mais:

Atualizar importações

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

Atualizar verificações de tipo de evento

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

Transmissão com 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}")

Digitar anotações

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* Removido; Usar workflow.run(responses=...)

PR:#3720

send_responses() e send_responses_streaming() foram removidos de Workflow. Continue os fluxos de trabalho pausados passando respostas diretamente para 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 renomeado para State; as APIs de estado do fluxo de trabalho são síncronas

PR:#3667

As APIs de estado não são mais necessárias awaite a nomenclatura foi padronizada:

🔴 Construtores de orquestração transferidos para agent_framework.orchestrations

PR:#3685

Os construtores de orquestração agora estão em um namespace de pacote dedicado.

Before:

from agent_framework import SequentialBuilder, GroupChatBuilder

After:

from agent_framework.orchestrations import SequentialBuilder, GroupChatBuilder

🟡 Respostas em segundo plano e tokens de continuação de execução prolongada

PR:#3808

Agora há suporte para respostas em segundo plano em execuções de agente do Python através de options={"background": True} e 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é-visualizações dos tipos de provedor de sessão/contexto adicionadas lado a lado

PR:#3763

Novos tipos de pipeline de sessão/contexto foram introduzidos juntamente com APIs herdadas para migração incremental, incluindo SessionContext e BaseContextProvider.

🟡 O streaming de interpretador de código agora inclui deltas de código incrementais

PR:#3775

O interpretador de código de streaming executa agora atualizações delta do surface code no conteúdo transmitido para que as interfaces do usuário possam renderizar o código gerado progressivamente.

🟡 @tool dá suporte ao tratamento de esquema explícito

PR:#3734

As definições de ferramenta agora podem usar o tratamento de esquema explícito quando a saída de esquema inferida precisa de personalização.

python-1.0.0b260130 (30 de janeiro de 2026)

Notas de versão:python-1.0.0b260130

🟡 ChatOptions e ChatResponse/AgentResponse agora está genérico para o formato de resposta

PR:#3305

ChatOptions, ChatResponsee AgentResponse agora são tipos genéricos parametrizados pelo tipo de formato de resposta. Isso permite uma inferência de tipo melhor ao usar saídas estruturadas com 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 suporte adicionado para o SDK do Claude Agent

PR:#3509

O SDK do Python agora inclui uma BaseAgent implementação para o SDK do Claude Agent, permitindo o uso baseado em adaptador de primeira classe no Agent Framework.

python-1.0.0b260128 (28 de janeiro de 2026)

Notas de versão:python-1.0.0b260128

🔴 AIFunction renomeado para FunctionTool e @ai_function renomeado para @tool

PR:#3413

A classe e o decorador foram renomeados para clareza e consistência com a terminologia da indústria.

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)

🔴 Padrão Factory adicionado ao GroupChat e Magentic; renomeações de API

PR:#3224

Adição da fábrica de participantes e da fábrica de orquestradores para o chat em grupo. Também inclui renomeações:

• 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 renomeado para GitHub

PR:#3486

Nomes de classe e pacotes atualizados para usar a capitalização correta.

Before:

from agent_framework_github_copilot import GithubCopilotAgent

agent = GithubCopilotAgent(...)

After:

from agent_framework_github_copilot import GitHubCopilotAgent

agent = GitHubCopilotAgent(...)

python-1.0.0b260127 (27 de janeiro de 2026)

Notas de versão:python-1.0.0b260127

🟡 BaseAgent suporte adicionado para o SDK do GitHub Copilot

PR:#3404

O SDK do Python agora inclui uma BaseAgent implementação para integrações do SDK do GitHub Copilot.

python-1.0.0b260123 (23 de janeiro de 2026)

Notas de versão:python-1.0.0b260123

🔴 Tipos de conteúdo simplificados para uma única classe com construtores de método de classe

PR:#3252

Substituíram todos os tipos de conteúdo antigos (derivados de BaseContent) por uma única classe Content com métodos de classe para criar tipos específicos.

Referência de migração completa

Novos métodos adicionais (sem predecessor direto):

• Content.from_text_reasoning(...) — Para conteúdo de raciocínio/pensamento
• Content.from_hosted_vector_store(...) — Para referências do repositório de vetores
• Content.from_usage(...) — Para informações sobre uso/token
• Content.from_mcp_server_tool_call(...) / Content.from_mcp_server_tool_result(...) — Para ferramentas de servidor MCP
• Content.from_code_interpreter_tool_call(...) / Content.from_code_interpreter_tool_result(...) — Para interpretador de código
• Content.from_image_generation_tool_call(...) / Content.from_image_generation_tool_result(...) — Para geração de imagem

Verificação de tipo

Em vez de isinstance() verificar, use a type propriedade:

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)

Exemplo básico

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

🔴 Tipos de anotação simplificados para Annotation e TextSpanRegion TypedDicts

PR:#3252

Tipos de anotação baseados em classe substituídos por definições mais TypedDict simples.

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 Erros de validação agora visíveis para os usuários

PR:#3274

ChatResponse.value e AgentResponse.value agora levantam ValidationError quando a validação do esquema falha, em vez de apenas retornar None de forma silenciosa.

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 execução lógica simplificada; Correções para o cliente MCP e Anthropic

PR:#3322

A assinatura e o run comportamento do método em AG-UI foram simplificados.

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
)

🟡 O cliente antropático agora dá suporte a saídas response_format estruturadas

PR:#3301

Agora você pode usar a análise de saída estruturada com clientes da Anthropic por meio do response_format, assim como com clientes da OpenAI e da Azure.

🟡 Configuração de IA do Azure expandida (reasoning, rai_config)

PRs:#3403, #3265

O suporte à IA do Azure foi expandido com suporte à configuração de raciocínio e rai_config durante a criação do agente.

python-1.0.0b260116 (16 de janeiro de 2026)

Notas de versão:python-1.0.0b260116

🔴 create_agent renomeado para as_agent

PR:#3249

Método renomeado para maior clareza sobre sua finalidade.

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 renomeado para executor_id

PR:#3166

Propriedade renomeada para consistência de uma 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 oferece suporte à continuidade de sessão gerenciada por serviço

PR:#3136

AG-UI agora preserva a identidade da conversa gerenciada pelo serviço (por exemplo, sessões/encadeamentos gerenciados pelo Foundry) para manter a continuidade em múltiplos turnos.

python-1.0.0b260114 (14 de janeiro de 2026)

Notas de versão:python-1.0.0b260114

🔴 Orquestrações refatoradas

PR:#3023

Ampla refatoração e simplificação de orquestrações em fluxos de trabalho do Agent Framework:

• Chat em Grupo: Dividir o executor do orquestrador em um agente dedicado e em um baseado em função (BaseGroupChatOrchestrator, GroupChatOrchestrator, AgentBasedGroupChatOrchestrator). Simplificado para a topologia estrela com o modelo de transmissão.
• Transferência: suporte a camada única, coordenador e executor personalizado removido. Movido para o modelo de transmissão com HandoffAgentExecutor.
• Sequencial & Concorrente: mecanismo simplificado de informações de solicitação que conta com sub-fluxos de trabalho por meio AgentApprovalExecutor e 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]
)

🔴 Opções introduzidas como TypedDict e Generic

PR:#3140

As opções agora são digitadas usando TypedDict para melhor segurança de tipo e preenchimento automático do IDE.

📖 Para obter instruções completas de migração, consulte o Guia de Opções Tipadas.

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_id": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 1000,
    },
)

🔴 display_name Removido; context_provider para o singular; middleware deve ser uma lista

PR:#3139

• display_name parâmetro removido dos agentes
• context_providers (plural, lista de aceitação) alterada para context_provider (singular, apenas 1 permitido)
• middleware agora requer uma lista (não aceita mais uma única instância)
• AggregateContextProvider removido do código (use a implementação de exemplo, se necessário)

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* renomeado para AgentResponse*

PR:#3207

AgentRunResponse e AgentRunResponseUpdate foram renomeado para AgentResponse e AgentResponseUpdate.

Before:

from agent_framework import AgentRunResponse, AgentRunResponseUpdate

After:

from agent_framework import AgentResponse, AgentResponseUpdate

🟡 Adicionado suporte para tempo de execução de fluxo de trabalho declarativo em fluxos de trabalho definidos por YAML

PR:#2815

Um runtime baseado em grafo foi adicionado para executar fluxos de trabalho declarativos do YAML, habilitando a orquestração de vários agentes sem código de runtime personalizado.

🟡 Melhorias de carregamento/confiabilidade do MCP

PR:#3154

As integrações do MCP ganharam comportamento aperfeiçoado em caso de perda de conexão, suporte à paginação ao carregar e opções de controle de representação.

🟡 A Foundry A2ATool agora dá suporte a conexões sem uma URL de destino

PR:#3127

A2ATool agora pode resolver conexões A2A com suporte do Foundry por meio de metadados de conexão de projeto mesmo quando uma URL de destino direto não está configurada.

python-1.0.0b260107 (7 de janeiro de 2026)

Notas de versão:python-1.0.0b260107

Nenhuma alteração significativa nesta versão.

python-1.0.0b260106 (6 de janeiro de 2026)

Notas de versão:python-1.0.0b260106

Nenhuma alteração significativa nesta versão.

Tabela de resumo

Próximas etapas