Devトンネルを使ったエージェントのテスト

Dev トンネルを使用すると、エージェントが開発用コンピューター上でローカルに実行されている間に、Microsoft 365 アプリケーション (Teams、Outlook、Wordなど) で Agent 365 エージェントをテストできます。 このアプローチは、ローカル開発と実際のテストを橋渡しするので、クラウドにデプロイする前に、実際のMicrosoft 365環境でエージェントの動作を検証できます。

[前提条件]

Dev Tunnelsを使う前に、必ず Dev Tunnelsのコマンドラインツールをインストールしてください。

• Windows: winget install Microsoft.devtunnel
• macOS/Linux:aka.ms/devtunnels/download からダウンロード

開発トンネルの設定

ローカル エージェント エンドポイントをMicrosoft 365 サービスに公開するように Dev Tunnel を構成します。

トンネルを作成して開始する

1. Dev Tunnelにサインイン:

   devtunnel user login
   

2. 永続トンネルの作成:

   devtunnel create --allow-anonymous
   

   このコマンドはトンネルIDを返します。 この識別子は将来の使用のために保存してください。

3. トンネルポートの設定:

   エージェントサーバーが使用するポート(通常は3978)を割り当てます:

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

4. トンネル開始:

   devtunnel host <tunnel-id>
   

   このコマンドはトンネルURLを表示します(例: https://abc123xyz.devtunnels.ms:3978)。 次のステップのためにこのURLをコピーしてください。

エージェントメッセージングエンドポイントの設定

あなたの Dev Tunnel URL (https://abc123xyz.devtunnels.ms:3978/api/messages など) をエージェント メッセージング エンドポイントとして登録し、Microsoft 365 がメッセージをルーティングする場所を把握できるようにします。 終点に付ける接尾辞 /api/messages を忘れないでください。

「Set agent messaging endpoint」をご覧ください

Microsoft 365を使用してテストする

Dev Tunnel がアクティブでエンドポイントが登録されたら、Microsoft 365 アプリケーションでエージェントをテストします。

Microsoft Teamsでテストする

1. 「依存関係のインストール」の指示に従ってローカルエージェントを起動し、エージェントアプリケーションサーバーを起動します。

2. トンネル接続性の確認:

   devtunnel list
   

   トンネルでアクティブなホスト接続が表示されているか確認してください。 「ホスト接続」列には0より大きい数値が表示されるはずです。

3. Teamsでエージェントとやり取りする:

   • Microsoft Teams (Web またはデスクトップ) を開く
   • Teams検索バーで、名前またはメールアドレスでエージェントを検索してください
   • エージェントと会話を始めましょう
   • メッセージを送って、その返答を観察してください
   • ローカルコンソールでリクエストやエージェントの活動を確認しましょう

テストメール通知

エージェントが メール通知用に設定されている場合:

1. エージェントのメールアドレスにメールを送ってください
2. メールのスレッドでエージェントをCCに入れてください
3. 使用中のローカルコンソールで通知ウェブフックを監視してください
4. エージェントの対応やメールへの返信を確認しましょう

Word統合のテスト

Wordコメントに応答するエージェントの場合:

1. エージェントがアクセスできるWordドキュメントを開きます。
2. エージェントについてコメントを添えてください。
3. 通知はローカルコンソールを確認してください。
4. エージェントの応答がWordに表示されていることを確認します。

トンネルの活動を監視する

Dev Tunnelsは、接続問題のデバッグやリクエストフローの理解を支援するトラフィック検査を提供します:

devtunnel show <tunnel-id>

このコマンドは以下を表示します:

• アクティブな接続とセッションの詳細。
• リクエストおよびレスポンス情報。
• 交通量の統計。
• 接続エラーと警告。

また、devtunnel host コマンドの出力を見守ることで、トンネルの活動をリアルタイムで監視することも可能です。

トンネル接続の維持

開発トンネルは devtunnel host プロセスが稼働し続ける必要があります。 もし非アクティブ、ネットワークの問題、またはパソコンがスリープ状態になって接続が切れた場合は、再起動が必要です。

トンネルの状態を確認する

トンネルがアクティブかどうか確認してください:

devtunnel list

出力は以下の通りです:

• トンネルID:あなたのトンネル識別子
• ホスト接続数:アクティブな接続数( devtunnel host 実行中は1つ以上であるべき)
• ポート:設定済みポート
• 期限:トンネルの有効期限

ホスト接続が0の場合、トンネルは存在していますが現在ホストされていません。

切断されたトンネルを再スタートする

もしトンネル接続が切れたら、同じトンネルIDを使って再起動してください:

devtunnel host <tunnel-id>

トンネルURLは同じままなので、エージェントのメッセージングエンドポイント設定を更新する必要はありません。

開発中はトンネルをアクティブに保つ

安定した接続を維持するために:

• ターミナルウィンドウを開けておく - devtunnel host稼働中のターミナルを閉じないでください。
• コンピュータスリープの防止 - テスト中にシステムを起き続けるように設定しましょう。
• 接続エラーに注意 - devtunnel host 端末の出力で切断メッセージを監視してください。
• ネットワーク変更後に再起動 する - ネットワークを切り替えたりVPNを再接続した場合は、トンネルを再起動してください。

クリーンアップ

開発トンネルでのテストが終わったら:

トンネルを止めろ

ターミナルで稼働中のdevtunnel hostが表示されたらCtrl+Cを押してトンネルを停止してください。

このコマンドは、エージェントのメッセージングエンドポイントからDev TunnelのURLを削除します。 本番環境にデプロイする際は、クラウドホストのエンドポイントURLを設定してください。

制限事項

Dev Tunnelsでのテスト時には以下の制限を考慮してください:

• 開発専用:開発とテストにはDev Tunnelsを使い、本番環境には使いません。
• パフォーマンス:ネットワークルーティングのため、クラウドホストエージェントと比べて遅延が高くなると予想してください。
• 接続の安定性:トンネル接続が時折切断され、手動再起動が必要になることがあります。
• セキュリティ上の考慮点: --allow-anonymous フラグはテストに便利ですが、機密データには使わないでください。
• セッション管理:セッションの長さに応じて定期的に再認証が必要になる場合があります。

次のステップ

Dev Tunnelテストが成功した後:

• エージェントをクラウドにデプロイします: Azure、 AWS でエージェント メッセージング エンドポイントを設定する、または GCP でエージェント メッセージング エンドポイントを設定にデプロイします。
• エージェントメッセージングエンドポイントの設定: エージェントメッセージングエンドポイント。
• 完全な開発ライフサイクルを追いましょう: Agent 365の開発ライフサイクル。

トラブルシューティング

Dev Tunnelsでのテスト中に問題が発生している場合は、共通のトンネル、接続性、エンドポイントの修正についてはこちらから始めてください。 より広範なAgent 365のトラブルシューティング(セットアップ、認証、メッセージング)については、「 トラブルシューティング」を参照してください。

トンネル接続の失敗

症状:Dev Tunnelが起動せず、すぐに切断される。

解決策:

• ログインを確認しましょう: devtunnel user login
• 同じポートを使っている他のプロセスがないか確認してください
• ファイアウォールがDev Tunnel接続を許可しているか確認してください
• トンネルを削除して再作成する: devtunnel delete <tunnel-id> 新しいトンネルを作成します

メッセージがローカルエージェントに届かない

Symptoms: Microsoft 365はメッセージが送信されたことを示しますが、ローカル エージェントはメッセージを受信しません。

解決策:

• エージェントがローカルで運用されているか確認してください
• トンネルがアクティブかどうか確認してください: devtunnel list 「接続済み」と表示されるはずです。
• エンドポイントの設定を確認してください: a365 config display DevのトンネルURLが表示されるはずです
• ターミナルで devtunnel host を実行中のDev Tunnelログを確認し、接続エラーがないか確認してください
• ローカルポートがトンネルポートと一致していることを確認してください(どちらもデフォルトで3978であるべきです)

Devトンネルを通じた認証エラー

症状:Dev Tunnelでテストした際に401または403エラーが発生します。

解決策:

• エージェント認証が構成されていることを確認します (ベアラー トークン認証は、Microsoft 365統合のために Dev トンネルでは機能しません)。
• a365 config display -gを使ってエージェントの設計図認証を確認してください。
• テストしている操作に必要な権限をエージェントが持っているか確認してください。
• 認証トークンが期限切れになっていないか確認してください。

トンネルURLの変更または期限切れ

症状:以前は使えていたトンネルURLがエージェントにルーティングされなくなった場合。

解決策:

• devtunnel listを使ってトンネルの状態を確認してください。
• devtunnel host <tunnel-id>を使ってトンネルを再起動してください。
• a365 setup blueprint --endpoint-onlyを使ってURLが変更された場合はメッセージングエンドポイントを更新してください。