Migration zu Microsoft Agent 365 SDK 2.0

Das Microsoft Agent 365 SDK 2.0 ist für Python, JavaScript und .NET verfügbar. Diese Version enthält inkompatible Änderungen, aber die meisten betreffen nur die veralteten Observability-Pakete, und jede Änderung hat einen direkten Migrationspfad. Nutzen Sie diesen Artikel, um die Änderungen zu finden, die für Ihren Agenten gelten, und um Ihren Code zu aktualisieren.

Zusammenfassung der Breaking Changes

Region Languages Ändern Action
Benachrichtigungen Python Der Wert AgentLifecycleEvent.USERDELETED änderte sich. Aktualisieren Sie Code, der mit dem rohen String-Wert vergleicht.
Werkzeugerweiterungen .NET authToken authentifiziert MCP-Server nicht länger. Pass UserAuthorization und authHandlerName, oder setze BEARER_TOKEN Umgebungsvariablen.
Laufzeit Python get_observability_authentication_scope() gibt das reine /.default App-Scope zurück. Nutze den Scope mit einem App-Only-Token-Resolver.
Observabilitätsexport Python, JavaScript, .NET Der Export verwendet immer den Service-to-Service-(S2S)-Endpunkt und erfordert einen App-only-Token-Resolver. Ersetzen Sie Code für delegierte Token durch einen reinen App-Resolver.
Observability-Telemetrie Python, JavaScript, .NET Nachrichtenattribute, Attributnamen und Inferenzvalidierung wurden geändert. Aktualisieren Sie Code, Abfragen und Dashboards, die auf dem früheren Format basieren.

Note

Die Observability-Pakete sind als veraltet markiert. SDK 2.0 stellt sie weiterhin bereit, aber nutzt sie nicht für neue Integrationen. Anstatt eine bestehende Observability-Integration auf SDK 2.0 zu aktualisieren, sollten Sie in Erwägung ziehen, auf die Microsoft OpenTelemetry Distro zu migrieren.

Aktualisieren Sie Ihre Pakete auf Agent 365 SDK 2.0

Aktualisieren Sie jedes Agent 365 SDK-Paket in Ihrem Projekt gleichzeitig auf Version 2.0. Für die vollständige Liste der Pakete siehe Agent 365 SDK Pakete.

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

Füge alle anderen Agent-365-Pakete, die dein Agent verwendet, wie z. B. Tooling-Erweiterungen, demselben Befehl hinzu.

Benachrichtigungen

Überprüfen Sie den aktualisierten Lebenszyklus-Ereigniswert und die neuen Ereignisse, die in SDK 2.0 verfügbar sind.

Python: Wert des Lebenszyklusereignisses „Benutzer gelöscht“ geändert

Der Wert AgentLifecycleEvent.USERDELETED ist jetzt agenticuserdeleted. In früheren Versionen war der Wert agenticuseridentitydeleted.

Wenn Ihr Code das Lebenszyklusereignis mit einer rohen Zeichenkette vergleicht, vergleichen Sie stattdessen den Eventtyp in Kleinbuchstaben mit dem AgentLifecycleEvent Mitgliedswert:

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

Neue Lebenszyklusereignisse

SDK 2.0 fügt Python und JavaScript fünf Lebenszyklusereignisse und Handler hinzu. Das .NET SDK enthält sie bereits. Die vollständige Liste finden Sie unter Agentenlebenszyklus-Ereignisse.

Werkzeugerweiterungen

Wenn Sie die .NET-Toolingerweiterungen verwenden, aktualisieren Sie, wie sich Ihr Agent bei MCP-Servern authentifiziert.

.NET: Der AuthToken-Parameter authentifiziert MCP-Server nicht mehr

Diese Änderung gilt für die Semantischer Kernel, das Agent Framework und die Azure AI Foundry Tooling-Erweiterungen.

Wenn du nicht UserAuthorization und authHandlerName lieferst, verwendet die Erweiterung authToken nur, um MCP-Server über das Tooling-Gateway zu entdecken. Anschließend authentifiziert es jeden MCP-Server nur mit einem Token aus der Umgebungsvariable BEARER_TOKEN_<SERVERNAME> oder BEARER_TOKEN. Die Erweiterung überspringt und protokolliert jeden Server, der kein Token hat, sodass ein Agent, der sich allein auf authToken verlassen hat, ohne Fehler keine MCP-Tools zurückgeben kann.

Diese Änderung betrifft auch die folgenden Azure AI Foundry -Methoden, die immer diesen Pfad verwenden:

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

Um zu migrieren, verwenden Sie eine der folgenden Optionen:

  • Agentische Authentifizierung (empfohlen): Übergeben Sie UserAuthorization und authHandlerName, damit die Erweiterung Token durch den agentischen On-Behalf-Of-(OBO)-Flow erhält.

    // 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);

  • Umgebungsvariablen: Legen Sie BEARER_TOKEN_<SERVERNAME> für jeden MCP-Server fest oder BEARER_TOKEN, um ein Token für alle Server zu verwenden. Diese Option eignet sich für lokale Entwicklung und Tests.

Weitere Informationen finden Sie unter Werkzeuge bei Ihrem Orchestrator registrieren.

Runtime

Wenn Ihr Python-Agent das Laufzeitpaket verwendet, um den Observability-Authentifizierungsbereich zu erhalten, prüfen Sie die folgende Änderung.

Python: Der Umfang der Observability-Authentifizierung ist nur für Apps

get_observability_authentication_scope() gibt nun den Observability-Ressourcenbereich /.default zurück, api://9b975845-388f-4429-889e-eab1ef63949c/.default. In früheren Versionen wurde der delegierte Agent365.Observability.OtelWrite Scope zurückgegeben.

Nutze diesen Scope nur, um ein reines App-Token für die exportierende Agenteninstanz zu erhalten. Details finden Sie unter Observability-Export verwendet reine App-Authentifizierung.

Beobachtbarkeitsänderungen in SDK 2.0

Die folgenden Änderungen gelten für die veralteten Agent-365-Observabilitätspakete in allen drei Sprachen.

Der Export von Observability verwendet nur App-Authentifizierung

SDK 2.0 entfernt die delegierte Authentifizierung für den Export der Observabilität:

  • Der Exporteur sendet immer Telemetrie an die S2S-Route. Die use_s2s_endpoint Optionen (Python), useS2SEndpoint (JavaScript) und UseS2SEndpoint (.NET) werden ignoriert, selbst wenn sie auf falsegesetzt sind.
  • Der Exporter benötigt einen Token-Resolver, der für die Instanz des exportierenden Agents ein nur für die App bestimmtes Token zurückgibt. Die S2S-Route lehnt delegierte Token ab.
  • Der Hosting-Token-Cache erwirbt App-Token. Die delegierten Registrierungsmethoden rufen keine Token mehr ab.
  • In .NET gibt /.default den nur für die App verfügbaren EnvironmentUtils.GetObservabilityAuthenticationScope()-Scope statt des delegierten Agent365.Observability.OtelWrite-Scope zurück.
Language Entfernen Stattdessen verwenden
Python AgenticTokenCache.register_observability(...), das jetzt ein No-Op ist und einen Fehler protokolliert AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver)
JavaScript RefreshObservabilityToken mit einem TurnContext und Authorization, und runWithExportToken für Exporter-Tokens RefreshObservabilityToken(agentId, tenantId, tokenResolver) mit withTokenResolver(...) oder exporterOptions.tokenResolver
.NET AgenticTokenCache.RegisterObservability(...) mit AgenticTokenStruct, was nun veraltet ist und einen Compilerfehler verursacht ObservabilityTokenResolver mit AgenticTokenCache.RefreshObservabilityToken(...), und TokenResolver oder ContextualTokenResolver in den Exportoptionen

Die Workload-Authentifizierung für MCP-Server, Microsoft Graph und OBO-Flows ändert sich nicht.

Für Resolver-Anforderungen und Codebeispiele in jeder Sprache siehe Token Resolver.

Änderungen des Observabilitäts-Telemetrieformats

Aktualisieren Sie den Code zur Erstellung von Telemetriedaten sowie alle Abfragen oder Dashboards, die vom Nachrichtenformat, den Validierungsregeln oder den in diesem Abschnitt beschriebenen Attributnamen abhängen.

Nachrichtenattribute sind JSON-Arrays

Die Attribute gen_ai.output.messages und gen_ai.input.messages folgen nun den semantischen Konventionen für generative KI von OpenTelemetry. Sie serialisieren als einfaches JSON-Array, wie zum Beispiel [{"role": ..., "parts": [...]}], statt als Wrapper {"version": "0.1.0", "messages": [...]} .

  • Python: Die Konstante A365_MESSAGE_SCHEMA_VERSION und das version Feld auf InputMessages und OutputMessages wurden entfernt. Der Standardwert von OutputMessage.finish_reason ist "stop".
  • JavaScript: Der Export A365_MESSAGE_SCHEMA_VERSION und die version Eigenschaft auf InputMessages und OutputMessages wurden entfernt. Verwenden Sie stattdessen DEFAULT_FINISH_REASON. Ausgabe-Nachrichten, die du aus einfachen Strings erstellst, sind standardmäßig von finish_reason bis "stop".
  • .NET: Die Klasse MessageConstants und die InputMessages.Version- und OutputMessages.Version-Eigenschaften werden entfernt. OutputMessage.FinishReason ist nicht nullierbar und standardmäßig auf "stop" festgelegt.

Aktualisieren Sie Code, Abfragen oder Dashboards, die diese Attribute analysieren, sodass sie ein JSON-Array erwarten.

Inferenzdetails werden validiert

  • Python:InferenceCallDetails erfordert eine nicht leere model oder responseModel. Wenn beide fehlen oder leer sind, löst die Konstruktion ValueError aus.
  • JavaScript:InferenceDetails.providerName ist erforderlich. model ist optional, aber du musst einen nicht leeren Wert für model oder responseModel angeben. InferenceScope.start() wirft, wenn diese Werte fehlen. Es wirft außerdem, wenn endpoint.port keine ganze Zahl von 1 bis 65535 ist.

Attribut- und Operationsnamensänderungen

  • Python: Inferenzoperationennamen und Span-Name-Präfixe verwenden die kanonischen Kleinbuchstaben der OpenTelemetry-Werte chat, text_completion und generate_content. Chat gpt-4 wird beispielsweise zu chat gpt-4. Aktualisieren Sie die die Groß-/Kleinschreibung beachtenden Filter, Dashboards und Benachrichtigungen.
  • JavaScript:
    • Die Inferenz umfasst den Eintrag, server.port wenn der Port 443 ist.
    • OpenAI-Erweiterungs-Antwortspannen melden das bereitgestellte Modell in gen_ai.response.model statt gen_ai.request.model.
    • Die LangChain-Erweiterung verwendet das bereitgestellte Modell nicht mehr als Fallback für gen_ai.request.model. Es meldet das bereitgestellte Modell nur in gen_ai.response.model.
  • .NET: Das Attribut gen_ai.tool.arguments wird in gen_ai.tool.call.arguments umbenannt.

Änderungen an der Schnittstelle .NET: IA365EtwLogger

Die IA365EtwLogger Schnittstelle fügt jeder bestehenden Exception? error Methode eine Log* Methode und einen optionalen LogApplyGuardrail(...) Parameter hinzu. Wenn du IA365EtwLogger implementierst, aktualisiere deine Implementierung und kompiliere neu.

Verwandte Inhalte

  • Zuletzt aktualisiert um