開発トンネルを使用したエージェントのテスト

開発トンネルを使用すると、Agent 365 エージェントを開発マシン上でローカルに実行しながら、Microsoft 365 アプリケーション (Teams、Outlook、Word など) との連携をテストできます。 このアプローチにより、ローカル環境での開発と実環境でのテストが連携されるため、クラウドへの展開前に、実際の Microsoft 365 環境でエージェントの動作を検証することができます。

必要条件

Dev Tunnels を使用する前に、開発トンネルコマンドライン ツールを必ずインストールしてください。

開発トンネルの設定

開発トンネルを構成して、ローカル エージェントのエンドポイントを Microsoft 365 サービスに公開します。

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

  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 をコピーしてください。

ヒント

devtunnel list を使用してすべてのトンネルを表示し、devtunnel delete <tunnel-id> を使用して不要になったトンネルを削除してください。

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

開発トンネルのURL (例: https://abc123xyz.devtunnels.ms:3978/api/messages) をエージェントのメッセージング エンドポイントとして登録し、Microsoft 365 がメッセージをどこに転送すべきかを認識できるようにします。 エンドポイントの末尾に /api/messages を付けるのを忘れないでください。

エージェントのメッセージング エンドポイントを設定するを参照してください

Microsoft 365 でのテスト

開発トンネルを有効にし、エンドポイントを登録したら、Microsoft 365 アプリケーションでエージェントをテストしてください。

Microsoft Teams でのテスト

  1. 依存関係のインストールとエージェント・アプリケーション・サーバーの起動に記載のの手順を使用して、ローカルエージェントを起動してください。

  2. トンネルの接続状態を確認してください:

    devtunnel list

    トンネルにアクティブなホスト接続があることを確認してください 「ホスト接続」列には、0より大きい数値が表示されている必要があります。

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

    • Microsoft Teams (Web 版またはデスクトップ版) を開きます
    • Teams の検索バーで、名前またはメールアドレスを使ってエージェントを検索してください
    • エージェントと会話を始める
    • メッセージを送信し、応答を確認してください
    • ローカルコンソールで受信リクエストとエージェントの活動を確認してください

電子メール通知のテスト

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

  1. エージェントのメールアドレスにメールを送ってください
  2. メールのスレッドでエージェントを CC に入れる
  3. ローカルコンソールで通知 webhook を監視する
  4. エージェントがメールを処理し、返信することを検証する

Word の統合テスト

Word コメントに応答するエージェント

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

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

開発トンネルは、接続の問題のデバッグやリクエストの流れの把握に役立つトラフィック検査機能を提供します:

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 を押すと、トンネルが停止します。

このコマンドは、エージェントのメッセージング エンドポイントから開発トンネルの URL を削除します。 運用環境に展開する際は、クラウド上でホストされているエンドポイントの URL を設定してください。

メモ

devtunnel delete <tunnel-id> を使用して明示的に削除するまでは、このトンネルは今後も引き続き利用可能です。

制限

開発トンネルを使用してテストを行う際は、以下の制限事項に注意してください:

  • 開発専用: 開発トンネルは開発やテストに使用し、運用環境では使用しないでください。
  • パフォーマンス: ネットワークのルーティングの影響により、クラウドホスト型のエージェントに比べて遅延が高くなる可能性があります。
  • 接続の安定性: トンネル接続が時折切断され、手動で再起動が必要になる場合があります。
  • セキュリティ上の注意: --allow-anonymous フラグはテストには便利ですが、機密データには使用しないでください。
  • セッション管理: セッションの期間によっては、定期的に再認証が必要になる場合があります。

次の手順

開発トンネルでのテストが成功した後:

トラブルシューティング​​

開発トンネルでのテスト中に問題が発生した場合は、トンネル、接続、エンドポイントに関する一般的な解決策について、まずこちらをご覧ください。 Agent 365 のより広範なトラブルシューティング (セットアップ、認証、メッセージング) については、、トラブルシューティングを参照してください。

トンネル接続失敗

症状: 開発トンネルが起動しないか、すぐに切断される。

ソリューション:

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

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

症状: Microsoft 365 ではメッセージが送信されたと表示されていますが、ローカル エージェントには受信されていません。

ソリューション:

  • エージェントがローカルで実行されていることを確認する
  • トンネルがアクティブであることを確認します devtunnel list に「接続済み」と表示されていることを確認してください
  • a365.config.json のエンドポイント構成を確認し、開発トンネルの URL がメッセージングエンドポイントとして設定されていることを確認してください
  • devtunnel host を実行しているターミナルで Dev Tunnel のログを確認し、接続エラーがないか調べてください
  • ローカルのポート番号がトンネルのポート番号と一致していることを確認してください (どちらもデフォルトは 3978 です)

開発トンネル経由での認証エラー

症状: 開発トンネル経由でテストを行うと、401 または 403 エラーが発生する。

ソリューション:

  • エージェンティック認証が構成されていることを確認してください (Microsoft 365 統合用の開発トンネルでは、ベアラー トークン認証は機能しません)。
  • a365.generated.config.json でエージェント ブループリントの認証情報を確認してください。
  • テストする操作に対して、エージェントに必要な権限が割り当てられていることを確認してください。
  • 認証トークンが期限切れになっていないか確認してください。

トンネルの URL が変更されたか、有効期限が切れました

症状: 以前正常に動作していたトンネル URL がエージェントにルーティングされなくなりました。

ソリューション:

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