Agents mithilfe von Entwicklertunneln testen

Durch die Nutzung von Entwicklertunneln können Sie Ihren Agent 365-Agenten mit Microsoft 365-Anwendungen (wie Teams, Outlook oder Word) testen, während Ihr Agent lokal auf Ihrer Entwicklungsmaschine läuft. Dieser Ansatz verbindet lokale Entwicklung und reale Tests, sodass Sie das Verhalten des Agents in tatsächlichen Microsoft 365-Umgebungen validieren können, bevor Sie ihn in die Cloud bereitstellen.

Voraussetzungen

Bevor Sie Entwicklertunnel verwenden, stellen Sie sicher, dass Sie das Entwicklertunnel-Kommandozeilentool installiert haben.

Entwicklertunnel einrichten

Konfigurieren Sie einen Entwicklertunnel, um Ihren lokalen Agent-Endpunkt für Microsoft 365-Dienste freizugeben.

Einen Tunnel erstellen und starten

  1. Melden Sie sich bei Entwicklertunnel an:

    devtunnel user login

  2. Erstellen eines persistenten Tunnels:

    devtunnel create --allow-anonymous

    Dieser Befehl gibt eine Tunnel-ID zurück. Speichern Sie diese Kennung für die zukünftige Verwendung.

  3. Konfigurieren Sie den Tunnelport:

    Legen Sie den Port fest, den Ihr Agent-Server verwendet (typischerweise 3978):

    devtunnel port create <tunnel-id> -p <port-number>

  4. Starten Sie den Tunnel:

    devtunnel host <tunnel-id>

    Der Befehl zeigt Ihre Tunnel-URL an (zum Beispiel https://abc123xyz.devtunnels.ms:3978). Kopieren Sie diese URL für den nächsten Schritt.

Trinkgeld

Verwenden Sie devtunnel list, um alle Ihre Tunnel anzuzeigen, und devtunnel delete <tunnel-id>, um Tunnel zu entfernen, die Sie nicht mehr benötigen.

Agent-Messaging-Endpunkt konfigurieren

Melden Sie Ihre Entwicklertunnel-URL (z. B. https://abc123xyz.devtunnels.ms:3978/api/messages) als Agent Messaging-Endpunkt an, damit Microsoft 365 weiß, wohin die Nachrichten geleitet werden sollen. Vergessen Sie nicht das /api/messages Suffix des Endpunkts.

Siehe Agent-Messaging-Endpunkt festlegen

Testen mit Microsoft 365

Mit aktivem Entwicklertunnel und registriertem Endpunkt kann der Agent in Microsoft 365-Anwendungen getestet werden.

Testen in Microsoft Teams

  1. Starten Sie Ihren lokalen Agent anhand der Anweisungen unter Abhängigkeiten installieren und den Agent-Anwendungsserver starten.

  2. Tunnelverbindung überprüfen:

    devtunnel list

    Überprüfen Sie, ob Ihr Tunnel aktive Host-Verbindungen anzeigt. Die Spalte „Host-Verbindungen“ sollte eine Zahl größer als 0 anzeigen.

  3. Interagieren Sie mit Ihrem Agent in Teams:

    • Öffnen Sie Microsoft Teams (Web oder Desktop)
    • Suchen Sie in der Teams-Suchleiste nach Ihrem Agent anhand des Namens oder der E-Mail-Adresse
    • Starten Sie eine Unterhaltung mit dem Agent
    • Senden Sie eine Nachricht und prüfen Sie die Antwort
    • Überprüfen Sie Ihre lokale Konsole auf eingehende Anfragen und Agentenaktivität

E-Mail-Benachrichtigungen testen

Wenn Ihr Agent für E-Mail-Benachrichtigungen konfiguriert ist:

  1. Senden Sie eine E-Mail an die E-Mail-Adresse Ihres Agents
  2. Ihren Agent in einem E-Mail-Thread auf CC setzen
  3. Überwachen Sie Ihre lokale Konsole auf den Benachrichtigungs-Webhook
  4. Überprüfen Sie, ob Ihr Agent die E-Mail bearbeitet und beantwortet

Word-Integration testen

Für Agents, die auf Word-Kommentare reagieren:

  1. Öffnen Sie ein Word-Dokument, auf das Ihr Agent Zugriff hat.
  2. Fügen Sie einen Kommentar hinzu, in dem Sie Ihren Agent erwähnen.
  3. Prüfen Sie Ihre lokale Konsole auf die Benachrichtigung.
  4. Überprüfen Sie, ob die Antwort Ihres Agents in Word erscheint.

Tunnelaktivität überwachen

Entwicklertunnel bietet Datenverkehrsanalyse, um Verbindungsprobleme zu debuggen und den Anfragefluss zu verstehen:

devtunnel show <tunnel-id>

Dieser Befehl zeigt an:

  • Aktive Verbindungen und Sitzungsdetails.
  • Anforderungs- und Antwortinformationen.
  • Statistiken zum Datenverkehrsvolumen.
  • Verbindungsfehler und Warnungen.

Sie können die Tunnelaktivität auch in Echtzeit überwachen, indem Sie die Ausgabe des devtunnel host-Befehls beobachten.

Tunnelverbindungen aufrechterhalten

Entwicklertunnel erfordern, dass der devtunnel host-Prozess weiterläuft. Wenn die Verbindung aufgrund von Inaktivität, Netzwerkproblemen oder dem Ruhezustand Ihres Computers abbricht, müssen Sie sie neu starten.

Tunnelstatus prüfen

Überprüfen Sie, ob Ihr Tunnel aktiv ist:

devtunnel list

Die Ausgabe zeigt Folgendes an:

  • Tunnel-ID: Ihre Tunnelkennung
  • Host-Verbindungen: Anzahl der aktiven Verbindungen (sollte eine oder mehrere sein, wenn devtunnel host läuft)
  • Ports: Konfigurierte Ports
  • Ablauf: Ablaufzeit des Tunnels

Wenn Host Connections 0 anzeigt, existiert der Tunnel, ist aber aktuell nicht gehostet.

Neustart eines getrennten Tunnels

Wenn Ihre Tunnelverbindung abbricht, starten Sie sie mit derselben Tunnel-ID neu:

devtunnel host <tunnel-id>

Die Tunnel-URL bleibt gleich, sodass Sie die Konfiguration Ihres Agent-Messaging-Endpunkts nicht aktualisieren müssen.

Stellen Sie sicher, dass die Tunnel während der Entwicklung aktiv bleiben

Um stabile Verbindungen aufrechtzuerhalten:

  • Halten Sie das Terminalfenster offen – Schließen Sie das laufende devtunnel hostTerminal nicht.
  • Verhindern Sie den Ruhezustand des Computers – Konfigurieren Sie Ihr System so, dass es während der Testsitzungen nicht in den Ruhezustand wechselt.
  • Achten Sie auf Verbindungsfehler – Überwachen Sie die devtunnel host Terminalausgabe auf Meldungen über getrennte Verbindungen.
  • Tunnel nach Netzwerkänderungen neu starten – Wenn Sie das Netzwerk wechseln oder sich erneut mit dem VPN verbinden, starten Sie den Tunnel neu.

Trinkgeld

Wenn Ihr Tunnel häufig die Verbindung verliert, überprüfen Sie Ihre Netzwerkeinstellungen und Firewall-Regeln, um sicherzustellen, dass sie die Verbindung nicht blockieren.

Bereinigung

Nach Abschluss Ihrer Tests mit Entwicklertunneln:

Stoppen Sie den Tunnel

Drücken Sie Ctrl+C im Terminal, in dem devtunnel host läuft, um den Tunnel zu stoppen.

Dieser Befehl entfernt die Entwicklertunnel-URL aus dem Messaging-Endpunkt Ihres Agents. Wenn Sie in die Produktion bereitstellen, setzen Sie die cloud-gehostete Endpunkt-URL.

Anmerkung

Der Tunnel bleibt für zukünftige Nutzung verfügbar, bis Sie ihn explizit mit devtunnel delete <tunnel-id> löschen.

Einschränkungen

Beachten Sie diese Einschränkungen beim Testen mit Entwicklertunneln:

  • Nur für Entwicklung: Verwenden Sie Entwicklertunnel für Entwicklung und Test, nicht für die Produktion.
  • Leistung: Erwarten Sie aufgrund des Netzwerkroutings eine höhere Latenz im Vergleich zu cloud-gehosteten Agents.
  • Verbindungsstabilität: Tunnelverbindungen können gelegentlich unterbrochen werden und einen manuellen Neustart erfordern.
  • Sicherheitsaspekte: Der --allow-anonymous Flag ist praktisch zum Testen, sollte aber nicht mit vertraulichen Daten verwendet werden.
  • Sitzungsmanagement: Je nach Sitzungsdauer müssen Sie sich möglicherweise erneut authentifizieren.

Nächste Schritte,

Nach erfolgreichen Entwicklertunnel-Tests:

Problembehandlung

Wenn Sie auf Probleme beim Testen über Dev Tunnels stoßen, beginnen Sie hier mit Lösungen für häufige Tunnel-, Verbindungs- und Endpunktprobleme. Für umfassendere Agent 365-Fehlerbehebung (Einrichtung, Authentifizierung und Nachrichtenübermittlung) siehe Fehlerbehebung.

Tunnelverbindung fehlgeschlagen

Symptome: Entwicklertunnel startet nicht oder wird sofort getrennt.

Lösungen:

  • Überprüfen Sie, ob Sie eingeloggt sind: devtunnel user login
  • Überprüfen Sie, ob ein anderer Prozess denselben Port verwendet
  • Stellen Sie sicher, dass Ihre Firewall Entwicklertunnel-Verbindungen erlaubt
  • Löschen und erstellen Sie den Tunnel neu: devtunnel delete <tunnel-id> dann einen neuen erstellen

Nachrichten erreichen den lokalen Agent nicht

Symptome: Microsoft 365 gibt an, dass die Nachricht gesendet wurde, aber Ihr lokaler Agent erhält sie nicht.

Lösungen:

  • Stellen Sie sicher, dass Ihr Agent lokal läuft
  • Überprüfen Sie, ob der Tunnel aktiv ist: devtunnel list sollte „Verbunden“ anzeigen
  • Überprüfen Sie die Endpunkt-Konfiguration in a365.config.json und stellen Sie sicher, dass Ihre Entwicklertunnel-URL als Messaging-Endpunkt eingetragen ist
  • Überprüfen Sie die Entwicklertunnel-Protokolle im Terminal, in dem devtunnel host ausgeführt wird, auf Verbindungsfehler
  • Stellen Sie sicher, dass Ihr lokaler Port mit dem Tunnelport übereinstimmt (beide sollten standardmäßig 3978 sein)

Authentifizierungsfehler durch Entwicklertunnel

Symptome: 401- oder 403-Fehler beim Testen über den Entwicklertunnel.

Lösungen:

  • Stellen Sie sicher, dass die agentische Authentifizierung konfiguriert ist (Bearer-Token-Authentifizierung funktioniert nicht mit Entwicklertunneln für die Microsoft 365-Integration).
  • Überprüfen Sie die Agent-Blaupausen-Anmeldeinformationen in a365.generated.config.json.
  • Bestätigen Sie, dass Ihr Agent die erforderlichen Berechtigungen für die von Ihnen getesteten Operationen hat.
  • Stellen Sie sicher, dass Ihre Authentifizierungstoken nicht abgelaufen sind.

Tunnel-URL geändert oder abgelaufen

Symptome: Die zuvor funktionierende Tunnel-URL führt nicht mehr zu Ihrem Agent.

Lösungen:

  • Überprüfen Sie den Tunnelstatus mithilfe von devtunnel list.
  • Starten Sie den Tunnel neu mit devtunnel host <tunnel-id>.
  • Aktualisieren Sie den Messaging-Endpunkt, falls sich die URL geändert hat, mithilfe von a365 setup blueprint --endpoint-only.
  • Last updated on