Guia de Mudanças Significativas em Python 2026

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

• 🔴 Interrupção — Requer alterações no código para atualização
• 🟡 Melhoria — Nova capacidade ou melhoria; O código existente continua a funcionar

Este documento será removido assim que chegarmos à versão estável 1.0.0, por isso, por favor, consulte-o ao atualizar entre versões em 2026 para garantir que não perde alterações importantes. Para obter instruções detalhadas de atualização sobre tópicos específicos (por exemplo, migração de opções), consulte os guias de atualização vinculados ou os pull requests (PRs) vinculados.

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. Foram atualizados todos os outros pacotes para 1.0.0b260219.

🔴 Tratamento unificado de credenciais Azure em todos os pacotes

PR:#4088

Os parâmetros/helpers ad_token, ad_token_provider e get_entra_auth_token foram substituídos por um parâmetro unificado credential em todos os pacotes Python relacionados com Azure. A nova abordagem utiliza azure.identity.get_bearer_token_provider para cache e atualização automática de tokens.

Classes afetadas:AzureOpenAIChatClient, AzureOpenAIResponsesClient, AzureOpenAIAssistantsClient, AzureAIClientAzureAIAgentClient, AzureAIProjectAgentProvider, AzureAIAgentsProvider, , AzureAISearchContextProvider, 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(),
    ...
)

O credential parâmetro aceita TokenCredential, AsyncTokenCredential, ou um fornecedor de token chamável. A cache e a atualização dos tokens são geridas automaticamente.

🔴 Hierarquia de exceções em Python redesenhada

PR:#4082

A família plana ServiceException foi substituída por ramos de exceção com âmbito de domínio sob uma única AgentFrameworkException raiz. Isto dá aos chamadores alvos precisos except e uma 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, ServiceResponseExceptionServiceContentFilterException, ServiceInvalidAuthError, ServiceInvalidExecutionSettingsError, ServiceInvalidRequestError, ServiceInvalidResponseError, , AgentExecutionException, . AgentInvocationErrorAgentInitializationErrorAgentSessionExceptionChatClientInitializationErrorCheckpointDecodingError

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 fornecedor definido por source_id

PR:#3995

Os hooks do fornecedor agora recebem um dicionário de estado específico do fornecedor (state.setdefault(provider.source_id, {})) em vez do estado completo da sessão. Isto significa que implementações de fornecedores que anteriormente acediam ao estado aninhado via state[self.source_id]["key"] devem agora aceder diretamente a state["key"].

Além disso, o InMemoryHistoryProvider padrão source_id mudou 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 da digitação de mensagens de chat/agente (run vs get_response)

PR:#3920

As implementações de chat-cliente get_response recebem agora consistentemente Sequence[Message]. agent.run(...) mantém-se flexível (str, Content, Message, ou sequências destes) e normaliza as entradas antes de ligar para 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 ferramentas baseados em esquemas já não dependem do comportamento genérico anterior FunctionTool[Any] . Use FunctionTool diretamente e forneça um BaseModel pydântico ou esquemas explícitos onde necessário (por exemplo, com @tool(schema=...)).

Before:

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

After:

placeholder: FunctionTool = FunctionTool(...)

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

Pull Requests:#3843, #4032

A classe baseada em pydantic-settings e AFBaseSettings foi substituída por um sistema de definições leve e baseado em funções utilizando TypedDict e load_settings(). A pydantic-settings dependência foi completamente removida.

Todas as classes de definições (por exemplo, OpenAISettings, AzureOpenAISettings, AnthropicSettings) são agora TypedDict definições, e os valores das definições são acedidos através da sintaxe do dicionário em vez de acesso a atributos.

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

🟡 Correção do modelo de raciocínio, fluxo de trabalho de transferência e serialização do histórico

PR:#4083

Corrige múltiplas falhas ao utilizar modelos de raciocínio (por exemplo, gpt-5-mini, gpt-5.2) em fluxos de trabalho multi-agente. Os itens de raciocínio da API Respostas são agora corretamente serializados e só incluídos no histórico quando a function_call também está presente, prevenindo erros na API. O conteúdo de raciocínio encriptado/oculto é agora emitido corretamente, e o summary formato do campo é corrigido. service_session_id também é eliminado na transferência para evitar vazamento de estado entre agentes.

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

PR:#3953

O Amazon Bedrock está agora incluído nos agent-framework-core[all] extras e está disponível através da agent_framework.amazon superfície de importação preguiçosa. O comportamento de escolha de ferramenta também foi corrigido: os valores de escolha de ferramenta não definidos permanecem agora desdefinidos, de modo que os fornecedores usam os seus valores predefinidos de serviço, enquanto valores explicitamente definidos são preservados.

from agent_framework.amazon import BedrockClient

🟡 AzureAIClient alerta sobre substituições de runtime não suportadas

PR:#3919

AzureAIClient agora regista um aviso quando o tempo tools de execução ou structured_output difere da configuração do agente no momento de criação. O Azure AI Agent Service não suporta alterações de ferramentas de runtime ou de formato de resposta — use AzureOpenAIResponsesClient em vez disso se precisar de overrides dinâmicos.

🟡 workflow.as_agent() Agora define o histórico local quando os fornecedores não estão definidos

PR:#3918

Quando workflow.as_agent() é criado sem context_providers, agora adiciona InMemoryHistoryProvider("memory") por defeito. Se forem explicitamente fornecidos fornecedores de contexto, essa lista mantém-se inalterada.

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

🟡 Contexto de traço OpenTelemetry propagado para requisições MCP

PR:#3780

Quando o OpenTelemetry é instalado, o contexto de rastreamento (por exemplo, W3C traceparent) é injetado automaticamente nos pedidos MCP via params._meta. Isto permite o rastreio distribuído de ponta a ponta entre chamadas de agente → servidor MCP. Não são necessárias alterações de código — este é um comportamento aditivo que se ativa quando existe um contexto de expansão válido.

🟡 Suporte duradouro de workflow para Azure Functions

PR:#3630

O pacote agent-framework-azurefunctions agora suporta a execução de grafos Workflow no Azure Durable Functions. Passe um workflow parâmetro para AgentFunctionApp para automaticamente registrar entidades de agentes, funções de atividade e endpoints 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

Suporta padrões de fan-out/fan-in, shared state e human-in-the-loop com timeout configurável e rejeição automática ao expirar.

python-1.0.0b260212 (12 de fevereiro de 2026)

Notas de Lançamento:python-1.0.0b260212

🔴 Hosted*ToolAs classes foram substituídas por métodos cliente get_*_tool()

PR:#3634

As classes de ferramentas alojadas foram removidas em favor de métodos de fábrica com âmbito cliente. Isto torna a disponibilidade de ferramentas explícita por fornecedor.

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 de fornecedor de sessão e de contexto finalizado (AgentSession, context_providers)

PR:#3850

A sessão Python e a migração do fornecedor de contexto foram concluídas. AgentThread e os antigos tipos de fornecedor de contexto 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)

🔴 O comportamento de armazenamento e o modelo de checkpoint foram refatorados

PR:#3744

Os internos dos checkpoints foram redesenhados, o que afeta a compatibilidade persistente dos checkpoints e as implementações de armazenamento personalizado:

• WorkflowCheckpoint Agora armazena objetos vivos (a serialização ocorre no armazenamento por checkpoint)
• FileCheckpointStorage Agora usa a serialização pickle do Python
• workflow_id foi removido e previous_checkpoint_id adicionado
• Os ganchos de checkpoint obsoletos foram removidos

Se persistir checkpoints entre versões, deve regenerar ou migrar os artefatos de checkpoint existentes antes de retomar os fluxos de trabalho.

🟡 AzureOpenAIResponsesClient suporta endpoints do projeto Microsoft Foundry

PR:#3814

Agora pode criar AzureOpenAIResponsesClient com um endpoint de projeto Foundry ou AIProjectClient, e não apenas com 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 já não aceita context

PR:#3829

A continuação do middleware agora não aceita discussões. Se o seu middleware ainda chama 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 Lançamento:python-1.0.0b260210

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

PR:#3781

register_executor() e register_agent() foram removidos de WorkflowBuilder. Todos os métodos builder (add_edge, add_fan_out_edges, add_fan_in_edges, add_chain, add_switch_case_edge_group, add_multi_selection_edge_group, start_executor) já não aceitam nomes de string — exigem instâncias de executor ou agente diretamente.

Para isolamento de estados, envolva a instanciação do executor/agente e a construção do workflow 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 necessitam de estado isolado por invocação, envolva a construção num 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 para Agent, ChatMessage renomeado para Message

PR:#3747

Os tipos Python principais foram simplificados ao remover o prefixo redundante Chat . Não são fornecidos alias de retrocompatibilidade.

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 APIs em diferentes modelos de resposta/mensagem

PR:#3647

Esta versão inclui uma limpeza ampla e fragmentada da tipagem de mensagens/respostas e das APIs auxiliares.

• Role e FinishReason são agora NewType envoltórios de str com RoleLiteral/FinishReasonLiteral para valores conhecidos. Trata-os como strings (sem uso de .value).
• Message a construção é padronizada em Message(role, contents=[...]); as cadeias em contents são convertidas automaticamente para conteúdo de texto.
• ChatResponse e AgentResponse os construtores agora centram-se em messages= (único Message ou sequência); o uso de construtores legados text= foi removido das respostas.
• ChatResponseUpdate e AgentResponseUpdate já não aceitam text=; usar contents=[Content.from_text(...)].
• Os nomes dos ajudantes de combinação de atualizações foram simplificados.
• try_parse_value foi removido de ChatResponse e AgentResponse.

Renomeação do método Helper

Atualização da construção de resposta e atualização

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_response e ResponseStream

PR:#3379

As APIs Python foram consolidadas em torno de agent.run(...) e client.get_response(...), com o 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ção de tipos de contexto/protocolo core

Pedidos de Pull:#3714, #3717

Atualize as importações e as anotações de tipo em conformidade.

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

PR:#3735

As assinaturas do middleware devem agora usar 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 segue agora um estilo de nomenclatura TypeVar consistente onde é usado o sufixo T .

Before:

TMessage = TypeVar("TMessage")

After:

MessageT = TypeVar("MessageT")

Se mantiver envoltórios personalizados em torno dos genéricos do framework, alinhe os nomes locais do TypeVar com a nova convenção para reduzir a movimentação de anotações.

🔴 Saída do fluxo de trabalho como agente e alterações em streaming

PR:#3649

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

🔴 Os métodos de construtor fluente passaram para parâmetros de construtor

PR:#3693

Métodos fluentes de configuração única em 6 construtores (WorkflowBuilder, SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, MagenticBuilder, ) HandoffBuilderforam migrados para parâmetros de construtor. Métodos fluentes que eram o único caminho de configuração para um cenário são removidos em favor de argumentos de construtor.

WorkflowBuilder

set_start_executor(), with_checkpointing(), e with_output_from() são removidos. Use antes 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(), with_checkpointing(), e with_intermediate_outputs() são removidos. Use antes 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(), with_checkpointing() e with_intermediate_outputs() são removidos. Use antes 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(), with_checkpointing(), e with_intermediate_outputs() são removidos. Use antes 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. Use antes 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 na validação

• WorkflowBuilder agora requer start_executor como argumento construtor (anteriormente definido via método fluente)
• SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, e MagenticBuilder agora requerem ou participants ou participant_factories em tempo de construção — não passar nenhum deles aciona ValueError

🔴 Eventos de fluxo de trabalho unificados num único WorkflowEvent com type discriminador

PR:#3690

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

Classes de evento removidas

As seguintes subclasses de evento exportadas já não existem:

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

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

Anotações de tipos

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; Utilização 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 renomeadas para State; as APIs de estado do fluxo de trabalho são síncronas

PR:#3667

As APIs de estado já não requerem await, e a nomenclatura foi padronizada:

🔴 Os construtores de orquestração foram movidos para agent_framework.orchestrations

PR:#3685

Os construtores de orquestração estão agora num espaço de nomes dedicado para paquetes.

Before:

from agent_framework import SequentialBuilder, GroupChatBuilder

After:

from agent_framework.orchestrations import SequentialBuilder, GroupChatBuilder

🟡 Respostas em segundo plano de longa duração e tokens de continuação

PR:#3808

As respostas em segundo plano são agora suportadas para execuções de agentes 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})

🟡 Tipos de pré-visualização do provedor de sessão/contexto adicionados lado a lado

PR:#3763

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

🟡 O streaming de interpretação de código inclui agora deltas incrementais no código

PR:#3775

O interpretador de código em streaming executa agora atualizações delta de código de superfície no conteúdo transmitido, permitindo que as interfaces de utilizador possam renderizar o código gerado progressivamente.

🟡 @tool suporta o tratamento explícito de esquemas

PR:#3734

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

python-1.0.0b260130 (30 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260130

🟡 ChatOptions e ChatResponse/AgentResponse agora suportam formatos genéricos de resposta

PR:#3305

ChatOptions, ChatResponse, e AgentResponse são agora tipos genéricos parametrizados pelo tipo de formato de resposta. Isto permite uma melhor inferência de tipos 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 Claude Agent SDK

PR:#3509

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

python-1.0.0b260128 (28 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260128

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

PR:#3413

A turma e o decorador foram renomeados para maior clareza e consistência com a terminologia do setor.

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 de fábrica adicionado ao GroupChat e à Magentic; Renomeações de APIs

PR:#3224

Adicionei a fábrica de participantes e a fábrica de orquestradores ao chat em grupo. Inclui também 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

Os nomes das classes e pacotes foram 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 Lançamento:python-1.0.0b260127

🟡 BaseAgent Adicionado suporte para o GitHub Copilot SDK

PR:#3404

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

python-1.0.0b260123 (23 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260123

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

PR:#3252

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

Referência Completa de Migração

Métodos adicionais novos (sem antecessor direto):

• Content.from_text_reasoning(...) — Para conteúdo de raciocínio/pensamento
• Content.from_hosted_vector_store(...) — Para referências de armazenamento vetorial
• Content.from_usage(...) — Para informações sobre o 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 imagens

Verificação de Tipos

Em vez de isinstance() verificações, 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

Substituíram os tipos de anotação baseados em classes 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 utilizadores

PR:#3274

ChatResponse.value e AgentResponse.value agora elevam ValidationError quando a validação do esquema falhar, em vez de silenciosamente devolver 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 lógica de execução simplificada; Correções para clientes MCP e Anthropic

PR:#3322

A run assinatura e o 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 Anthropic agora suporta response_format saídas estruturadas

PR:#3301

Agora pode usar análise estruturada de saída com clientes Anthropic via response_format, semelhante aos clientes OpenAI e Azure.

🟡 Configuração da Azure AI expandida (reasoning, rai_config)

Pedidos de Pull:#3403, #3265

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

python-1.0.0b260116 (16 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260116

🔴 create_agent renomeado para as_agent

PR:#3249

Método renomeado para maior clareza sobre o seu propósito.

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 da 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 suporta continuidade de sessão gerida por serviços

PR:#3136

AG-UI agora preserva a identidade de conversa gerida por serviços (por exemplo, sessões/threads geridos pela Foundry) para manter a continuidade de múltiplas interações.

python-1.0.0b260114 (14 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260114

🔴 Orquestrações refatoradas

PR:#3023

Refatoração e simplificação extensivas das orquestrações nos workflows do Agent Framework:

• Chat de Grupo: Dividir o executor do orquestrador em dedicado baseado em agentes e baseado em funções (BaseGroupChatOrchestrator, GroupChatOrchestrator, AgentBasedGroupChatOrchestrator). Simplificado para topologia em estrela com modelo de difusão.
• Handoff: Removido o suporte para nível único, coordenador e executor personalizado. Mudei para o modelo de transmissão com HandoffAgentExecutor.
• Sequencial & Concorrente: Mecanismo simplificado de informação de pedidos para depender de subfluxos de trabalho via 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 tipificadas usando TypedDict para melhor segurança de tipos e autocompletar no IDE.

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

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 ao singular; middleware deve ser uma lista

PR:#3139

• display_name parâmetro removido dos agentes
• context_providers (plural, lista de aceitação) alterado para context_provider (singular, apenas 1 permitido)
• middleware Agora requer uma lista (já não aceita uma única instância)
• AggregateContextProvider removido do código (use exemplo de implementação 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 renomeados para AgentResponse e AgentResponseUpdate.

Before:

from agent_framework import AgentRunResponse, AgentRunResponseUpdate

After:

from agent_framework import AgentResponse, AgentResponseUpdate

🟡 Tempo de execução declarativo do fluxo de trabalho adicionado para fluxos de trabalho definidos por YAML

PR:#2815

Foi adicionado um runtime baseado em grafos para executar fluxos de trabalho declarativos YAML, permitindo orquestração multi-agente sem código de execução personalizado.

🟡 Melhorias de carga/fiabilidade do MCP

PR:#3154

As integrações MCP melhoraram o comportamento de perda de conexão, suporte para paginação durante o carregamento e opções de controle de exibição.

🟡 A Foundry A2ATool agora suporta ligações sem URL de destino

PR:#3127

A2ATool agora pode resolver conexões A2A suportadas pela Foundry utilizando metadados de conexão do projeto, mesmo quando um URL-alvo direto não está configurado.

python-1.0.0b260107 (7 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260107

Não houve alterações significativas nesta versão.

python-1.0.0b260106 (6 de janeiro de 2026)

Notas de Lançamento:python-1.0.0b260106

Não houve alterações significativas nesta versão.

Quadro de resumo

Próximos passos