Testagenten mithilfe von Dev Tunnels

Mithilfe von Dev Tunnels können Sie Ihren Agent 365-Agent mit Microsoft 365 Anwendungen (z. B. Teams, Outlook oder Word) testen, während Ihr Agent lokal auf Ihrem Entwicklungscomputer ausgeführt wird. Dieser Ansatz verbindet lokale Entwicklung und reale Tests, sodass Sie das Agentverhalten in tatsächlichen Microsoft 365 Umgebungen überprüfen können, bevor Sie in der Cloud bereitstellen.

Voraussetzungen

Bevor du Dev Tunnels verwendest, solltest du unbedingt das Dev Tunnels-Kommandozeilen-Tool installieren.

• Windows: winget install Microsoft.devtunnel
• macOS/Linux: Download von aka.ms/devtunnels/download

Richte den Dev Tunnel ein

Konfigurieren Sie einen Dev Tunnel, um Ihren lokalen Agent-Endpunkt für Microsoft 365 Dienste verfügbar zu machen.

Erstelle und starte einen Tunnel

1. Melden Sie sich bei Dev Tunnel an:

   devtunnel user login
   

2. Erstellen Sie einen persistenten Tunnel:

   devtunnel create --allow-anonymous
   

   Dieser Befehl liefert eine Tunnel-ID. Speichern Sie diesen Identifikator für die spätere Nutzung.

3. Konfigurieren Sie den Tunnelport:

   Weisen Sie den Port zu, den Ihr Agent-Server verwendet (typischerweise 3978):

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

4. Starte den Tunnel:

   devtunnel host <tunnel-id>
   

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

Nachrichtenendpunkt des Agenten konfigurieren

Registrieren Sie Ihre Dev Tunnel-URL (z. B. https://abc123xyz.devtunnels.ms:3978/api/messages) als Agent-Messaging-Endpunkt, damit Microsoft 365 weiß, wo Nachrichten weitergeleitet werden sollen. Vergiss nicht das /api/messages Suffix des Endpunkts.

Bitte siehe Set agent messaging endpoint

Testen mit Microsoft 365

Testen Sie Ihren Agenten in Microsoft 365-Anwendungen, wenn Ihr Dev Tunnel aktiv ist und der Endpunkt registriert ist.

Testen in Microsoft Teams

1. Starte deinen lokalen Agenten mit den Anweisungen in Installationsabhängigkeiten und starte den Agent-Anwendungsserver.

2. Überprüfen Sie die Tunnelverbindung:

   devtunnel list
   

   Überprüfe, ob dein Tunnel aktive Host-Verbindungen anzeigt. Die Spalte "Host-Verbindungen" sollte eine Zahl größer als 0 anzeigen.

3. Interagiere mit deinem Agenten in Teams:

   • Öffnen von Microsoft Teams (Web oder Desktop)
   • In der Suchleiste von Teams suchen Sie Ihren Agenten anhand des Namens oder der E-Mail
   • Beginnen Sie ein Gespräch mit dem Agenten
   • Senden Sie eine Nachricht und beobachten Sie die Antwort
   • Überprüfen Sie Ihre lokale Konsole auf eingehende Anfragen und Agentenaktivität

Test-E-Mail-Benachrichtigungen

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

1. Senden Sie eine E-Mail an die E-Mail-Adresse Ihres Maklers
2. CC deinen Agenten in einem E-Mail-Thread
3. Überwachen Sie Ihre lokale Konsole für den Benachrichtigungs-Webhook
4. Überprüfen Sie, ob Ihr Agent die E-Mail verarbeitet und beantwortet.

der Test der Word-Integration

Für Agents, die auf Word Kommentare reagieren:

1. Öffnen Sie ein Word Dokument, auf das Ihr Agent Zugriff hat.
2. Füge einen Kommentar hinzu, in dem du deinen Makler erwähnst.
3. Schau auf deine lokale Konsole nach der Benachrichtigung.
4. Überprüfen Sie, ob die Antwort Ihres Agents in Word angezeigt wird.

Tunnelaktivität überwachen

Dev Tunnels bietet Verkehrskontrolle, um Verbindungsprobleme zu debuggen und den Anfragefluss zu verstehen:

devtunnel show <tunnel-id>

Dieser Befehl zeigt an:

• Aktive Verbindungen und Sitzungsdetails.
• Anfrage- und Antwortinformationen.
• Statistiken zum Verkehrsaufkommen.
• Verbindungsfehler und Warnungen.

Du kannst auch die Tunnelaktivität in Echtzeit überwachen, indem du die Ausgabe des Befehls devtunnel host beobachtest.

Tunnelverbindungen erhalten

Dev-Tunnels erfordern, dass der devtunnel host Prozess weiterhin läuft. Wenn Inaktivität, Netzwerkprobleme oder der Schlafzustand des Computers dazu führen, dass die Verbindung abfällt, musst du ihn neu starten.

Überprüfen Sie den Tunnelstatus

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

devtunnel list

Die Ausgabe zeigt:

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

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

Neustart eines getrennten Tunnels

Wenn deine Tunnelverbindung abbricht, starte sie mit derselben Tunnel-ID neu:

devtunnel host <tunnel-id>

Die Tunnel-URL bleibt gleich, sodass du die Konfiguration deines Agent-Messaging-Endpunkts nicht aktualisieren musst.

Halten Sie die Tunnel während der Entwicklung aktiv

Um stabile Verbindungen aufrechtzuerhalten:

• Lass das Terminalfenster offen – Schließe das laufende devtunnel hostTerminal nicht.
• Verhindern Sie Computerschlaf – Konfigurieren Sie Ihr System so, dass es während der Testsitzungen wach bleibt.
• Achten Sie auf Verbindungsfehler – Überwachen Sie den devtunnel host Terminalausgang auf Trennmeldungen.
• Neustart nach Netzwerkänderungen – Wenn du das Netzwerk wechselst oder dich wieder mit VPN verbindest, starte den Tunnel neu.

Aufräumen

Wenn du die Tests mit Dev Tunnels abgeschlossen hast:

Stoppt den Tunnel

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

Dieser Befehl entfernt die Dev Tunnel URL vom Messaging-Endpunkt deines Agenten. Wenn Sie in die Produktion deployen, setzen Sie die cloud-gehostete Endpunkt-URL ein.

Einschränkungen

Beachten Sie diese Einschränkungen beim Testen mit Dev Tunnels:

• Nur Entwicklung: Nutze Dev Tunnels für Entwicklung und Test, nicht für die Produktion.
• Leistung: Erwarten Sie eine höhere Latenz im Vergleich zu cloud-gehosteten Agenten aufgrund von Netzwerkrouten.
• Verbindungsstabilität: Tunnelverbindungen können gelegentlich abbrechen und einen manuellen Neustart erfordern.
• Sicherheitsaspekte: Die Flagge --allow-anonymous ist praktisch zum Testen, aber verwenden Sie sie nicht bei sensiblen Daten.
• Sitzungsmanagement: Je nach Sitzungsdauer müssen Sie sich eventuell regelmäßig erneut authentifizieren.

Nächste Schritte

Nach erfolgreichen Dev-Tunnel-Tests:

• Stellen Sie Ihren Agent in der Cloud bereit: Deploy to Azure, Set agent messaging endpoint in AWS, or Set agent messaging endpoint in GCP.
• Agent-Messaging-Endpunkte konfigurieren: Agent-Messaging-Endpunkt.
• Folgen Sie dem gesamten Entwicklungszyklus: Agent 365 Entwicklungslebenszyklus.

Problembehandlung

Wenn Sie beim Testen durch Dev Tunnels auf Probleme stoßen, beginnen Sie hier mit den Lösungen für gemeinsame Tunnel, Konnektivität und Endpunkte. Für umfassendere Agent-365-Fehlerbehebung (Einrichtung, Authentifizierung und Messaging) siehe Fehlerbehebung.

Tunnelverbindung scheitert

Symptome: Der Dev-Tunnel startet nicht oder trennt sich sofort.

Lösungen:

• Überprüfen Sie, dass Sie eingeloggt sind: devtunnel user login
• Überprüfen Sie, ob ein anderer Prozess denselben Port verwendet
• Stelle sicher, dass deine Firewall Dev-Tunnel-Verbindungen erlaubt
• Lösche und erstelle den Tunnel neu: devtunnel delete <tunnel-id> Dann erstelle einen neuen

Nachrichten erreichen den örtlichen Agenten nicht

Symptoms: Microsoft 365 gibt an, dass die Nachricht gesendet wurde, aber Ihr lokaler Agent empfängt sie nicht.

Lösungen:

• Bestätigen Sie, dass Ihr Agent lokal arbeitet
• Überprüfen Sie, ob der Tunnel aktiv ist: devtunnel list sollte "Verbunden" angezeigt werden.
• Überprüfen Sie die Endpunkt-Konfiguration: a365 config display sollte deine Dev-Tunnel-URL anzeigen
• Überprüfen Sie die Dev Tunnel-Logs im laufenden devtunnel host Terminal auf Verbindungsfehler
• Stelle sicher, dass dein lokaler Port mit dem Tunnelport übereinstimmt (beide sollten standardmäßig 3978 sein).

Authentifizierungsfehler durch den Dev Tunnel

Symptome: 401- oder 403-Fehler beim Testen durch Dev Tunnel.

Lösungen:

• Überprüfen Sie, ob die Agenten-Authentifizierung konfiguriert ist (Die Bearertoken-Authentifizierung funktioniert nicht mit Dev Tunnels für die Integration von Microsoft 365).
• Überprüfen Sie die Agenten-Blueprint-Zugangsdaten mit a365 config display -g.
• 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 arbeitende Tunnel-URL wird nicht mehr zu Ihrem Agenten weitergeleitet.

Lösungen:

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