Guida alle modifiche significative di Python 2026

Questo documento elenca tutte le modifiche significative nelle versioni di Python dall'inizio del 2026, incluse le modifiche di rilievo e importanti miglioramenti che possono influire sul codice. Ogni modifica viene contrassegnata come:

• 🔴 Interruzione : richiede modifiche al codice per l'aggiornamento
• 🟡 Miglioramento : nuova funzionalità o miglioramento; il codice esistente continua a funzionare

Questo documento tiene traccia delle modifiche significative di Python in tutte le release del 2026, quindi consultatelo quando passate da una versione all'altra per non perdere nessuna modifica importante. Per istruzioni dettagliate sull'aggiornamento su argomenti specifici (ad esempio, la migrazione delle opzioni), consultare le guide all'aggiornamento collegate o le richieste pull collegate.

Non rilasciata

🔴 Il lab viene installato separatamente e Foundry supporta Projects 2.6

PR:#8188

agent-framework e agent-framework-core[all] non installa più il pacchetto sperimentale agent-framework-lab . Installare ogni modulo Lab in modo esplicito.

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

Lab risolve ora le dipendenze sperimentali indipendentemente dai pacchetti di Agent Framework rilasciati. Il agent-framework-foundry pacchetto supporta azure-ai-projects>=2.2.0,<2.7.0 e usa una versione compatibile con agent-framework-openai OpenAI 3. Questa separazione consente alle applicazioni Foundry di usare Azure AI Projects dalla versione 2.4 alla 2.6 senza sovrascrivere i vincoli delle dipendenze di Lab compatibili con OpenAI 2.

🔴 Gli hook dei file dello spazio di lavoro di GitHub Copilot richiedono l'attivazione esplicita

PR:#7517

GitHubCopilotAgent non carica più .github/hooks/ dalla directory di lavoro per impostazione predefinita. Abilita gli hook solo per una directory di lavoro di cui ti fidi.

from agent_framework.github import GitHubCopilotAgent, GitHubCopilotOptions

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

Gli hook sui file eseguono comandi sull'host e non sono soggetti a on_permission_request o ad altri callback di approvazione degli strumenti. Quando sono presenti hook e si omette enable_file_hooks, l'agente lo imposta automaticamente su False e registra un avviso una volta sola. L'impostazione esplicita di enable_file_hooks=False disabilita gli hook senza tale avviso. Per indicazioni sulla configurazione, vedere Controllare gli hook dei file dell'area di lavoro.

🔴 L'archiviazione basata su file usa la normalizzazione del percorso condiviso

PR:#8123

Le sessioni basate su file, la memoria e l'archiviazione delle attività da svolgere ora ricavano i nomi delle cartelle tramite un'unica mappatura condivisa delle chiavi di archiviazione. Gli ID e gli ambiti che contengono lettere maiuscole, separatori di percorso, caratteri Unicode o altri caratteri non sicuri potrebbero risolversi in una posizione diversa dopo l'aggiornamento.

I dati esistenti non vengono spostati automaticamente. Se è necessario conservarli, migrare i vecchi file o le directory nel nuovo percorso derivato. Considera FileMemoryProvider.scope come una chiave dello spazio dei nomi opaco, non come percorso annidato. Ad esempio, tenants/alice corrisponde a una cartella codificata.

TodoFileStore usa il mapping condiviso per gli ID proprietario, ma rifiuta gli ID sessione che contengono / o \. Canonizzare questi ID di sessione prima di eseguire la migrazione dei dati todo.

🔴 SecretString non eredita più da str

PR:#8127

SecretString maschera ora la conversione, la formattazione e la concatenazione delle stringhe. Le API che richiedono un effettivo str, inclusa la serializzazione JSON, non accettano più il wrapper in modo implicito. Estrai esplicitamente il valore nel punto di confine che richiede la credenziale:

Before:

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

After:

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

Il valore estratto è una stringa normale e non è più protetto dalla registrazione o dalla formattazione accidentale.

🔴 Gli input del middleware richiedono una sequenza e Agent Hooks si installa separatamente

Richiesta pull:#7918

I costruttori degli agenti, gli input del middleware per ogni esecuzione e create_harness_agent() non accettano più un unico valore per il middleware. Passa il middleware sotto forma di sequenza. Un pacchetto Agent Hooks continua a essere supportato come uno degli elementi di quella sequenza.

L'elemento agent-framework-core[agent-hooks] aggiuntivo viene rimosso. Installare agent-hooks-sdk direttamente.

Before:

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

After:

pip install agent-hooks-sdk

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

python-1.16.0 (27 agosto 2026)

Note sulla versione:python-1.16.0

🟡 Configurazione del provider OpenTelemetry a livello di codice

Richiesta pull:#7703

configure_otel_providers() accetta ora i metadati del servizio, gli attributi delle risorse e le opzioni di esportazione OTLP direttamente. I metadati espliciti del servizio hanno la precedenza sui valori dell'ambiente. Gli attributi delle risorse hanno la precedenza sugli attributi dell'ambiente. Le variabili di intestazione e gli endpoint OTLP specifici del segnale rimangono più specifici delle impostazioni programmatiche di base.

python-1.15.0 (21 agosto 2026)

Note sulla versione:python-1.15.0

🔴 Convenzioni semantiche consolidate di OpenTelemetry GenAI

PR:#7673

Agent Framework ora usa per impostazione predefinita gli attributi span sperimentali GenAI più recenti, incluso gen_ai.provider.name invece di gen_ai.system. Impostare OTEL_SEMCONV_STABILITY_OPT_IN su un valore che omette il token con distinzione tra maiuscole e minuscole gen_ai_latest_experimental per selezionare gli attributi span v1.36. Gli eventi di messaggio e di scelta della versione v1.36 sono selezionati indipendentemente, rimangono abilitati per impostazione predefinita quando vengono acquisiti dati sensibili e continuano a utilizzare gen_ai.system. Imposta ENABLE_MESSAGE_EVENTS=false per disattivarli.

🟡 Il middleware di funzione può interrompersi con MiddlewareFailure

PR:#7562

Il middleware di funzione può generare MiddlewareFailure quando l'esecuzione deve interrompersi, anziché trasformarsi in un errore dello strumento recuperabile. Il ciclo di invocazione della funzione propaga questa eccezione al chiamante e annulla le altre chiamate allo strumento parallele in corso. Non intercettare questa eccezione nel middleware perché così facendo l'esecuzione continua.

Il middleware dell'agente e della chat propaga già eccezioni ordinarie. Usare MiddlewareFailure quando il middleware della funzione richiede in modo specifico un comportamento irreversibile e chiuso.

python-1.14.0 (14 agosto 2026)

Note sulla versione:python-1.14.0

🟡 Il ragionamento crittografato è facoltativo per la chat di Foundry

PR:#7536

FoundryChatClient non richiede più reasoning.encrypted_content per impostazione predefinita. L'impostazione predefinita evita errori nei modelli non supportati. Per le distribuzioni idonee, fornire il consenso esplicito con default_options={"include": ["reasoning.encrypted_content"]}.

🔴 [Beta] Lo stato di Foundry Hosted Agent viene spostato in Foundry State Store

PR:#7533

La pull request #7533 rimuove FoundrySessionStore(path) dal pacchetto beta agent-framework-foundry-hosting. L'host ora utilizza FoundryAgentSessionStore e le impostazioni predefinite basate su Foundry State Store per le sessioni dell'agente, i checkpoint del flusso di lavoro e le approvazioni delle funzioni.

• Rimuovi le importazioni e la creazione di FoundrySessionStore.
• Consenti a ResponsesHostServer di creare i provider predefiniti. Per l'archiviazione personalizzata, specificare agent_session_store_provider, checkpoint_store_provider, o function_approval_store_provider.
• Lo stato esistente basato su file non viene migrato automaticamente.

Per il modello di provider corrente, vedere Rendere persistenti lo stato e gestire conversazioni a esecuzione prolungata.

🔴 Creare definizioni di flusso di lavoro funzionali prima di eseguirle

Richiesta pull:#7521

PR #7521 modifica @workflow per restituire un FunctionalWorkflowDefinition senza stato. Chiama .build() per creare un FunctionalWorkflow con stato. Crea il flusso di lavoro prima di chiamare .run() o .as_agent(), e passa l'archiviazione del checkpoint a .build().

Before:

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

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

After:

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

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

Creare un'istanza separata del workflow per ogni chiamante logico o sessione, in modo che gli stati di esecuzione e riesecuzione rimangano isolati.

🟡 Agent Hooks aggiunge un contratto di intercettazione chiuso non riuscita

Richiesta pull:#7515

Agent Framework aggiunge il supporto sperimentale per il contratto AGENT-HOOKS-0.1 tramite create_agent_hooks_middleware() e create_agent_hooks_middleware_from_emitter(). Il pacchetto middleware copre i punti di intercettazione di agenti, modelli e funzioni con applicazione del verdetto con blocco in caso di errore, scrittura di ritorno delle trasformazioni, streaming con buffering e persistenza subordinata al verdetto.

Per il pacchetto corrente e il contratto middleware, installare agent-hooks-sdk direttamente e passare il bundle restituito in una sequenza, ad esempio middleware=[hooks]. Per informazioni dettagliate, vedere Hook dell'agente.

python-1.8.0 (4 giugno 2026)

Note sulla versione:python-1.8.0

🔴 github-copilot-sdk aggiornato alla V1.0.0 con modifiche che causano un'interruzione dell'API

PR:#6292

La richiesta pull #6292 aggiorna agent-framework-github-copilot da github-copilot-sdk 1.0.0b2 alla release stabile 1.0.0, adeguandosi a tutte le modifiche che causano un'interruzione dell'API introdotte nella versione di disponibilità generale.

• SubprocessConfig rimosso: usare RuntimeConnection.for_stdio(path=...) e argomenti con nome in CopilotClient (connection, log_level, base_directory).
• Percorsi di importazione spostati : copilot.generated.session_events → copilot.session_events.
• Impostazioni rinominate : copilot_home → base_directory; la variabile di ambiente è ora GITHUB_COPILOT_BASE_DIRECTORY (era GITHUB_COPILOT_COPILOT_HOME).
• Gestori di autorizzazioni : usare tipi decisionali concreti anziché PermissionRequestResult(kind=...). Il modello PermissionHandler.approve_all predefinito sostituisce i modelli di approvazione manuale.
• Gestore di negazione predefinito : ora restituisce PermissionDecisionUserNotAvailable() (comportamento di fallback SDK corrispondente).
• Tipo di gestore di autorizzazioni : supporta ora sia i callback sincroni che i callback asincroni (Callable[..., PermissionRequestResult | Awaitable[PermissionRequestResult]]).

Before:

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

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

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

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

After:

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

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

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

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

🟡 Esposizione progressiva degli strumenti tramite FunctionInvocationContext

PR:#6233

Aggiunge il supporto per esporre progressivamente gli strumenti durante un'esecuzione tramite FunctionInvocationContext. Gli strumenti possono ora essere aggiunti o rimossi dinamicamente in base ai risultati precedenti dello strumento all'interno della stessa esecuzione dell'agente.

Per la documentazione completa, inclusi modelli, avvertenze ed esempi di ordinamento degli strumenti, vedere Controllo della disponibilità degli strumenti.

🟡 Individuazione delle competenze basata su MCP (McpSkillsSource)

PR:#6169

Aggiunge McpSkillsSource a agent-framework-core, abilitando l'individuazione delle competenze e il caricamento tramite server MCP.

🟡 Supporto nativo per l'output strutturato tramite l'API Converse di Bedrock

Richiesta pull:#6052

agent-framework-bedrock implementa ora il supporto dell'output strutturato nativo tramite l'API AWS Bedrock Converse, consentendo response_format di usare i modelli Bedrock.

🟡 Integrazione di Foundry Adaptive Evals (generazione di rubriche)

Richiesta pull:#6101

Aggiunge l'integrazione di Foundry Adaptive Evals a agent-framework-foundry per la generazione automatica di rubriche nei flussi di lavoro di valutazione.

🟡 Pacchetto client di incorporamento di intelligenza artificiale Mistral

PR:#5480

Nuovo pacchetto agent-framework-mistral che include un client di embedding Mistral AI.

🟡 agent-framework-declarative alzato di livello per il rilascio del candidato

Richiesta pull:#6256

Il pacchetto agent-framework-declarative viene promosso dalla fase beta alla fase di release candidate.

python-1.7.0 (28 maggio 2026)

Note sulla versione:python-1.7.0

🔴 Dichiarativo: azioni Python-only rimosse e tipi di alias rinominati in nomi canonici C#

Richiesta pull:#6126

PR #6126 rimuove le azioni dichiarative esclusive di Python e rinomina i tipi di alias in modo che corrispondano ai nomi canonici di C# per garantire coerenza tra i vari linguaggi.

• Vengono rimossi i tipi di azione dichiarativi esclusivi di Python che non avevano un equivalente in C#.
• I tipi di alias delle azioni sono ora allineati alle convenzioni di denominazione di C#; aggiornate di conseguenza i file YAML/JSON dichiarativi esistenti.

🟡 HarnessAgent e provider di infrastruttura di agente in background

Richieste pull:#6041, #6069

Aggiunge HarnessAgent a agent-framework-core, abilitando i modelli di agente supportati dall'infrastruttura per l'elaborazione in background.

🟡 A2AAgentSession con ID attività a cui si fa riferimento e supporto richiesto per l'input

PR:#5980

Aggiunge A2AAgentSession a agent-framework-a2a e agent-framework-core, supportando gli ID attività a cui si fa riferimento e il flusso richiesto dall'input per le interazioni con protocollo A2A.

🟡 API sperimentali per la conversione e la distribuzione dell'agente prompt

PR:#5959

Aggiunge API sperimentali a agent-framework-foundry per convertire le definizioni di prompt in agenti e distribuirle a livello di codice.

python-1.6.0 (21 maggio 2026)

Note sulla versione:python-1.6.0

🔴 Strumentazione abilitata per impostazione predefinita

PR:#5865

PR #5865 abilita la strumentazione OpenTelemetry per impostazione predefinita in agent-framework-core e agent-framework-foundry.

• Le esecuzioni dell'agente ora generano automaticamente intervalli di telemetria senza consenso esplicito.
• Se la strumentazione è stata disabilitata in precedenza o si dispone di pipeline di telemetria personalizzate, verificare che il comportamento predefinito non sia in conflitto.
• Per disabilitare, specificare enable_instrumentation=False se applicabile.

Before:

from agent_framework import Agent
from agent_framework.observability import configure_otel_providers

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

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

After:

from agent_framework import Agent

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

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

🟡 Strumento shell con supporto per l'esecuzione locale e Docker

Richiesta pull:#5664

Aggiunge uno strumento della shell predefinito a agent-framework-core che supporta sia l'esecuzione locale che l'esecuzione sandbox basata su Docker.

🟡 Nuovo agent-framework-monty pacchetto del provider CodeAct

Richiesta pull:#5915

Introduce il agent-framework-monty pacchetto per le integrazioni CodeAct supportate da Monty (fase alfa).

python-1.4.0 (14 maggio 2026)

Note sulla versione:python-1.4.0

🔴 [API sperimentale delle competenze] Allineare l'individuazione della cartella delle competenze del file alla specifica di agentskills.io

Richiesta pull:#5807

La PR #5807 aggiorna l'API sperimentale delle competenze per allineare il rilevamento basato su file delle cartelle delle competenze alla specifica agentskills.io.

• La logica di risoluzione delle cartelle delle skill è cambiata; aggiorna le strutture di directory delle skill personalizzate se utilizzi l'API sperimentale delle skill.

🔴 [API competenze sperimentali] Estrarre i metadati delle specifiche di competenza in SkillFrontmatter

PR:#5775

La richiesta pull #5775 sposta i metadati della specifica della competenza in una classe di dati SkillFrontmatter dedicata.

• Se si accede direttamente ai campi dei metadati delle competenze, aggiornate i riferimenti in modo che utilizzino gli attributi SkillFrontmatter.

🔴 DevUI: rafforzare i controlli di accesso predefiniti e il comportamento CORS

Richiesta pull:#5740

La PR #5740 rende più rigorose la configurazione predefinita del controllo degli accessi e la configurazione CORS per agent-framework-devui.

• Le origini CORS predefinite sono ora più restrittive.
• Se la configurazione di DevUI si basa sull'accesso cross-origin da domini personalizzati, configura esplicitamente le origini consentite.

🔴 A2A: Eseguire la migrazione a a2a-sdk v1.0

PR:#5752

PR #5752 migra agent-framework-a2a a a2a-sdk v1.0.

• I tipi di protocollo A2A e le API di trasporto seguono le convenzioni a2a-sdk 1.0.
• Aggiornare qualsiasi codice che interagisce direttamente con i tipi di protocollo A2A.

🟡 AG-UI: canale di visualizzazione dei risultati del tool e promozione della release candidate

Richieste pull:#5762, #5844

Aggiunge a agent-framework-ag-ui il canale di visualizzazione dei risultati dello strumento e promuove il pacchetto allo stadio di release candidate.

python-1.3.0 (7 maggio 2026)

Note sulla versione:python-1.3.0

🔴 [API sperimentale delle competenze] Ristrutturare le competenze degli agenti in un'architettura con più origini

PR:#5584

PR #5584 ristruttura l'API sperimentale delle skill per supportare il caricamento delle skill da più origini.

• La registrazione delle competenze e la logica di individuazione sono state modificate per la funzionalità di competenze sperimentali.
• Se si utilizza l'API sperimentale delle competenze, consultare le nuove convenzioni per il caricamento da più origini.

🟡 ClassSkill per le definizioni delle competenze basate su classi

Richiesta pull:#5678

Aggiunge ClassSkill a agent-framework-core per le definizioni di competenze basate su classi con metadati dichiarativi e individuazione automatica dei metodi.

🟡 Difesa contro il prompt injection nel controllo del flusso di informazioni

PR:#5331

Aggiunge un meccanismo di controllo del flusso di informazioni a agent-framework-core per difendersi dagli attacchi di prompt injection.

🟡 github-copilot-sdk aggiornato alla versione 1.0.0b2

PR:#5665

Aggiorna agent-framework-github-copilot a github-copilot-sdk>=1.0.0b2, aggiungendo instruction_directories, la configurazione di copilot_home e l'inoltro delle opzioni di runtime alla ripresa della sessione.

🟡 Imporre approval_mode negli agenti Claude e GitHub Copilot

PR:#5562

agent-framework-claude e agent-framework-github-copilot ora impongono il decorator approval_mode agli strumenti di funzione, in linea con le altre implementazioni degli agenti.

🟡 Supporto per la selezione dello strumento OpenAI e Gemini allowed_tools

PR:#5322

Aggiunge il supporto per lo strumento allowed_tools in agent-framework-openai, consentendo di limitare gli strumenti che il modello può chiamare.

python-1.2.2 (29 aprile 2026)

Note sulla versione:python-1.2.2

🔴 Output del terminale di orchestrazione standardizzati come AgentResponse

PR:#5301

La PR #5301 standardizza l'output del terminale di orchestrazione come AgentResponse, così che Workflow.as_agent() restituisca solo la risposta finale.

• I flussi di approvazione sequenziale (with_request_info) e simultanei (intermediate_outputs=True) seguono ora lo stesso contratto di output.
• Se si usano direttamente i risultati dell'orchestrazione, aspettatevi oggetti AgentResponse anziché testo grezzo o tipi misti.

Before:

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

After:

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

🟡 Provider di contesto di Comprensione dei contenuti di Azure AI

PR:#4829

Nuovo pacchetto agent-framework-azure-contentunderstanding alfa: analizza automaticamente gli allegati di file (documenti, immagini, audio, video) e inserisce i risultati strutturati nel contesto LLM.

🟡 Supporto per workflow durevoli ospitati tramite l'hosting Foundry

PR:#5531

Aggiunge il supporto per Durable Workflow ospitato a agent-framework-foundry-hosting, propagando la cronologia completa delle conversazioni agli agenti del workflow.

python-1.1.0 (21 aprile 2026)

Note sulla versione:python-1.1.0

🔴 CosmosCheckpointStorage usa la deserializzazione pickle limitata per impostazione predefinita

PR:#5200

CosmosCheckpointStorage ora usa per impostazione predefinita la deserializzazione pickle con restrizioni, in linea con il comportamento di FileCheckpointStorage.

• Se i checkpoint contengono tipi definiti dall'applicazione, passali tramite allowed_checkpoint_types=["my_app.models:MyState"].
• Senza questo, la deserializzazione dei tipi personalizzati genererà WorkflowCheckpointException.

Before:

from agent_framework.azure.cosmos import CosmosCheckpointStorage

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

After:

from agent_framework.azure.cosmos import CosmosCheckpointStorage

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

🟡 GeminiChatClient aggiunta

PR:#4847

Nuovo pacchetto agent-framework-gemini con GeminiChatClient per il supporto dell'API Google Gemini e di Vertex AI.

🟡 Pacchetto Hyperlight CodeAct

PR:#5185

Nuovo pacchetto agent-framework-hyperlight per l'esecuzione di codice in sandbox di CodeAct basato su Hyperlight.

🟡 Supporto per Foundry Toolboxes

PR:#5346

Aggiunge il supporto per le cassette degli strumenti Foundry in agent-framework-foundry, consentendo configurazioni gestite degli strumenti da Azure AI Foundry.

🟡 finish_reason su AgentResponse e AgentResponseUpdate

PR:#5211

Aggiunge finish_reason il campo a AgentResponse e AgentResponseUpdate, consentendo ai consumer di verificare il motivo per cui il modello ha smesso di generare.

🟡 Supporto dell'agente ospitato V2 in Foundry

Richiesta pull:#5379

Aggiunge il supporto per l'agente ospitato V2 in agent-framework-foundry per le funzionalità più recenti del Servizio agenti Foundry.

python-1.0.1 (9 aprile 2026)

Note sulla versione:python-1.0.1

🔴 FileCheckpointStorage usa la deserializzazione pickle con restrizioni (rafforzamento della sicurezza)

Richiesta pull:#4941

La deserializzazione dei checkpoint ora avviene tramite un unpickler con restrizioni per impostazione predefinita, che consente solo un insieme integrato di tipi Python sicuri e tutti i tipi del framework agent_framework.

• Se l'applicazione archivia tipi personalizzati nei checkpoint, passare i relativi identificatori "module:qualname" tramite il nuovo parametro del costruttore allowed_checkpoint_types, altrimenti le operazioni di caricamento genereranno WorkflowCheckpointException.
• Per informazioni dettagliate, vedere Considerazioni sulla sicurezza .

Before:

from agent_framework.workflows import FileCheckpointStorage

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

After:

from agent_framework import FileCheckpointStorage

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

🔴 Correzione della gestione del contesto nel workflow di passaggio

Richiesta pull:#5136

La richiesta pull #5136 corregge la gestione del contesto nel workflow di passaggio. Si tratta di un cambiamento comportamentale: gli agenti coinvolti nel passaggio ora mantengono correttamente un contesto isolato durante le transizioni.

🟡 Archiviazione dei checkpoint di Cosmos DB NoSQL per i flussi di lavoro

Richiesta pull:#4916

Nuovo pacchetto agent-framework-azure-cosmos che fornisce l'archiviazione checkpoint supportata da Cosmos DB NoSQL per i flussi di lavoro di Python.

python-1.0.0 (2 aprile 2026)

Note sulla versione:python-1.0.0

In questa sezione vengono acquisite le modifiche significative di Python che sono state apportate dopo python-1.0.0rc6 e ora fanno parte di python-1.0.0.

🔴 Message(..., text=...) la costruzione è ora completamente rimossa

Richiesta pull:#5062

PR #5062 completa la precedente pulizia del modello di messaggio Python rimuovendo gli ultimi percorsi di codice nel framework che ancora costruivano oggetti Message con text=....

• Compilare messaggi di testo come Message(role="user", contents=["Hello"]) anziché Message(role="user", text="Hello").
• Questo vale ovunque si costruisca direttamente i messaggi, incluse le richieste del flusso di lavoro, le risposte middleware personalizzate, gli helper di orchestrazione e il codice di migrazione.
• Le stringhe semplici all'interno contents=[...] sono ancora normalizzate in contenuto di testo automaticamente, quindi contents=["Hello"] rimane il formato di solo testo più semplice.

Before:

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

After:

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

🟡 I pacchetti Python rilasciati non richiedono più --pre

Richiesta pull:#5062

La richiesta pull #5062 promuove i principali pacchetti Python a 1.0.0 e aggiorna le linee guida per l'installazione per distinguere i pacchetti rilasciati dai pacchetti ancora in versione preliminare.

• agent-framework agent-framework-core, agent-framework-openai, e agent-framework-foundry sono ora pacchetti rilasciati e non richiedono --prepiù .
• I connettori beta, ad esempio agent-framework-ag-ui, agent-framework-azurefunctionsagent-framework-copilotstudio, agent-framework-foundry-local, agent-framework-github-copilot, , agent-framework-mem0e agent-framework-ollama richiedono --preancora .
• Se un singolo comando di installazione include un qualsiasi pacchetto beta, è necessario mantenere --pre su tale comando.

🔴 Foundry possiede ora incorporamenti Python e impostazioni di endpoint dei modelli

Richiesta pull:#5056

PR #5056 rimuove il pacchetto autonomo agent-framework-azure-ai e sposta l'interfaccia di embedding di Python su agent-framework-foundry e agent_framework.foundry.

• Usare FoundryEmbeddingClient, FoundryEmbeddingOptions, e FoundryEmbeddingSettings da agent_framework.foundry.
• Installare agent-framework-foundry per la chat Foundry, gli agenti gestiti dal servizio, i provider di memoria e gli incorporamenti.
• agent_framework.azure non esporta AzureAIInferenceEmbeddingClientpiù , AzureAIInferenceEmbeddingOptions, AzureAIInferenceEmbeddingSettingso AzureAISettings.
• Gli incorporamenti di fonderia ora usano FOUNDRY_MODELS_ENDPOINT, FOUNDRY_MODELS_API_KEY, FOUNDRY_EMBEDDING_MODEL, e l'opzionale FOUNDRY_IMAGE_EMBEDDING_MODEL.
• FoundryChatClient e FoundryAgent usano comunque le impostazioni dell'endpoint del progetto, FOUNDRY_PROJECT_ENDPOINT ad esempio e 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"],
)

🔴 I workflow ora instradano i kwargs di runtime tramite bucket espliciti.

Richiesta pull:#5010

La richiesta pull #5010 aggiorna Python workflow.run(...) in modo che i kwargs di runtime vengano passati in modo esplicito come function_invocation_kwargs= e client_kwargs= invece che **kwargs genericamente inoltrati.

• Un mapping flat viene considerato globale e viene inoltrato a ogni executor di agente corrispondente nel workflow.
• Se una o più chiavi di primo livello corrispondono agli ID degli executor, l'intero mapping viene considerato come destinazione specifica per ciascun executor ed ogni executor riceve solo la propria voce.
• Gli ID executor del workflow AgentExecutor(id="...") personalizzati e altri espliciti sono le chiavi su cui ci si concentra.
• Le stesse regole globali e mirate si applicano sia a function_invocation_kwargs che a 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 ora esegue provider di contesto per ogni chiamata

Richiesta pull:#5013

La richiesta pull #5013 corregge un gap di comportamento di Python in cui GitHubCopilotAgent è accettato context_providers ma non è stato effettivamente richiamato.

• before_run() ora viene eseguito prima dell'invio del prompt di Copilot.
• I messaggi e le istruzioni aggiunti dal provider sono inclusi nel prompt che raggiunge la CLI di Copilot.
• after_run() viene ora eseguito dopo l'assemblaggio della risposta finale, incluso il percorso di streaming.

Se è già stato passato context_providers a GitHubCopilotAgent, non è necessaria alcuna migrazione. Gli hook ora si comportano in modo coerente con il resto della superficie dell'agente Python.

🟡 L'output strutturato accetta ora mapping di schemi JSON oltre ai modelli Pydantic

PR:#5022

La richiesta pull #5022 amplia l'analisi dell'output strutturato di Python così che response_format possa essere un modello Pydantic o un mapping dello schema JSON.

• I modelli Pydantic vengono ancora analizzati nelle istanze del modello tipizzato su response.value.
• I mapping degli schemi JSON ora analizzano valori compatibili JSON di Python in response.value (tipicamente in dict o list).
• Le stesse regole di analisi si applicano quando si raccoglie la risposta finale da un flusso.

Si tratta di un miglioramento anziché di una modifica che causa un'interruzione, ma è utile sapere se gli schemi sono già archiviati come dizionari simili a JSON.

python-1.0.0rc6

In questa sezione vengono acquisite le modifiche significative di Python fornite con o rilevate per python-1.0.0rc6.

🔴 La selezione del modello è standardizzata in model

Richiesta pull:#4999

Il PR #4999 completa la pulizia della selezione del modello sul lato Python tra costruttori, opzioni tipizzate, impostazioni di default dell'agente, oggetti risposta e variabili di ambiente.

• Usare model ovunque in precedenza si usava model_id.
• Agent.default_options e options={...} per ogni esecuzione ora prevedono "model", non "model_id".
• Gli oggetti di risposta espongono response.model, non response.model_id.
• Le impostazioni OpenAI ora usano OPENAI_MODEL, OPENAI_CHAT_MODELOPENAI_CHAT_COMPLETION_MODEL, e OPENAI_EMBEDDING_MODEL.
• Le impostazioni di Azure OpenAI ora usano AZURE_OPENAI_MODEL, AZURE_OPENAI_CHAT_MODEL, AZURE_OPENAI_CHAT_COMPLETION_MODELe AZURE_OPENAI_EMBEDDING_MODEL.
• Anthropic ora usa ANTHROPIC_CHAT_MODEL, e Foundry Local usa FOUNDRY_LOCAL_MODEL.
• Il pacchetto Anthropic aggiunge anche wrapper ospitati dal provider, come AnthropicFoundryClient, AnthropicBedrockClient e 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"},
)

🔴 I provider di contesto possono aggiungere middleware e rendere persistente la cronologia per ogni chiamata al modello

Richiesta pull:#4992

PR #4992 aggiorna la pipeline del provider di contesto Python e il modo in cui la cronologia gestita dal framework può essere resa persistente durante le esecuzioni con più chiamate.

• ContextProvider e HistoryProvider sono ora le classi di base di Python canoniche.
• BaseContextProvider e BaseHistoryProvider rimangono temporaneamente come alias deprecati per la compatibilità, ma il nuovo codice deve eseguire la migrazione ai nuovi nomi.
• SessionContext può ora raccogliere il middleware di chat o funzione aggiunto dal provider tramite extend_middleware() ed esporre l'elenco normale tramite get_middleware().
• Agent(..., require_per_service_call_history_persistence=True) esegue provider di cronologia per ogni chiamata di modello anziché una volta dopo run() completo.
• Questa modalità è destinata alla cronologia locale gestita dal framework e non può essere combinata con una conversazione gestita dal servizio esistente, session.service_session_id ad esempio o 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,
)

🔴 Superfici di compatibilità di Azure/OpenAI deprecate rimosse

Richiesta pull:#4990

La richiesta pull #4990 completa la migrazione leader del provider da #4818 rimuovendo le superfici di compatibilità deprecate di Python che erano ancora disponibili nelle precedenti versioni di anteprima.

• agent_framework.azure non esporta più AzureOpenAI* né le superfici agente/client/provider meno recenti AzureAI*.
• I tipi di compatibilità degli assistenti OpenAI Python non sono più inclusi nella superficie attuale agent_framework.openai.
• Usare OpenAIChatClient, OpenAIChatCompletionCliente OpenAIEmbeddingClient per scenari OpenAI diretti o OpenAI di Azure.
• Usare FoundryChatClient per l'inferenza del progetto Foundry e FoundryAgent per Prompt Agents o HostedAgents.
• Lo spazio dei nomi corrente agent_framework.azure include ora le integrazioni di Azure rimanenti, ad esempio Ricerca di intelligenza artificiale di Azure, Cronologia Cosmos, Funzioni di Azure e flussi di lavoro durevoli. Chat, agenti, memoria e incorporamenti dei client Foundry si trovano in agent_framework.foundry.

Se si esegue la migrazione di codice Python meno recente, usare queste sostituzioni:

• AzureOpenAIResponsesClient → OpenAIChatClient
• AzureOpenAIChatClient → OpenAIChatCompletionClient
• AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
• AzureAIAgentClient / AzureAIClient / AzureAIProjectAgentProvider / AzureAIAgentsProvider FoundryChatClient→ o FoundryAgent, a seconda che l'app sia proprietaria della definizione dell'agente
• OpenAIAssistantsClient / OpenAIAssistantProvider OpenAIChatClient→ per il funzionamento corrente di Python OpenAI o FoundryAgent se è necessario un agente gestito dal servizio in Foundry

🔴 Progettazione dei client leader e suddivisione dei pacchetti del provider

Richiesta pull:#4818

La richiesta pull #4818 riorganizza la superficie del provider Python per i pacchetti e gli spazi dei nomi specifici del provider.

• I client OpenAI ora risiedono nel pacchetto agent-framework-openai, pur continuando a importare dal namespace agent_framework.openai.
• I clienti di Microsoft Foundry ora risiedono nel agent-framework-foundry pacchetto e nello agent_framework.foundry spazio dei nomi.
• Foundry Local viene reso disponibile anche da agent_framework.foundry come FoundryLocalClient.
• OpenAIResponsesClient viene rinominato in OpenAIChatClient.
• OpenAIChatClient viene rinominato in OpenAIChatCompletionClient.
• La configurazione client è standardizzata in model, sostituendo i parametri meno recenti, ad model_idesempio , deployment_namee model_deployment_name.
• Per il nuovo codice OpenAI di Azure, usare i agent_framework.openai client. Gli shim di compatibilità precedenti AzureOpenAI* sono stati rimossi successivamente in #4990.
• Per il nuovo codice Foundry, usare FoundryChatClient per l'inferenza diretta del progetto, FoundryAgent per Prompt Agents e HostedAgents e FoundryLocalClient per i runtime locali.
• AzureAIClient, AzureAIProjectAgentProvider, AzureAIAgentClient, AzureAIAgentsProvider e la superficie di compatibilità degli assistenti Python è stata spostata sui percorsi di compatibilità durante questo refactoring e successivamente rimossa in #4990.
• La copertura di esempio è stata riorganizzata in modo da corrispondere al nuovo layout leader del provider, inclusi gli esempi di Foundry in samples/02-agents/providers/foundry/.

Mappatura dei pacchetti

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

Se in precedenza si usava direttamente Azure OpenAI, eseguire il mapping delle classi dedicate precedenti alle nuove classi OpenAI leader del provider:

• AzureOpenAIResponsesClient → OpenAIChatClient
• AzureOpenAIChatClient → OpenAIChatCompletionClient
• AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
• AzureOpenAIAssistantsClient → OpenAIChatClient per la migrazione diretta dell'API Risposte, oppure FoundryAgent se è necessario un agente Foundry gestito dal servizio

La modifica del codice è principalmente un trasferimento del nome della classe più deployment_name → model. Per la compatibilità di Azure OpenAI, usare input espliciti di Azure nei nuovi client OpenAI. credential= è ora la superficie di autenticazione di Azure preferita, mentre un elemento chiamabile api_key rimane un percorso di compatibilità:

Prima (AzureOpenAIResponsesClient):

from agent_framework.azure import AzureOpenAIResponsesClient

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

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

Prima (AzureOpenAIChatClient):

from agent_framework.azure import AzureOpenAIChatClient

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

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

Se si vuole passare dagli endpoint OpenAI di Azure a un endpoint di progetto Microsoft Foundry, usare invece la superficie orientata a Foundry:

Prima (endpoint OpenAI di Azure):

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

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

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

Per i runtime locali di Microsoft Foundry, usare lo spazio dei nomi Foundry più il connettore locale:

from agent_framework.foundry import FoundryLocalClient

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

Se ometti model, imposta FOUNDRY_LOCAL_MODEL nel tuo ambiente.

Aggiornare anche i nomi di ambiente/configurazione, se applicabile:

• Usare OPENAI_CHAT_MODEL per OpenAIChatClient, OPENAI_CHAT_COMPLETION_MODEL per OpenAIChatCompletionClient, con OPENAI_MODEL come fallback condiviso.
• Azure OpenAI ora usa AZURE_OPENAI_CHAT_MODEL per OpenAIChatClient, AZURE_OPENAI_CHAT_COMPLETION_MODEL per OpenAIChatCompletionClient, e AZURE_OPENAI_MODEL come fallback condiviso.
• Usare azure_endpoint per gli URL delle risorse OpenAI di Azure o base_url se si ha già un URL completo .../openai/v1 e impostare api_version per la superficie dell'API OpenAI di Azure in uso
• Adotta impostazioni specifiche di Foundry, come FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, FOUNDRY_AGENT_NAME e FOUNDRY_AGENT_VERSION per i client di Cloud Foundry.
• Usare ANTHROPIC_CHAT_MODEL per Anthropic e FOUNDRY_LOCAL_MODEL per Foundry Local

Questa modifica è stata implementata per la prima volta durante il ciclo python-1.0.0rc6.

🔴 Le dipendenze principali sono ora intenzionalmente sottili

Richiesta pull:#4904

La richiesta pull #4904 segue la suddivisione del pacchetto del provider da #4818 riducendo agent-framework-core e rimuovendo altre dipendenze transitive del provider dal pacchetto principale.

• agent-framework-core è ora intenzionalmente minimo.
• Se importi agent_framework.openai, installa agent-framework-openai.
• Se si importa agent_framework.foundry, installare agent-framework-foundry per l'inferenza del progetto Foundry, gli agenti gestiti dal servizio, i provider di memoria e gli incorporamenti. Usare agent-framework-foundry-local --pre per i runtime locali.
• Se si usano strumenti MCP, Agent.as_mcp_server()o altre integrazioni MCP in un'installazione minima, installare mcp --pre manualmente. Per il supporto MCP di WebSocket, installare mcp[ws] --pre.
• Se si vuole l'esperienza generale "tutto incluso", installare il meta pacchetto agent-framework.

Questo non riprogetta nuovamente la superficie del provider; cambia ciò che viene installato per impostazione predefinita quando si porta solo la base.

Prima di (le installazioni di base spesso comportano più funzionalità del provider in modo transitivo):

pip install agent-framework-core

Dopo (installare il pacchetto del provider in uso):

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

or:

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

Se si aggiorna un progetto esistente che in precedenza dipendeva da importazioni principali e posticipate dei provider, verificare le importazioni e specificare esplicitamente i pacchetti dei provider nell'ambiente o nei file di dipendenza. Effettuare la stessa operazione per le dipendenze MCP se ci si affida agli strumenti MCP o all'hosting su server MCP.

🔴 I client OpenAI generici preferiscono ora segnali di routing espliciti

Richiesta pull:#4925

PR #4925 modifica il modo in cui client generici agent_framework.openai decidono tra OpenAI e Azure OpenAI.

• I client OpenAI generici non passano più ad Azure solo perché AZURE_OPENAI_* sono presenti variabili di ambiente.
• Se OPENAI_API_KEY è configurato, i client generici rimangono in OpenAI a meno che non si passi un segnale di routing esplicito di Azure, credential ad esempio o azure_endpoint.
• Se sono presenti solo le impostazioni AZURE_OPENAI_*, i client generici possono comunque fare fallback al routing basato sull'ambiente di Azure.
• Il modello OpenAI di Azure preferito consiste ora nel passare le impostazioni esplicite di Azure più credential=AzureCliCredential() in OpenAIChatClient, OpenAIChatCompletionClient e il client di incorporamento.
• I wrapper deprecati AzureOpenAI* mantengono il comportamento di compatibilità, quindi il codice basato su wrapper esistente non segue le nuove regole di precedenza del client generico.

Prima (OpenAIChatClient poteva instradare ad Azure perché erano presenti le variabili d'ambiente di Azure):

import os
from agent_framework.openai import OpenAIChatClient

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

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

Dopo (OpenAI generico rimane in OpenAI; passare gli input espliciti di Azure per forzare il routing ad 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(),
)

Se l'ambiente contiene sia valori OPENAI_* che AZURE_OPENAI_*, controlla qualsiasi costruzione client generica agent_framework.openai e rendi esplicita la scelta del provider. Per questo motivo, gli esempi del provider di Azure sono stati aggiornati per passare direttamente gli input di Azure.

Gli incorporamenti di Azure seguono ora lo stesso modello di routing:

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

Per gli scenari di incorporamento, effettuare la mappatura:

• AzureOpenAIEmbeddingClient → OpenAIEmbeddingClient
• AZURE_OPENAI_EMBEDDING_MODEL → model
• OPENAI_EMBEDDING_MODEL rimane la variabile di ambiente di incorporamento lato OpenAI

python-1.0.0rc5 / python-1.0.0b260319 (19 marzo 2026)

🔴 Pipeline client di chat riordinata: FunctionInvocation esegue ora il wrapping di ChatMiddleware

Richiesta pull:#4746

L'ordinamento della pipeline ChatClient è stato modificato. FunctionInvocation è ora il livello più esterno ed esegue il wrapping di ChatMiddleware, il che significa che il middleware della chat viene eseguito per ogni chiamata al modello (inclusa ogni iterazione del ciclo di chiamata dello strumento) anziché una volta per l'intera sequenza di invocazione delle funzioni.

Ordine della pipeline precedente:

ChatMiddleware → FunctionInvocation → RawChatClient

Nuovo ordine della pipeline:

FunctionInvocation → ChatMiddleware → ChatTelemetry → RawChatClient

Se si dispone di un middleware di chat personalizzato che presuppone di essere eseguito solo una volta per ogni invocazione dell'agente (che incapsula l'intero ciclo di chiamata dello strumento), aggiornarlo in modo che sia sicuro per l'esecuzione ripetuta. Il middleware di chat viene ora richiamato per ogni singola richiesta LLM, incluse le richieste che inviano i risultati dello strumento al modello.

Inoltre, ChatTelemetry è ora un livello separato da ChatMiddleware nella pipeline, in esecuzione più vicino a RawChatClient.

🔴 Kwargs di runtime pubblici suddivisi in bucket espliciti

Richiesta pull:#4581

L'agente Python pubblico e le API di chat non considerano più l'inoltro pubblico **kwargs generico come meccanismo principale di dati di runtime. I valori di runtime sono ora suddivisi per scopo:

• Usare function_invocation_kwargs per i valori che dovrebbero essere visibili solo agli strumenti o al middleware delle funzioni.
• Utilizzare client_kwargs per i kwargs del livello client e la configurazione del middleware client.
• Accedere ai dati dello strumento o del runtime tramite FunctionInvocationContext (ctx.kwargs e ctx.session).
• Definire gli strumenti con un parametro di contesto inserito anziché **kwargs. I parametri di contesto inseriti non vengono visualizzati nello schema visualizzato dal modello.
• Quando si delega a un agente secondario come strumento, usare agent.as_tool(propagate_session=True) se l'agente figlio deve condividere la sessione del chiamante.

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

Se implementi metodi pubblici run() o get_response() personalizzati, aggiungi function_invocation_kwargs e client_kwargs a quelle firme. Per gli strumenti, preferire un parametro annotato come FunctionInvocationContext — può essere nominato ctx, context o qualsiasi altro nome annotato. Se si specifica un modello di schema/input esplicito, viene riconosciuto anche un parametro non annotato normale denominato ctx . Lo stesso oggetto di contesto è disponibile per il middleware delle funzioni ed è dove ora risiedono i kwargs della funzione di runtime e lo stato della sessione. Le definizioni degli strumenti che si basano ancora su **kwargs usano solo un percorso di compatibilità legacy e verranno rimosse.

python-1.0.0rc4 / python-1.0.0b260311 (11 marzo 2026)

Note sulla versione:python-1.0.0rc4

🔴 Le integrazioni di Intelligenza artificiale di Azure ora puntano a azure-ai-projects 2.0 GA

Richiesta pull:#4536

Le integrazioni di Python con Azure AI ora presuppongono l'interfaccia GA 2.0 azure-ai-projects.

• L'intervallo di dipendenze supportato è ora azure-ai-projects>=2.0.0,<3.0.
• Il passthrough foundry_features è stato rimosso dalla creazione degli agenti di Azure AI.
• Il comportamento di anteprima ora usa allow_preview=True nei client/provider supportati.
• Gli shim di compatibilità beta/disponibilità generale misti sono stati rimossi, quindi aggiornare le importazioni e i nomi dei tipi sulla superficie SDK 2.0 in disponibilità generale.

🔴 I gestori degli strumenti di GitHub Copilot ora usano ToolInvocation / ToolResult e Python 3.11+

RICHIESTA pull:#4551

agent-framework-github-copilot ora tiene traccia di github-copilot-sdk>=0.1.32.

• I gestori degli strumenti ricevono una ToolInvocation classe di dati anziché un oggetto non elaborato dict.
• Restituisci ToolResult utilizzando campi in snake_case, come result_type e text_result_for_llm.
• Il agent-framework-github-copilot pacchetto richiede ora Python 3.11+.

Before:

from typing import Any


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

After:

from copilot.tools import ToolInvocation, ToolResult


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

python-1.0.0rc3 / python-1.0.0b260304 (4 marzo 2026)

Note sulla versione:python-1.0.0rc3

🔴 Provider di competenze completato per Skill / SkillResource definito dal codice

Richiesta pull:#4387

Le competenze dell'agente Python ora supportano gli oggetti definiti dal codice Skill e SkillResource insieme alle competenze basate su file, e la superficie del provider pubblico è standardizzata su SkillsProvider.

• Se stai ancora importando la precedente anteprima interna FileAgentSkillsProvider, passa a SkillsProvider.
• La ricerca delle risorse basata su file non utilizza più i riferimenti con virgolette inverse in SKILL.md; le risorse vengono individuate dalla directory delle competenze.

Se si dispone di codice interno/in anteprima che ha importato FileAgentSkillsProvider, passare alla superficie pubblica corrente:

from agent_framework import Skill, SkillResource, SkillsProvider

python-1.0.0rc2 / python-1.0.0b260226 (26 febbraio 2026)

Note sulla versione:python-1.0.0rc2

🔴 I flussi di lavoro dichiarativi sostituiscono InvokeTool con InvokeFunctionTool

Richiesta pull:#3716

I flussi di lavoro Dichiarativi python non usano più il tipo di azione precedente InvokeTool . Sostituirlo con InvokeFunctionTool e registrare i chiamabili Python con 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 (19 febbraio 2026)

Rilascio:agent-framework-core e agent-framework-azure-ai alzato di livello a 1.0.0rc1. Tutti gli altri pacchetti aggiornati a 1.0.0b260219.

🔴 Gestione unificata delle credenziali di Azure in tutti i pacchetti

Richiesta pull:#4088

I parametri ad_token, ad_token_provider e get_entra_auth_token/assistenti sono stati sostituiti con un parametro unificato credential in tutti i pacchetti Python correlati ad Azure. Il nuovo approccio usa azure.identity.get_bearer_token_provider per la memorizzazione automatica nella cache e l'aggiornamento dei token.

Classi interessate:AzureOpenAIChatClient, AzureOpenAIResponsesClient, AzureOpenAIAssistantsClient, AzureAIClient, AzureAIAgentClient, AzureAIProjectAgentProviderAzureAIAgentsProviderAzureAISearchContextProviderPurviewClientPurviewPolicyMiddleware. 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(),
    ...
)

Il credential parametro accetta TokenCredential, AsyncTokenCredentialo un provider di token chiamabile. La memorizzazione nella cache e l'aggiornamento dei token vengono gestiti automaticamente.

🔴 Gerarchia di eccezioni Python riprogettata

Richiesta pull:#4082

La famiglia flat ServiceException è stata sostituita con rami di eccezioni con ambito di dominio sotto una singola radice AgentFrameworkException. In questo modo, fornisce ai chiamanti destinazioni except precise e una chiara semantica degli errori.

Nuova gerarchia:

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

Eccezioni rimosse:ServiceException, ServiceInitializationError, ServiceResponseExceptionServiceContentFilterException, ServiceInvalidAuthError, , ServiceInvalidExecutionSettingsError, ServiceInvalidRequestErrorServiceInvalidResponseError, 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
    ...

🔴 Stato del provider delimitato da source_id

PR:#3995

Gli hook del provider ricevono ora un dizionario di stato con ambito provider (state.setdefault(provider.source_id, {})) anziché lo stato completo della sessione. Ciò significa che le implementazioni del provider che in precedenza hanno eseguito l'accesso allo stato annidato tramite state[self.source_id]["key"] devono ora accedere state["key"] direttamente.

Inoltre, InMemoryHistoryProvider il valore predefinito source_id è passato da "memory" a "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")

🔴 Allineamento digitazione messaggi chat/agente (run vs get_response)

Richiesta pull:#3920

Le implementazioni client get_response di chat ricevono Sequence[Message] ora in modo coerente. agent.run(...) rimane flessibile (str, Content, Messageo sequenze di tali elementi) e normalizza gli input prima di chiamare i client di 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): ...

Installazione generica di 🔴FunctionTool[Any] rimossa per il pass-through dello schema

Richiesta pull:#3907

I percorsi degli strumenti basati su schema non si basano più sul comportamento generico precedente FunctionTool[Any] . Usare FunctionTool direttamente e fornire un BaseModel Pydantic o schemi espliciti, se necessario (ad esempio, con @tool(schema=...)).

Before:

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

After:

placeholder: FunctionTool = FunctionTool(...)

🔴 Impostazioni Pydantic sostituite con TypedDict + load_settings()

Richieste pull:#3843, #4032

La pydantic-settingsclasse basata su AFBaseSettings è stata sostituita con un sistema di impostazioni leggero basato su funzioni usando TypedDict e load_settings(). La pydantic-settings dipendenza è stata rimossa completamente.

Tutte le classi di impostazioni ( ad esempio OpenAISettings, , AzureOpenAISettings, AnthropicSettings) sono ora TypedDict definizioni e i valori delle impostazioni sono accessibili tramite la sintassi del dizionario anziché l'accesso agli attributi.

Before:

from agent_framework.openai import OpenAISettings

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

After:

from agent_framework import load_settings
from agent_framework.openai import OpenAISettings

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

🟡 Correggi il passaggio del flusso di lavoro del modello di ragionamento e la serializzazione della cronologia

Richiesta pull:#4083

Corregge più errori quando si usano modelli di ragionamento (ad esempio, gpt-5-mini, gpt-5.2) nei flussi di lavoro con più agenti. Gli elementi di ragionamento dell'API Risposte vengono ora serializzati correttamente e inclusi nella cronologia solo quando è presente anche un oggetto function_call , impedendo gli errori dell'API. Il contenuto di ragionamento crittografato/nascosto viene ora generato correttamente e il formato del summary campo viene corretto. L'oggetto service_session_id viene inoltre cancellato durante il passaggio per evitare perdite di stato tra agenti.

🟡 Bedrock aggiunto a core[all] e impostazioni predefinite delle scelte degli strumenti corrette

Richiesta pull:#3953

Amazon Bedrock è ora incluso negli agent-framework-core[all] aggiuntivi ed è disponibile tramite la superficie di importazione lazy agent_framework.amazon. È stato corretto anche il comportamento di scelta degli strumenti: i valori di scelta dello strumento non impostati rimangono ora non impostati, in modo che i provider usino le impostazioni predefinite del servizio, mentre vengono mantenuti i valori esplicitamente impostati.

from agent_framework.amazon import BedrockChatClient

🟡 AzureAIClient ha avvisato su sostituzioni di runtime non supportate

Richiesta pull:#3919

Al momento di questa modifica, AzureAIClient ha registrato un avviso quando il runtime tools o structured_output differiva dalla configurazione in fase di creazione dell'agente. La superficie Python è stata rimossa. Per il codice Python corrente, utilizzare FoundryChatClient quando è necessaria la configurazione dello strumento o del runtime proprietario dell'app, o OpenAIChatClient per scenari dell'API di Risposte dirette che richiedono override dinamici.

🟡 workflow.as_agent() ora imposta di default la cronologia locale quando i provider non sono impostati

Richiesta pull:#3918

Quando workflow.as_agent() viene creato senza context_providers, ora aggiunge InMemoryHistoryProvider("memory") di default. Se i provider di contesto vengono forniti in modo esplicito, tale elenco viene mantenuto invariato.

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

🟡 Contesto di traccia OpenTelemetry trasmesso alle richieste MCP

Richiesta pull:#3780

Quando OpenTelemetry è installato, il contesto di traccia ,ad esempio W3C traceparent, viene inserito automaticamente nelle richieste MCP tramite params._meta. In questo modo è possibile abilitare il tracciamento distribuito end-to-end tra chiamate agente → server MCP. Nessuna modifica del codice necessaria: si tratta di un comportamento aggiuntivo che si attiva quando esiste un contesto di intervallo valido.

🟡 Supporto del flusso di lavoro durevole per Funzioni di Azure

Richiesta pull:#3630

Il pacchetto agent-framework-azurefunctions supporta ora l'esecuzione di grafici Workflow in Funzioni durevoli di Azure. Passare un workflow parametro a AgentFunctionApp per registrare automaticamente le entità agente, le funzioni di attività e gli endpoint HTTP.

from agent_framework.azure import AgentFunctionApp

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

Supporta modelli fan-out/fan-in, stato condiviso e intervento umano nel ciclo con timeout configurabile e rifiuto automatico alla scadenza.

python-1.0.0b260212 (12 febbraio 2026)

Note sulla versione:python-1.0.0b260212

🔴 Hosted*Toolclassi sostituite da metodi client get_*_tool()

Richiesta pull:#3634

Le classi di strumenti ospitati sono state rimosse a favore dei metodi factory con ambito client. In questo modo, la disponibilità dello strumento è esplicita da parte del provider.

Before:

from agent_framework import HostedCodeInterpreterTool, HostedWebSearchTool

tools = [HostedCodeInterpreterTool(), HostedWebSearchTool()]

After:

from agent_framework.openai import OpenAIChatClient

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

🔴 La pipeline del provider di sessione/contesto è stata finalizzata (AgentSession, context_providers)

PR:#3850

La migrazione della sessione Python e del provider di contesto è stata completata. AgentThread e i tipi di provider di contesto precedenti sono stati rimossi.

• 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= i modelli vengono sostituiti da context_providers=[...]
• ChatMessageStore è stato rimosso. Usare HistoryProvider (o InMemoryHistoryProvider per il caso in memoria predefinito), entrambi esportati da agent_framework. Se non viene passato alcun provider di contesto, l'agente inserisce automaticamente InMemoryHistoryProvider.

Before:

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

After:

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

🔴 Modello del checkpoint e comportamento di archiviazione rifattorizzato

Richiesta pull:#3744

Sono stati riprogettati gli interni del checkpoint, che influiscono sulla compatibilità dei checkpoint persistenti e sulle implementazioni di archiviazione personalizzate:

• WorkflowCheckpoint archivia ora gli oggetti attivi (la serializzazione avviene nell'archiviazione del checkpoint)
• FileCheckpointStorage ora usa la serializzazione pickle
• workflow_id è stato rimosso ed previous_checkpoint_id è stato aggiunto
• Sono stati rimossi hook di checkpoint deprecati

Se si salvano in modo permanente i checkpoint tra versioni, rigenerare o eseguire la migrazione di artefatti di checkpoint esistenti prima di riprendere i workflow.

🟡 Gli endpoint del progetto Foundry sono stati originariamente esposti attraverso AzureOpenAIResponsesClient

Richiesta pull:#3814

Questa funzionalità di anteprima ha originariamente consentito AzureOpenAIResponsesClient di connettersi agli endpoint del progetto Foundry. Le indicazioni correnti per Python utilizzano FoundryChatClient per l'inferenza del progetto Foundry o FoundryAgent per gli agenti Foundry gestiti dal servizio invece del rimosso 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(),
)

🔴 Il middleware call_next non accetta più context

Richiesta pull:#3829

Ora la continuazione del middleware non accetta argomenti. Se il middleware chiama call_next(context)ancora , aggiornarlo a 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 febbraio 2026)

Note sulla versione:python-1.0.0b260210

🔴 Metodi di factory del workflow rimossi da WorkflowBuilder

Richiesta pull:#3781

register_executor() e register_agent() sono stati rimossi da WorkflowBuilder. Tutti i metodi del generatore (add_edge, add_fan_out_edges, add_fan_in_edgesadd_chain, add_switch_case_edge_groupadd_multi_selection_edge_group) e start_executor non accettano più nomi di stringa, richiedono direttamente istanze dell'executor o dell'agente.

Per l'isolamento dello stato, eseguire il wrapping dell'istanza dell'executor o dell'agente e creare il workflow all'interno di un metodo helper, così che ogni chiamata generi istanze nuove.

WorkflowBuilder con executor

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 con agenti

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 dello stato con metodi helper

Per i workflow che richiedono uno stato isolato per chiamata, eseguire il wrapping della costruzione in un metodo helper:

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 rinominato in Agent, ChatMessage rinominato in Message

Richiesta pull:#3747

I tipi Python di base sono stati semplificati rimuovendo il prefisso ridondante Chat . Non vengono forniti alias di compatibilità con le versioni precedenti.

Aggiornare le importazioni

Before:

from agent_framework import ChatAgent, ChatMessage

After:

from agent_framework import Agent, Message

Aggiornare i riferimenti ai tipi

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

🔴 I tipi API esaminano gli aggiornamenti nei modelli di risposta/messaggio

Richiesta pull:#3647

Questa versione include una profonda e sostanziale revisione delle API relative alla tipologia di messaggi/risposte e agli helper.

• Role e FinishReason sono ora wrapper NewType su str con RoleLiteral/FinishReasonLiteral per i valori noti. Considerarli come stringhe (nessun .value utilizzo).
• Message la costruzione è standardizzata su Message(role, contents=[...]); le stringhe in contents vengono convertite automaticamente in il contenuto di testo.
• I costruttori ChatResponse e AgentResponse ora si concentrano su messages= (singola Message o sequenza); l'utilizzo del costruttore legacy text= è stato rimosso dalle risposte.
• ChatResponseUpdate e AgentResponseUpdate non accetta text=più ; usare contents=[Content.from_text(...)].
• I nomi dei helper per la combinazione degli aggiornamenti sono stati semplificati.
• try_parse_value è stato rimosso da ChatResponse e AgentResponse.

Ridenominazione del metodo helper

Aggiornare la creazione dell'aggiornamento della risposta

Before:

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

After:

from agent_framework import AgentResponseUpdate, Content

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

Sostituire try_parse_value con try/except su .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}")

🔴 Modello unificato run/get_response e ResponseStream utilizzo

Richiesta pull:#3379

Le API Python sono state consolidate intorno a agent.run(...) e client.get_response(...), con il flusso rappresentato da 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)

🔴 Ridenominazione del tipo di contesto/protocollo di base

PR:#3714, #3717

Aggiornare le importazioni e le annotazioni di tipo di conseguenza.

🔴 Parametro di continuazione middleware rinominato in call_next

Richiesta pull:#3735

Le firme middleware dovrebbero ora usare call_next invece di 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)

🔴 Nomi TypeVar standardizzati (TName → NameT)

Richiesta pull:#3770

La codebase segue ora uno stile di denominazione TypeVar coerente in cui viene usato il suffisso T .

Before:

TMessage = TypeVar("TMessage")

After:

MessageT = TypeVar("MessageT")

Se si mantengono wrapper personalizzati per i valori generici del framework, allineare i nomi TypeVar locali con la nuova convenzione per ridurre la varianza delle annotazioni.

🔴 Output e modifiche in streaming del workflow come agente

PR:#3649

workflow.as_agent() il comportamento è stato aggiornato per allineare l'output e lo streaming ai modelli di risposta dell'agente standard. Esaminare i consumatori del workflow come agente che dipendono dalla gestione di output/aggiornamento legacy e aggiornarli al flusso attuale AgentResponse/AgentResponseUpdate.

🔴 I metodi di Fluent Builder sono stati spostati nei parametri del costruttore

Richiesta pull:#3693

I metodi fluenti a configurazione unica in 6 costruttori (WorkflowBuilder, SequentialBuilder, ConcurrentBuilder, GroupChatBuilder, MagenticBuilder, HandoffBuilder) sono stati migrati ai parametri del costruttore. I metodi Fluent che erano l'unico percorso di configurazione per un'impostazione vengono rimossi a favore degli argomenti del costruttore.

WorkflowBuilder

set_start_executor(), with_checkpointing()e with_output_from() vengono rimossi. Usare invece i parametri del costruttore.

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() vengono rimossi. Usare invece i parametri del costruttore.

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() vengono rimossi. Usare invece i parametri del costruttore.

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() vengono rimossi. with_intermediate_outputs() Usare invece i parametri del costruttore.

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() vengono rimossi. Usare invece i parametri del costruttore.

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

Modifiche alla convalida

• WorkflowBuilder ora richiede start_executor come argomento del costruttore (impostato in precedenza tramite il metodo Fluent)
• SequentialBuilder, ConcurrentBuilder, GroupChatBuilder e MagenticBuilder ora richiedono participants o participant_factories in fase di creazione , passando nessuno dei due si genera ValueError

🔴 Eventi del flusso di lavoro unificati in un unico WorkflowEvent con type discriminatore

Richiesta pull:#3690

Tutte le singole sottoclassi di eventi del flusso di lavoro sono state sostituite da una singola classe generica WorkflowEvent[DataT] . Invece di usare isinstance() controlli per identificare i tipi di evento, ora si controlla la event.type stringa letterale (ad esempio "output", "request_info", "status"). Questo segue lo stesso modello del consolidamento della Content classe da python-1.0.0b260123.

Classi di evento rimosse

Le sottoclassi di evento esportate seguenti non esistono più:

Aggiornare le importazioni

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

Aggiorna i controlli del tipo di evento

Before:

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

After:

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

Streaming con AgentResponseUpdate

Before:

from agent_framework import AgentResponseUpdate, WorkflowOutputEvent

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

After:

from agent_framework import AgentResponseUpdate

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

Annotazioni dei tipi

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

Richiesta pull:#3720

send_responses() e send_responses_streaming() sono stati rimossi da Workflow. Continuare i flussi di lavoro sospesi passando le risposte direttamente a run().

Before:

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

After:

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

🔴 SharedState rinominato in State; le API dello stato del flusso di lavoro sono sincrone

Richiesta pull:#3667

Le API di stato non richiedono awaitpiù e la denominazione è stata standardizzata:

🔴 Generatori di orchestrazioni spostati in agent_framework.orchestrations

Richiesta pull:#3685

I generatori di orchestrazione si trovano ora in uno spazio dei nomi del pacchetto dedicato.

Before:

from agent_framework import SequentialBuilder, GroupChatBuilder

After:

from agent_framework.orchestrations import SequentialBuilder, GroupChatBuilder

🟡 Risposte in background a esecuzione prolungata e token di continuazione

Richiesta pull:#3808

Le risposte in background sono ora supportate per le esecuzioni dell'agente Python tramite 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})

🟡 Tipi di anteprima del provider di sessione/contesto aggiunti affiancati

Richiesta pull:#3763

Sono stati introdotti nuovi tipi di pipeline di sessione/contesto insieme alle API legacy per la migrazione incrementale, tra cui SessionContext e BaseContextProvider.

🟡 Lo streaming dell'interprete del codice ora include delta di codice incrementale

Richiesta pull:#3775

L'interprete del codice di streaming esegue ora aggiornamenti differenziali del codice di superficie nel contenuto trasmesso, in modo che le interfacce utente possano eseguire il rendering progressivo del codice generato.

🟡 @tool supporta la gestione esplicita dello schema

Richiesta pull:#3734

Le definizioni degli strumenti possono ora usare la gestione esplicita dello schema quando l'output dello schema dedotto richiede la personalizzazione.

python-1.0.0b260130 (30 gennaio 2026)

Note sulla versione:python-1.0.0b260130

🟡 ChatOptions e ChatResponse/AgentResponse ora generico rispetto al formato di risposta

Richiesta pull:#3305

ChatOptions, ChatResponsee AgentResponse sono ora tipi generici con parametri per il tipo di formato di risposta. Ciò consente una migliore inferenza dei tipi quando si usano output strutturati con 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 supporto aggiunto per Claude Agent SDK

Richiesta pull:#3509

Python SDK include ora un'implementazione BaseAgent per Claude Agent SDK, abilitando l'utilizzo basato su adattatori di prima classe in Agent Framework.

python-1.0.0b260128 (28 gennaio 2026)

Note sulla versione:python-1.0.0b260128

🔴 AIFunction rinominato in FunctionTool e @ai_function rinominato in @tool

Richiesta pull:#3413

La classe e il decoratore sono stati rinominati per chiarezza e coerenza con la terminologia del settore.

Before:

from agent_framework.core import ai_function, AIFunction

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

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

After:

from agent_framework import FunctionTool, tool

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

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

🔴 Modello factory aggiunto a GroupChat e Magentic; rinomina l'API

Richiesta pull:#3224

Aggiunta della factory del partecipante e della factory dell'orchestratore alla chat di gruppo. Include anche le ridenominazione:

• with_standard_manager → with_manager
• participant_factories → register_participant

Before:

from agent_framework.workflows import MagenticBuilder

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

After:

from agent_framework.orchestrations import MagenticBuilder

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

🔴 Github rinominato in GitHub

Richiesta pull:#3486

Nomi di classi e pacchetti aggiornati per usare maiuscole e minuscole corrette.

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 gennaio 2026)

Note sulla versione:python-1.0.0b260127

🟡 BaseAgent aggiunta del supporto per GitHub Copilot SDK

Richiesta pull:#3404

Python SDK include ora un'implementazione BaseAgent per le integrazioni di GitHub Copilot SDK.

python-1.0.0b260123 (23 gennaio 2026)

Note sulla versione:python-1.0.0b260123

🔴 Tipi di contenuto semplificati in una singola classe con costruttori classmethod

Richiesta pull:#3252

Sostituire tutti i tipi di contenuto precedenti (derivati da BaseContent) con una singola Content classe con classmethods per creare tipi specifici.

Guida completa alla migrazione

Nuovi metodi aggiuntivi (nessun predecessore diretto):

• Content.from_text_reasoning(...) — Contenuti di ragionamento/pensiero
• Content.from_hosted_vector_store(...) — Per i riferimenti all'archivio vettoriale
• Content.from_usage(...) — Per informazioni sull'utilizzo/token
• Content.from_mcp_server_tool_call(...) / Content.from_mcp_server_tool_result(...) — Per gli strumenti server MCP
• Content.from_code_interpreter_tool_call(...) / Content.from_code_interpreter_tool_result(...) — Per l'interprete di codice
• Content.from_image_generation_tool_call(...) / Content.from_image_generation_tool_result(...) — Per la generazione di immagini

Controllo dei tipi

isinstance() Anziché dei controlli, usare la type proprietà :

Before:

from agent_framework.core import TextContent, FunctionCallContent

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

After:

from agent_framework import Content

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

Esempio di base

Before:

from agent_framework.core import TextContent, DataContent, UriContent

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

After:

from agent_framework import Content

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

🔴 Tipi di annotazione semplificati in Annotation e TextSpanRegion TypedDicts

Richiesta pull:#3252

Sostituzione dei tipi di annotazione basati su classi con definizioni più semplici 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 errori di convalida ora visibili agli utenti

Richiesta pull:#3274

ChatResponse.value e AgentResponse.value ora generano ValidationError quando la convalida dello schema ha esito negativo anziché restituire Noneautomaticamente .

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, logica di esecuzione semplificata; correzioni client per MCP e Anthropic

Richiesta pull:#3322

La firma e il comportamento del run metodo in AG-UI sono stati semplificati.

Before:

from agent_framework.ag_ui import AGUIEndpoint

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

After:

from agent_framework.ag_ui import AgentFrameworkAgent

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

🟡 Il client Anthropic supporta response_format ora output strutturati

Richiesta pull:#3301

È ora possibile usare l'analisi dell'output strutturato con i client Anthropic tramite response_format, come per i client OpenAI e Azure.

🟡 Configurazione di Intelligenza artificiale di Azure espansa (reasoning, rai_config)

Richieste pull:#3403, #3265

Il supporto di AI di Azure è stato ampliato con il supporto alla configurazione del ragionamento e rai_config durante la creazione dell'agente.

python-1.0.0b260116 (16 gennaio 2026)

Note sulla versione:python-1.0.0b260116

🔴 create_agent rinominato in as_agent

Richiesta pull:#3249

Metodo rinominato per maggiore chiarezza sullo scopo.

Before:

from agent_framework.core import ChatClient

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

After:

from agent_framework.openai import OpenAIChatClient

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

🔴 WorkflowOutputEvent.source_executor_id rinominato in executor_id

Richiesta pull:#3166

Proprietà rinominata per coerenza API.

Before:

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

After:

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

🟡 AG-UI supporta la continuità della sessione gestita dal servizio

Richiesta pull:#3136

AG-UI mantiene ora l'identità della conversazione gestita dal servizio (ad esempio, sessioni/thread gestiti da Foundry) per conservare la continuità su più turni.

python-1.0.0b260114 (14 gennaio 2026)

Note sulla versione:python-1.0.0b260114

🔴 Orchestrazioni refattorizzate

Richiesta pull:#3023

Refactoring e semplificazione estese delle orchestrazioni nei workflow di Agent Framework:

• Chat di gruppo: suddividere l'esecutore dell'orchestratore in agente dedicato e basato su funzioni (BaseGroupChatOrchestrator, GroupChatOrchestrator, AgentBasedGroupChatOrchestrator). Topologia a stella semplificata con modello di trasmissione.
• Handoff: rimosso il supporto di un singolo livello, coordinatore e executor personalizzato. Passato al modello di trasmissione con HandoffAgentExecutor.
• Sequenziale e simultaneo: meccanismo semplificato di informazioni sulle richieste per basarsi su flussi di lavoro secondari tramite 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.orchestrations import (
    GroupChatOrchestrator,
    HandoffAgentExecutor,
)

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

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

🔴 Opzioni introdotte come TypedDict e Generic

Richiesta pull:#3140

Le opzioni sono ora tipate usando TypedDict per migliorare la sicurezza dei tipi e il completamento automatico dell'IDE.

📖 Per istruzioni complete sulla migrazione, vedere la Guida alle opzioni tipite.

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 rimosso; context_provider su singolare; middleware deve essere un elenco

Richiesta pull:#3139

• display_name parametro rimosso dagli agenti
• context_providers rimane il parametro di sequenza plurale corrente per i provider
• middleware ora richiede un elenco (non accetta più una singola istanza)
• AggregateContextProvider rimosso dal codice (usare l'implementazione di esempio, se necessario)

Before:

from agent_framework.core import Agent, AggregateContextProvider

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

aggregate = AggregateContextProvider([provider1, provider2])

After:

from agent_framework import Agent

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

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

🔴 AgentRunResponse* rinominato in AgentResponse*

PR:#3207

AgentRunResponse e AgentRunResponseUpdate sono stati rinominati in AgentResponse e AgentResponseUpdate.

Before:

from agent_framework import AgentRunResponse, AgentRunResponseUpdate

After:

from agent_framework import AgentResponse, AgentResponseUpdate

🟡 Aggiunto il runtime del flusso di lavoro dichiarativo per workflow definiti tramite YAML

Richiesta pull:#2815

È stato aggiunto un runtime basato su grafo per l'esecuzione di flussi di lavoro YAML dichiarativi, abilitando l'orchestrazione multi-agente senza codice di runtime personalizzato.

🟡 Miglioramenti di caricamento/affidabilità MCP

Richiesta pull:#3154

Le integrazioni MCP hanno migliorato il comportamento di perdita di connessione, il supporto della paginazione durante il caricamento e le opzioni di controllo della rappresentazione.

🟡 Foundry A2ATool supporta ora le connessioni senza un URL di destinazione

Richiesta pull:#3127

A2ATool può ora risolvere le connessioni A2A supportate da Foundry tramite i metadati di connessione del progetto anche quando non è configurato un URL di destinazione diretto.

python-1.0.0b260107 (7 gennaio 2026)

Note sulla versione:python-1.0.0b260107

Nessuna modifica significativa in questa versione.

python-1.0.0b260106 (6 gennaio 2026)

Note sulla versione:python-1.0.0b260106

Nessuna modifica significativa in questa versione.

Tabella di riepilogo

Passaggi successivi