Freigeben über

Schnellstartanleitung: Einrichten und Ausführen des Beispiel-Agents Python Agent Framework

In dieser Schnellstartanleitung werden Sie durch die Einrichtung eines funktionierenden Python Agent Framework-Agents unter Verwendung der Agent 365-Tools, Benachrichtigungen und Einblicke geführt und lernen, wie Sie den Agents mit Agents Playground und Teams testen können.

Voraussetzungen

  • Wenn Sie beabsichtigen, Visual Studio Code zu verwenden, muss .NET installiert sein. (.NET 8.0 wird empfohlen.)

  • Python 3.11+ ist installiert

  • UV-Paket-Manager ist installiert. Installieren Sie dies in einem Terminal mithilfe von pip install uv.

  • Microsoft Agents Toolkit/Agent Framework-Abhängigkeiten

    Das in der exemplarischen Vorgehensweise verwendete Beispiel basiert auf den Agent Framework-Bibliotheken, die über das Microsoft 365 Agents Toolkit oder ATK bereitgestellt werden. Sie werden automatisch installiert, wenn Sie die Agents Toolkit-Erweiterung in VS Code verwenden, um das Beispiel zu erstellen. Alternativ können Sie das Paket auch manuell mit dem folgenden Befehl installieren:

    uv pip install -e . --find-links ../dist --pre

  • Zugriff auf GitHub

  • Ein vorhandenes KI-Agent-Projekt. Diese Schnellstartanleitung verwendet einen Agent 365-Beispiel-Agent aus dem Microsoft 365 Agent-Toolkit, das in VS Code auch als ATK bezeichnet wird.

  • A365 CLI

  • Agent-Identitätsauthentifizierung

Einrichten des Agent-Frameworks + Python-Beispiels aus dem Microsoft 365 Agents Toolkit

Um alle Vorbereitungen zu treffen, installieren Sie das Microsoft 365 Agents Toolkit in VS Code, öffnen Sie die Beispielgalerie und erstellen Sie das Agent-Framework + Python-Beispiel lokal, damit Sie es später konfigurieren und ausführen können. Die folgenden Screenshots zeigen, was erwartungsgemäß angezeigt werden sollte.

  1. Öffnen Sie Visual Studio Code. Öffnen Sie dann den Bereich Erweiterungen und wählen Sie Strg+Umschalt+X.

  2. Geben Sie in der Suchleiste Agents Toolkit ein.
    Das Ergebnis sollte hier im Screenshot angezeigt werden:

    Screenshot der Erweiterungs-Marketplace-Suche nach Agents Toolkit.

  3. Wählen Sie Microsoft 365 Agents Toolkit aus.

  4. Wählen Sie Installieren aus.

    VS Code zeigt die Detailansicht der Erweiterung an, ähnlich wie folgt:

    Screenshot der Seite „Erweiterungsdetails“ mit den Schaltflächen „Installieren“ und „Aktivieren“.

  5. Nach der Installation wird das Symbol M365 Agents Toolkit in der linken Navigationsleiste angezeigt.

  6. Wählen Sie es aus, um den Willkommensbildschirm zu öffnen.

    Nun sollten Optionen wie Deklarativen Agent erstellen, Neuen Agent/App erstellen und Beispiele anzeigen angezeigt werden, wie hier dargestellt:

    Screenshot der Willkommensansicht des Toolkits mit den Optionen „Deklarativen Agent erstellen“, „Neuen Agent oder App erstellen“ oder „Beispiele anzeigen“.

  7. Wählen Sie Beispiele anzeigen aus.

  8. Scrollen Sie in der Beispielliste, um das Agent-Framework + Python-Agentbeispiel zu finden.

  9. Wählen Sie ihn aus.

    Es werden zwei Optionen angezeigt: Erstellen (lokales Grundgerüst) oder Auf GitHub anzeigen.

  10. Wählen Sie Erstellen.

    Screenshot des Agent Framework-Agents mit A365-SDK-Python-Verwendungsbeispiel.

  11. Wenn Sie dazu aufgefordert werden, wählen Sie einen Ordner auf Ihrem Computer aus, in dem das Beispiel generiert werden soll. Beispiel: C:\A365-python-sample

    Das Toolkit erstellt das Agent-Framework + Python-Beispiel in einem Unterordner (z. B. sample_agent) und öffnet es anschließend automatisch in VS Code.

    Sobald die Gerüstkonstruktion abgeschlossen ist, verfügen Sie nun über ein voll funktionsfähiges Agent-Framework sowie ein Python-Agent-Projekt auf Ihrem Rechner

  12. Installieren der erforderlichen Agent 365-Pakete

    Öffnen Sie vor dem Ausführen des Beispiels package.json in Ihrem Projekt, und vergewissern Sie sich, dass alle erforderlichen Agent 365- und Agent-Framework-Abhängigkeiten aufgelistet sind. Das vom Microsoft 365 Agents Toolkit generierte Beispiel enthält diese Einträge bereits.

    Nachdem Sie die package.json überprüft haben, installieren Sie alles, indem Sie diesen Befehl ausführen:

    uv pip install -e

    Dadurch werden alle Agent 365 SDK-Bibliotheken, Agent-Framework-Abhängigkeiten, Hostingkomponenten und alle anderen im Beispiel definierten Abhängigkeiten abgerufen.

  13. Bitte überprüfen Sie nach der Installation, ob das Projekt erstellt und ausgeführt wird, indem Sie den Entwicklungsserver mit dem folgenden Befehl starten:

    uv run python start_with_generic_host.py

Hinzufügen von Microsoft 365-Tools (MCP-Server)

Sie können MCP-Server mithilfe der A365-Entwicklungsbefehle in der CLI erkunden und verwalten.

Beim Arbeiten mit MCP-Servern können Sie Folgendes tun:

  • Ermitteln, welche MCP-Server zur Verwendung verfügbar sind
  • Einen oder mehrere MCP-Server zur Konfiguration Ihres Agents hinzufügen
  • Die derzeit konfigurierten MCP-Server überprüfen
  • MCP-Server entfernen, die Sie nicht mehr benötigen

Nachdem MCP-Server hinzugefügt wurden, wird das Toolmanifest Ihres Agents erweitert, um Einträge wie folgt einzuschließen:

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

Erfahren Sie, wie Sie Tools hinzufügen und verwalten

Benachrichtigungsabonnement und -verwaltung

Der Beispiel-Agent abonniert alle Agent 365 SDK-Benachrichtigungen mithilfe von onAgentNotification("*") und leitet sie an einen einzelnen Handler weiter. Dieser Handler ermöglicht es dem Agent, auf Hintergrund- oder Systemereignisse zu reagieren, nicht nur auf direkte Benutzernachrichten.

Erfahren Sie, wie Sie Agents benachrichtigen

Der folgende Code zeigt, wie die Benachrichtigung in der Datei agent.py konfiguriert ist.

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

Einblick

Dieser Codeausschnitt zeigt die minimalen Änderungen, die erforderlich sind, um Beobachtbarkeit im Beispiel zu ermöglichen. Das Agent 365 Observability SDK wird initialisiert und jeder Agent-Aufruf in einem InferenceScope wird umschlossen, sodass Eingaben, Ausgaben und Metadaten automatisch erfasst werden können.

Der folgende Code zeigt ein optimiertes Beispiel für Beobachtbarkeit in der Datei agent.py.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

Dieser Code ist das vollständige Einblick-Setup, das für das Python + Agent-Framework-Beispiel erforderlich ist. Weitere Informationen zur Beobachtbarkeit

Ihren Agent testen

Legen Sie die erforderlichen Umgebungsvariablen fest, wählen Sie einen Authentifizierungsmodus aus, und starten Sie den Agent lokal. Sie können alles durchgängig mit Agents Playground testen, ohne einen Microsoft 365-Mandanten zu benötigen, es sei denn, Sie möchten den Agent veröffentlichen und in Apps wie Teams oder Outlook verwenden.

Übersicht über Testschritte

  • Fügen Sie Ihre API-Schlüssel und die Modelleinstellungen zu einer .env-Datei hinzu, damit das Beispiel mit einem LLM sprechen kann.
  • Wählen Sie Ihren Authentifizierungsmodus aus. Für die lokale Entwicklung unterstützt das Beispiel die agentische Authentifizierung mithilfe von Werten, die aus Ihrem Agent-Blueprint erstellt wurden.
  • Starten Sie den Agent lokal, wodurch er Tools wie Agents Playground verfügbar gemacht wird.
  • Verwenden Sie Agents Playground, um Meldungen, Tools und Benachrichtigungen zu testen, ohne einen Mandanten einzurichten oder etwas bereitzustellen.
  • Wenn Sie bereit für die Praxis sind, veröffentlichen Sie einen Microsoft 365-Mandanten, und testen Sie den Agent innerhalb von Teams, Outlook oder anderen Microsoft 365-Oberflächen.

Weitere Informationen zum Testen

Agent veröffentlichen

Wenn Ihr Agent für tatsächliche Microsoft 365-Erlebnisse wie Teams-Diagramme, Outlook-Nachrichten oder Word @mentions bereit ist, veröffentlichen Sie ihn in einem Microsoft 365-Mandanten. Der Agent 365 CLIpublish-Befehl behandelt die Verpackung: Er aktualisiert Ihr Manifest, verpackt alles und lädt den Agent in das Microsoft Admin Center hoch.

Überprüfen Sie während der Veröffentlichung den Namen, die Beschreibung, die Symbole und die Version des Agents und passen Sie diese an, bevor Sie den Upload abschließen. Nach der Veröffentlichung ist Ihr Agent innerhalb des Mandanten auffindbar und installierbar.

Von Bedeutung

Nach der Veröffentlichung deines Agenten musst du den Agenten-Blueprint im Developer Portal konfigurieren, bevor du Instanzen erstellst. Siehe Agent Blueprint konfigurieren im Developer Portal.

Hier können Sie veröffentlichte Agents anzeigen: https://admin.cloud.microsoft/#/agents/all

Weitere Informationen über den vollständigen Workflow und schrittweise Anleitungen

  • Last updated on