Passa a Microsoft Agent 365 SDK 2.0

Microsoft Agent 365 SDK 2.0 è disponibile per Python, JavaScript e .NET. Questa versione include modifiche incompatibili, ma la maggior parte di esse riguarda solo i pacchetti di osservabilità obsoleti, e ogni modifica ha un percorso di migrazione diretto. Usa questo articolo per trovare le modifiche che si applicano al tuo agente e aggiornare il tuo codice.

Riepilogo delle modifiche incompatibili

Area Languages Cambia Action
Notifiche Python Il AgentLifecycleEvent.USERDELETED valore è cambiato. Aggiorna il codice che confronta con il valore letterale della stringa.
Estensioni degli strumenti .NET authToken non autentica più i server MCP. Passare UserAuthorization e authHandlerName, oppure impostare le variabili di ambiente BEARER_TOKEN.
runtime Python get_observability_authentication_scope() restituisce l'ambito per la sola app /.default. Usa lo scope con un resolver di token solo per app.
Esportazione di osservabilità Python, JavaScript, .NET L'esportazione utilizza sempre l'endpoint service-to-service (S2S) e richiede un resolver di token solo app. Sostituisci il codice dei token delegati con un resolver solo app.
Telemetria dell'osservabilità Python, JavaScript, .NET Attributi dei messaggi, nomi degli attributi e validazione dell'inferenza sono cambiati. Aggiorna codice, query e dashboard che dipendono dal formato precedente.

Note

I pacchetti di osservabilità sono obsoleti. SDK 2.0 li pubblica ancora, ma non usarli per nuove integrazioni. Invece di aggiornare un'integrazione di osservabilità esistente verso SDK 2.0, considera di migrare a Microsoft OpenTelemetry Distro.

Aggiorna i tuoi pacchetti all'Agent 365 SDK 2.0

Aggiorna contemporaneamente ogni pacchetto SDK Agent 365 nel tuo progetto alla versione 2.0. Per l'elenco completo dei pacchetti, vedi Agent 365 SDK packages.

pip install --upgrade microsoft-agents-a365-notifications microsoft-agents-a365-tooling microsoft-agents-a365-runtime

Aggiungi qualsiasi altro pacchetto Agent 365 che il tuo agente utilizza, come le estensioni degli strumenti, allo stesso comando.

Notifications

Rivedi il valore aggiornato degli eventi del ciclo di vita e i nuovi eventi disponibili nell'SDK 2.0.

Python: valore modificato dell'evento del ciclo di vita dell'utente eliminato

Il AgentLifecycleEvent.USERDELETED valore è ora agenticuserdeleted. Nelle versioni precedenti, il valore era agenticuseridentitydeleted.

Se il tuo codice confronta l'evento del ciclo di vita con una stringa grezza, confronta invece il tipo di evento in minuscolo con il valore del membro AgentLifecycleEvent:

from microsoft_agents_a365.notifications import AgentLifecycleEvent, AgentNotification

agent_notification = AgentNotification(app)

@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
    event_type = (notification.activity.value_type or "").lower()
    if event_type == AgentLifecycleEvent.USERDELETED.value:
        await context.send_activity("User identity deleted")

Nuovi eventi del ciclo di vita

SDK 2.0 aggiunge cinque eventi del ciclo di vita e gestori del ciclo di vita a Python e JavaScript. L'SDK di .NET li include già. Per l'elenco completo, vedi eventi del ciclo di vita dell'agente.

Estensioni degli strumenti

Se usi le estensioni degli strumenti .NET, aggiorna il modo in cui il tuo agente si autentica con i server MCP.

.NET: Il parametro authToken non autentica più i server MCP

Questa modifica si applica alle estensioni degli strumenti Kernel semantico, Agent Framework e Azure AI Foundry.

Quando non fornisci UserAuthorization e authHandlerName, l'estensione usa authToken solo per scoprire i server MCP tramite il gateway degli strumenti. Successivamente autentica ogni server MCP solo con un token della variabile di ambiente BEARER_TOKEN_<SERVERNAME> o BEARER_TOKEN. L'estensione salta e registra qualsiasi server che non abbia un token, quindi un agente che si basava esclusivamente su authToken può non restituire alcuno strumento MCP senza generare un errore.

Questo cambiamento riguarda anche i seguenti metodi di Azure AI Foundry, che utilizzano sempre questo percorso:

  • AddToolServersToAgent (sincrono)
  • GetMcpToolDefinitionsAndResourcesAsync(agentInstanceId, authToken, turnContext)

Per migrare, utilizza una delle seguenti opzioni:

  • Autenticazione agentica (consigliata): Passa UserAuthorization e authHandlerName in modo che l'estensione acquisisca token tramite il flusso agentico on-behalf-of (OBO).

    // Semantic Kernel
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);

// Azure AI Foundry: use the async method instead of AddToolServersToAgent
await toolService.AddToolServersToAgentAsync(agentClient, userAuthorization, authHandlerName, turnContext);

  • Variabili di ambiente: Impostate BEARER_TOKEN_<SERVERNAME> per ogni server MCP, oppure impostate BEARER_TOKEN per usare un token per tutti i server. Questa opzione è adatta allo sviluppo locale e ai test locali.

Per maggiori informazioni, consulta Registra gli strumenti con il tuo orchestratore.

Runtime

Se il tuo agente Python utilizza il pacchetto runtime per ottenere l'ambito di autenticazione dell'osservabilità, rivedi la seguente modifica.

Python: L'ambito di autenticazione dell'osservabilità è solo per app

get_observability_authentication_scope() restituisce ora l'ambito /.default della risorsa di osservabilità, api://9b975845-388f-4429-889e-eab1ef63949c/.default. Nelle versioni precedenti, restituiva l'ambito delegato Agent365.Observability.OtelWrite .

Usa questo ambito solo per acquisire un token solo per l'app dell'istanza dell'agente esportante. Per dettagli, vedi L'esportazione dell'osservabilità usa l'autenticazione solo app.

Modifiche all'osservabilità in SDK 2.0

Le seguenti modifiche si applicano ai pacchetti di observability Agent 365 obsoleti in tutte e tre le lingue.

L'esportazione dell'osservabilità utilizza l'autenticazione solo tramite app

SDK 2.0 rimuove l'autenticazione delegata per l'esportazione di osservabilità:

  • L'esportatore invia sempre la telemetria alla rotta S2S. Le use_s2s_endpoint opzioni (Python), useS2SEndpoint (JavaScript) e UseS2SEndpoint (.NET) vengono ignorate, anche se impostate su false.
  • L'esportatore richiede un resolver di token che restituisca un token esclusivo dell'app per l'istanza dell'agente di esportazione. La rotta S2S rifiuta i token delegati.
  • La cache di token di hosting acquisisce token per la sola app. I metodi di registrazione delegati non acquisiscono più token.
  • In .NET, EnvironmentUtils.GetObservabilityAuthenticationScope() restituisce l'ambito solo app /.default invece dell'ambito delegato Agent365.Observability.OtelWrite.
Language Remove Usare invece
Python AgenticTokenCache.register_observability(...), che ora è un no-op che registra un errore AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver)
JavaScript RefreshObservabilityToken con un TurnContext e Authorization, e runWithExportToken per i token dell'esportatore RefreshObservabilityToken(agentId, tenantId, tokenResolver) con withTokenResolver(...) o exporterOptions.tokenResolver
.NET AgenticTokenCache.RegisterObservability(...) con AgenticTokenStruct, che ora è obsoleto e causa un errore del compilatore ObservabilityTokenResolver con AgenticTokenCache.RefreshObservabilityToken(...), e TokenResolver o ContextualTokenResolver sulle opzioni esportatore

L'autenticazione del carico di lavoro per server MCP, Microsoft Graph e flussi OBO non cambia.

Per i requisiti del resolver e gli esempi di codice in ciascun linguaggio, vedi Token resolver.

Cambiamenti nel formato della telemetria dell'osservabilità

Aggiorna il codice che crea la telemetria e qualsiasi query o dashboard che dipenda dal formato del messaggio, dalle regole di validazione o dai nomi degli attributi descritti in questa sezione.

Gli attributi dei messaggi sono array JSON

L'attributo gen_ai.input.messages e l'attributo gen_ai.output.messages ora seguono le convenzioni semantiche di OpenTelemetry per l'IA generativa. Serializzano come un semplice array JSON, come [{"role": ..., "parts": [...]}], invece che come il {"version": "0.1.0", "messages": [...]} wrapper.

  • Python: La A365_MESSAGE_SCHEMA_VERSION costante e il version campo su InputMessages e OutputMessages vengono rimossi. Il valore predefinito di OutputMessage.finish_reason è "stop".
  • JavaScript: L'esportazione A365_MESSAGE_SCHEMA_VERSION e la version proprietà su InputMessages e OutputMessages vengono rimosse. Utilizzare invece DEFAULT_FINISH_REASON. I messaggi di output che crei da stringhe semplici vengono impostati per impostazione predefinita da finish_reason a "stop".
  • .NET: La classe MessageConstants e le proprietà InputMessages.Version e OutputMessages.Version vengono rimosse. OutputMessage.FinishReason non è nullabile e di default è "stop".

Aggiorna qualsiasi codice, query o dashboard che analizzano questi attributi in modo che si aspettino un array JSON.

I dettagli di inferenza sono validati

  • Python:InferenceCallDetails richiede un non blank model o responseModel. Se entrambi sono mancanti o vuoti, la costruzione solleva ValueError.
  • JavaScript:InferenceDetails.providerName è richiesto. model è opzionale, ma devi fornire un non blank model o responseModel. InferenceScope.start() lancia se questi valori sono mancanti. Inoltre, lancia se endpoint.port non è un intero da 1 a 65535.

Modifiche al nome dell’attributo e dell’operazione

  • Python: I nomi delle operazioni di inferenza e i prefissi dei nomi degli span utilizzano i valori canonici minuscoli di OpenTelemetry chat, text_completion e generate_content. Ad esempio, Chat gpt-4 diventa chat gpt-4. Aggiorna filtri con distinzione tra maiuscole e minuscole, dashboard e avvisi.
  • JavaScript:
    • L'inferenza riguarda il record server.port quando la porta è 443.
    • Gli span di risposta dell'estensione OpenAI riportano il modello servito in gen_ai.response.model invece di gen_ai.request.model.
    • L'estensione LangChain non utilizza più il modello servito come fallback per gen_ai.request.model. Riporta il modello servito solo in gen_ai.response.model.
  • .NET: L'attributo gen_ai.tool.arguments viene rinominato in gen_ai.tool.call.arguments.

.NET: Cambiamenti all'interfaccia IA365EtwLogger

L'interfaccia IA365EtwLogger aggiunge un metodo LogApplyGuardrail(...) e un parametro opzionale Exception? error su ogni metodo Log* esistente. Se implementi IA365EtwLogger, aggiorna la tua implementazione e ricompila.

Contenuti correlati

  • Ultimo aggiornamento: