Eigene Agenten in Agent 365 registrieren: Python und Entra

Dein Agent läuft ausserhalb von Microsoft. Trotzdem müssen deine Administratoren wissen, dass es ihn gibt, wer ihn verantwortet und welche Identität er verwendet. Genau darum geht es in dieser Anleitung zur Registrierung in Agent 365.

In der Folge registriere ich eine kleine Python-Demo zur Ticket-Vorsortierung in Microsoft Agent 365, verknüpfe ihre Entra-Identität und prüfe die entstandenen Objekte in den Portalen. Interessant ist dabei nicht die nächste Agenten-Demo. Es ist das Zusammenspiel von Registereintrag, Identität und Aktivitäten – und die Stellen, an denen diese Dinge voneinander getrennt bleiben.

Die Folge ansehen

Das Video ist auf Deutsch und dauert rund elf Minuten. Die wichtigsten Abschnitte:

• 00:49: Agent Card und Registrierungs-API;
• 01:42: das Python-Skript für die Registrierung;
• 02:55: den Eintrag im Microsoft 365 Admin Center prüfen;
• 03:58: Blueprint, Agentenidentität und Berechtigungen;
• 07:14: die Identität erstellen und mit dem Register verknüpfen;
• 08:39: Telemetrie vorbereiten und die Aktivitäten einordnen.

Wenn du das Portal noch nicht kennst, starte mit meinem Überblick zu Microsoft Agent 365. Wie der Agent selbst entsteht, zeige ich im vorherigen Foundry-Python-Walkthrough.

Was eine Registrierung in Agent 365 leistet – und was nicht

Ich möchte drei Dinge klar voneinander trennen:

Das Register beschreibt den Agenten: Name, Fähigkeiten, Herkunft und verantwortliche Person. Die Entra-Identität liefert eine Identität mit einem Berechtigungsmodell. Laufzeitnachweise zeigen, was bei einer tatsächlichen Ausführung passiert ist.

Der erste Punkt beweist nicht, dass die anderen beiden funktionieren. Eine Registrierung stellt die Python-Anwendung nicht bereit, startet keinen Prozess und prüft keinen Tool-Aufruf. Sie belegt auch nicht automatisch, dass alle Sicherheits-, Compliance- und Monitoring-Kontrollen eingerichtet sind.

Das sieht man in der Aufnahme: Der erste Registereintrag existiert bereits, bevor ich eine Entra-Agentenidentität damit verknüpfe. Wer einen Inventareintrag schon für eine fertige Integration hält, übersieht diesen fehlenden Schritt.

Bevor du loslegst

Nutze einen Entwicklungstenant und fiktive Daten. Contoso Ticket-Triage beschreibt in der Demo einen externen Agenten zur Vorsortierung von IT-Tickets. Er genehmigt keine Änderungen und führt keine produktiven Remediations aus.

Für den Registrierungsaufruf dokumentiert Microsoft aktuell AgentRegistration.ReadWrite.All für unterstützte Geschäfts- oder Schulkonten und für Anwendungszugriff. In der Aufnahme verwende ich POST https://graph.microsoft.com/beta/copilot/agentRegistrations. Diese Beta-API kann sich ändern und wird laut Microsoft nicht für produktive Anwendungen unterstützt. Prüfe vor einem eigenen Aufruf die aktuelle Agent Registry API-Referenz.

Zusätzlich brauchst du Zugriff auf die entsprechenden Agent-365- und Entra-Funktionen in deinem Tenant. Kläre Lizenzen, Verfügbarkeit, Administratorrollen und Einwilligungen vorher. Ein erfolgreicher Registrierungsaufruf ersetzt diese Prüfung nicht.

Schritt 1: den Agenten mit einer Agent Card beschreiben

Die Agent Card ist ein kleines Metadatendokument, das erklärt, was der Agent ist. In der Aufnahme schaue ich mir agent-card.json an, bevor ich Änderungen ausführe.

Vier Bereiche würde ich zuerst prüfen:

• Name und Version: Kann ein Administrator diesen Agenten von seiner nächsten Version unterscheiden?
• Beschreibung und Anbieter: Ist der Zweck auch ohne Erklärung durch den Entwickler verständlich?
• Ein- und Ausgabe sowie Fähigkeiten: Entspricht die Beschreibung der wirklichen Implementierung?
• Skills und Wissensquellen: Was kann der Agent, und woher kommen seine Informationen?

Beschreibe den Zweck konkret. „Sortiert fiktive IT-Tickets für eine Demo“ hilft mehr als „autonome Enterprise-KI“. Nenne keine Schreibfunktionen, die die Anwendung nicht ausführen kann. Zugangsdaten und Ticketinhalte gehören ebenfalls nicht in die Karte.

Schritt 2: den Registereintrag erstellen und prüfen

Das gezeigte Registrierungs-Skript hat einen bewusst gesetzten Schalter für Änderungen. Zuerst prüfe ich den geplanten Request, danach erstelle ich den Eintrag mit --apply. Das ist eine Funktion meines Demo-Skripts, kein eingebauter Dry-Run-Modus von Microsoft Graph.

Das Skript speichert die zurückgegebene Registrierungs-ID lokal. So kann ich mit demselben Demo-Eintrag weiterarbeiten, statt bei jeder Ausführung einen neuen anzulegen. Daraus entsteht keine serverseitige Idempotenzgarantie. Prüfe nach einem Timeout den Tenant-Zustand, bevor du den Create-Aufruf wiederholst.

Ausschnitt aus der Aufnahme: Der Eintrag ist sichtbar, das Feld für die Agentenidentität ist zu diesem Zeitpunkt noch leer.

Vergleiche Name, Beschreibung, Besitzer und Herkunft mit dem beabsichtigten Request. Halte die Registrierungs-ID getrennt von den späteren IDs für Identität und Blueprint. Ähnlich aussehende GUIDs sind nicht austauschbar.

Schritt 3: die Entra-Identität ergänzen und verknüpfen

Im nächsten Teil entstehen ein Agent Identity Blueprint, sein Blueprint Principal und die einzelne Agentenidentität. Anschliessend verknüpfe ich den Registereintrag mit den zugehörigen Identitätsobjekten. Das Ergebnis prüfe ich sowohl im Microsoft 365 Admin Center als auch in Entra.

Vergleiche für eine neue Implementierung diese direkte API-Demo mit Microsofts aktuell empfohlenem Weg. Die Blueprint-Dokumentation zeigt inzwischen v1.0-Endpunkte für Identitäten und empfiehlt für neue Projekte das Microsoft 365 Agents SDK. Das ändert nicht den Beta-Status des separaten Register-Endpunkts aus dieser Folge.

Die temporären lokalen Zugangsdaten der Demo würde ich nicht unverändert in die Produktion übernehmen. Wähle ein geeignetes Managed-Identity- oder Federation-Konzept, halte Berechtigungen eng und lege Zuständigkeiten für Rotation und Ausserbetriebnahme fest. Prüfe jede Berechtigung einzeln: Eine Identität anzulegen und ihr Zugriff auf Geschäftsdaten zu geben sind unterschiedliche Entscheidungen.

Schritt 4: Telemetrie separat nachweisen

Der letzte Abschnitt bereitet ein OpenTelemetry-Beispiel vor. Ein Detail ist wichtig: Bei der Ausführung am Ende der Aufnahme verwende ich den Schalter --live nicht. Die bereits im Portal sichtbare Aktivität stammt aus einem früheren Test.

Die Folge zeigt damit die Registrierung und die Arbeit an der Identität. Sie beweist nicht, dass das letzte Telemetrie-Beispiel erfolgreich ein neues Ereignis übertragen hat.

Starte für deinen eigenen Test eine kontrollierte Ausführung mit fiktiven Eingaben. Notiere Zeitpunkt und Korrelationskennung und finde genau diese Ausführung am Ziel wieder. Prüfe Fehler genauso wie erfolgreiche Läufe. Ein gefüllter Aktivitäten-Bildschirm allein verrät nicht, ob der gerade gestartete Lauf angekommen ist.

Meine Prüfung vor dem Abschluss

Für jeden dieser Punkte möchte ich einen Nachweis sehen:

1. Der beabsichtigte Agent steht genau einmal im Register, mit passenden Metadaten und Verantwortlichen.
2. Agentenidentität und Blueprint passen zu den verknüpften Objekten in Entra.
3. Die Anwendung nutzt die vorgesehene Identität und nicht die Zugangsdaten eines Entwicklers.
4. Eine erlaubte Aktion funktioniert, eine Aktion ausserhalb der Berechtigungen wird abgewiesen.
5. Eine neue Testausführung lässt sich im erwarteten Telemetrieziel wiederfinden.
6. Für Registereintrag, Anwendung, Zugangsdaten und Identitätsobjekte gibt es einen dokumentierten Ablauf zur Ausserbetriebnahme.

Das sind Abnahmeprüfungen für deine Umgebung. Sie sind keine Behauptung, dass das kurze Video eine produktive Bereitstellung vollständig validiert.

Häufige Fragen

Kann ein ausserhalb von Microsoft betriebener Agent in Agent 365 erscheinen?

Genau dieses Szenario zeigt die Folge: Ein externer Demo-Agent erhält einen Registereintrag und eine verknüpfte Entra-Identität. Hosting und Ausführung bleiben davon getrennt.

Ist die Registrierung dasselbe wie das Erstellen eines Foundry-Agenten?

Nein. Mit der Anwendung oder dem Foundry-Agenten entsteht die eigentliche Implementierung. Die Agent-365-Registrierung macht Metadaten für Administratoren sichtbar. Identität und Telemetrie anzubinden erfordert weitere Arbeit.

Sollte ich die API-Versionen aus der Aufnahme unverändert übernehmen?

Nein. Prüfe vor der Ausführung die verlinkten Referenzen und deinen Tenant. Register und Identität haben jeweils eigene Versions- und Verfügbarkeitsbedingungen.

Was ich daraus mitnehme

Für mich ist der sinnvolle Endzustand ein Agent, den Administratoren erkennen und mit seiner tatsächlichen Ausführung verbinden können – nicht nur eine weitere Zeile im Portal. Starte mit einer klaren Agent Card, prüfe die Identitätsverknüpfung und weise eine neue Ausführung nach, bevor du die Integration erweiterst.

Stay healthy, Cheers Jannik