Migrer vers Microsoft Agent 365 SDK 2.0

Le SDK Microsoft Agent 365 2.0 est disponible pour Python, JavaScript et .NET. Cette version inclut des modifications avec rupture de compatibilité, mais la plupart concernent uniquement les packages d’observabilité obsolètes, et chaque modification a un chemin de migration direct. Utilisez cet article pour identifier les modifications qui s’appliquent à votre agent et mettre à jour votre code.

Résumé des changements cassants

Area Languages Activer Action
Notifications Python La AgentLifecycleEvent.USERDELETED valeur a changé. Mettez à jour le code qui compare avec la valeur de chaîne brute.
Extensions d’outils .NET authToken n’authentifie plus les serveurs MCP. Transmettez UserAuthorization et authHandlerName, ou définissez les variables d’environnement BEARER_TOKEN.
Durée Python get_observability_authentication_scope() retourne la portée /.default réservée à l’application seule. Utilisez la portée avec un résolveur de jetons uniquement pour l’application.
Export de l’observabilité Python, JavaScript, .NET L’export utilise toujours le point de terminaison d’API service à service (S2S) et nécessite un résolveur de jeton d’application uniquement. Remplacez le code de jeton délégué par un résolveur application uniquement.
Télémétrie d’observabilité Python, JavaScript, .NET Les attributs des messages, les noms d’attributs et la validation d’inférence ont changé. Mettez à jour le code, les requêtes et les tableaux de bord qui dépendent du format précédent.

Note

Les packages d’observabilité sont obsolètes. Le SDK 2.0 les publie toujours, mais il ne faut pas les utiliser pour de nouvelles intégrations. Au lieu de mettre à jour une intégration d’observabilité existante vers le SDK 2.0, envisagez de migrer vers la Microsoft OpenTelemetry Distro.

Mettez à jour vos paquets vers la version 2.0 du SDK Agent 365

Mettez à jour tous les paquets SDK Agent 365 de votre projet vers la version 2.0 en même temps. Pour la liste complète des paquets, voir paquets SDK Agent 365.

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

Ajoutez tous les autres packages Agent 365 que votre agent utilise, comme les extensions d’outils, à la même commande.

Notifications

Examinez la valeur mise à jour des événements du cycle de vie ainsi que les nouveaux événements disponibles dans le SDK 2.0.

Python : la valeur de l’événement de cycle de vie « utilisateur supprimé » a changé

La AgentLifecycleEvent.USERDELETED valeur est maintenant agenticuserdeleted. Dans les versions antérieures, la valeur était agenticuseridentitydeleted.

Si votre code compare l’événement du cycle de vie avec une chaîne brute, comparez plutôt le type d’événement minuscule avec la AgentLifecycleEvent valeur membre :

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

Nouveaux événements du cycle de vie

Le SDK 2.0 ajoute cinq événements et gestionnaires de cycle de vie à Python et JavaScript. Le SDK .NET les inclut déjà. Pour la liste complète, voir Événements du cycle de vie de l’agent.

Extensions d’outillage

Si vous utilisez les extensions d’outils .NET, mettez à jour la façon dont votre agent authentifie les serveurs MCP.

.NET : Le paramètre authToken n’authentifie plus les serveurs MCP

Ce changement s’applique aux extensions d’outils Noyau sémantique, Agent Framework et Azure AI Foundry.

Lorsque vous ne fournissez pas UserAuthorization et authHandlerName, l’extension utilise authToken uniquement pour découvrir les serveurs MCP via la passerelle d’outils. Il authentifie ensuite chaque serveur MCP uniquement avec un jeton provenant de la variable d’environnement BEARER_TOKEN_<SERVERNAME> ou BEARER_TOKEN. L’extension ignore et consigne tout serveur qui n’a pas de jeton, donc un agent qui s’est fié à authToken seul peut ne renvoyer aucun outil MCP sans erreur.

Ce changement affecte également les méthodes suivantes d’Azure AI Foundry, qui utilisent toujours ce chemin :

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

Pour migrer, utilisez l’une des options suivantes :

  • Authentification agentique (recommandée) : Transmettez UserAuthorization et authHandlerName afin que l’extension acquière des jetons via le flux agent 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);
    
  • Variables d’environnement : Définissez BEARER_TOKEN_<SERVERNAME> pour chaque serveur MCP, ou configurez BEARER_TOKEN pour utiliser un jeton pour tous les serveurs. Cette option convient au développement et aux essais locaux.

Pour plus d’informations, consultez Enregistrer des outils auprès de votre orchestrateur.

Runtime

Si votre agent Python utilise le package d’exécution pour obtenir le scope d’authentification d’observabilité, relisez le changement suivant.

Python : La portée d’authentification de l’observabilité est application uniquement

get_observability_authentication_scope() renvoie désormais le scope de la ressource /.default d’observabilité, api://9b975845-388f-4429-889e-eab1ef63949c/.default. Dans les versions antérieures, elle renvoyait le périmètre délégué Agent365.Observability.OtelWrite .

Utilisez cette portée d’autorisation uniquement pour obtenir un jeton d’application uniquement pour l’instance de l’agent exportateur. Pour plus de détails, voir L’exportation de l’observabilité utilise l’authentification uniquement par application.

Évolutions de l’observabilité dans le SDK 2.0

Les changements suivants s’appliquent aux paquets d’observabilité Agent 365 obsolètes dans les trois langages.

L’exportation d’observabilité utilise l’authentification uniquement par application

Le SDK 2.0 supprime l’authentification déléguée pour l’exportation d’observabilité :

  • L’exportateur envoie toujours la télémétrie vers l’itinéraire S2S. Les use_s2s_endpoint options (Python), useS2SEndpoint (JavaScript) et UseS2SEndpoint (.NET) sont ignorées, même lorsqu’elles sont définies sur false.
  • L’exportateur nécessite un résolveur de jeton qui renvoie un jeton d’application uniquement pour l’instance de l’agent exportateur. La route S2S rejette les jetons délégués.
  • Le cache de jetons d’hébergement acquiert des jetons d’application uniquement. Les méthodes d’enregistrement déléguées n’acquièrent plus de jetons.
  • En .NET, EnvironmentUtils.GetObservabilityAuthenticationScope() retourne le scope uniquement /.default de l’application au lieu du scope déléguéAgent365.Observability.OtelWrite.
Language Supprimer Utiliser à la place
Python AgenticTokenCache.register_observability(...), qui est maintenant un no-op enregistrant une erreur AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver)
JavaScript RefreshObservabilityToken avec un TurnContext et Authorization, et runWithExportToken pour les jetons d’exportation RefreshObservabilityToken(agentId, tenantId, tokenResolver) avec withTokenResolver(...) ou exporterOptions.tokenResolver
.NET AgenticTokenCache.RegisterObservability(...) avec AgenticTokenStruct, qui est désormais obsolète et provoque une erreur de compilateur ObservabilityTokenResolver avec AgenticTokenCache.RefreshObservabilityToken(...), et TokenResolver ou ContextualTokenResolver dans les options de l’exportateur

L'authentification de charge de travail applicative pour les serveurs MCP, Microsoft Graph et les flux OBO ne change pas.

Pour les exigences du résolveur et les exemples de code dans chaque langage, voir Résolveur de jetons.

Changements de format de télémétrie de l’observabilité

Mettez à jour le code qui crée la télémétrie ainsi que toute requête ou tableau de bord dépendant du format du message, des règles de validation ou des noms d’attributs décrits dans cette section.

Les attributs des messages sont des tableaux JSON

Les attributs gen_ai.input.messages et gen_ai.output.messages suivent désormais les conventions sémantiques de l’IA générative d’OpenTelemetry. Ils sérialisent sous forme d’un simple tableau JSON, comme [{"role": ..., "parts": [...]}], au lieu de l’enveloppe {"version": "0.1.0", "messages": [...]} .

  • Python : La A365_MESSAGE_SCHEMA_VERSION constante et le version champ sur InputMessages et OutputMessages sont supprimés. OutputMessage.finish_reason a la valeur par défaut "stop".
  • JavaScript : L’instruction A365_MESSAGE_SCHEMA_VERSION export et la propriété version sur InputMessages et OutputMessages sont supprimées. Utilisez DEFAULT_FINISH_REASON à la place. Les messages de sortie que vous créez à partir de chaînes simples sont par défaut de finish_reason à "stop".
  • .NET : La classe MessageConstants et les propriétés InputMessages.Version et OutputMessages.Version sont supprimées. OutputMessage.FinishReason est non nullable et a pour valeur par défaut "stop".

Mettez à jour tout code, requêtes ou tableaux de bord qui analysent ces attributs afin qu’ils attendent un tableau JSON.

Les détails d’inférence sont validés

  • Python :InferenceCallDetails nécessite un model ou responseModel non vide. Si les deux sont manquants ou vides, la construction déclenche ValueError.
  • JavaScript :InferenceDetails.providerName est requis. model est optionnel, mais vous devez fournir un model ou responseModel non vide. InferenceScope.start() génère une exception si ces valeurs sont absentes. Il lève aussi une exception si endpoint.port n’est pas un entier de 1 à 65535.

Changements de noms d’attributs et d’opérations

  • Python: Les noms d’opérations d’inférence et les préfixes de noms de span utilisent les valeurs canoniques OpenTelemetry en minuscules chat, text_completion et generate_content. Par exemple, Chat gpt-4 devient chat gpt-4. Mettez à jour les filtres respectant la casse, les tableaux de bord et les alertes.
  • JavaScript :
    • Les plages d’inférence enregistrent server.port lorsque le port est 443.
    • Les segments de réponse de l’extension OpenAI indiquent le modèle servi dans gen_ai.response.model au lieu de gen_ai.request.model.
    • L’extension LangChain n’utilise plus le modèle déployé comme solution de secours pour gen_ai.request.model. Il indique le modèle servi uniquement dans gen_ai.response.model.
  • .NET : L’attribut gen_ai.tool.arguments est renommé gen_ai.tool.call.arguments.

.NET: Modifications de l’interface IA365EtwLogger

L’interface IA365EtwLogger ajoute une méthode LogApplyGuardrail(...) et un paramètre optionnel Exception? error à chaque méthode Log* existante. Si vous implémentez IA365EtwLogger, mettez à jour votre implémentation et recompilez.