Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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
UserAuthorizationetauthHandlerNameafin 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 configurezBEARER_TOKENpour 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_endpointoptions (Python),useS2SEndpoint(JavaScript) etUseS2SEndpoint(.NET) sont ignorées, même lorsqu’elles sont définies surfalse. - 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/.defaultde 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_VERSIONconstante et leversionchamp surInputMessagesetOutputMessagessont supprimés.OutputMessage.finish_reasona la valeur par défaut"stop". -
JavaScript : L’instruction
A365_MESSAGE_SCHEMA_VERSIONexport et la propriétéversionsurInputMessagesetOutputMessagessont supprimées. UtilisezDEFAULT_FINISH_REASONà la place. Les messages de sortie que vous créez à partir de chaînes simples sont par défaut definish_reasonà"stop". -
.NET : La classe
MessageConstantset les propriétésInputMessages.VersionetOutputMessages.Versionsont supprimées.OutputMessage.FinishReasonest 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 :
InferenceCallDetailsnécessite unmodelouresponseModelnon vide. Si les deux sont manquants ou vides, la construction déclencheValueError. -
JavaScript :
InferenceDetails.providerNameest requis.modelest optionnel, mais vous devez fournir unmodelouresponseModelnon vide.InferenceScope.start()génère une exception si ces valeurs sont absentes. Il lève aussi une exception siendpoint.portn’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_completionetgenerate_content. Par exemple,Chat gpt-4devientchat gpt-4. Mettez à jour les filtres respectant la casse, les tableaux de bord et les alertes. -
JavaScript :
- Les plages d’inférence enregistrent
server.portlorsque le port est443. - Les segments de réponse de l’extension OpenAI indiquent le modèle servi dans
gen_ai.response.modelau lieu degen_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 dansgen_ai.response.model.
- Les plages d’inférence enregistrent
-
.NET : L’attribut
gen_ai.tool.argumentsest 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.