こんにちは、Power Platform サポートの清水です。
この記事では、Copilot Studio のエージェントを Teams に展開した際に発生することのあるトラブルと、その対処法についてご紹介します。
重要
本記事は Copilot Studio の Standard Harness を使用した場合を前提としています。GitHub Copilot Harness には当てはまらない場合があります。
この記事でわかること
- Copilot Studio のエージェントを Teams に展開した場合の動作の特徴
- Teams チャネルで発生しがちなトラブル
- Teams チャネルでトラブルが発生した場合の対処法
- Teams チャネルでトラブルが発生しにくくなるようなエージェントの構築ヒント
目次
Teams チャネルの特徴と発生しがちなトラブルについて
Copilot Studio の Microsoft Teams チャネルは、エージェントの展開先として非常に多くご採用いただいているチャネルですが、チャネルの特徴により、エージェントとの会話において原因不明のエラーが発生することも多くあります。
Teams チャネルでトラブルの発生原因となる動作として、セッションが自動でリセットされないという特徴があります。
Teams チャネルでは、Microsoft 365 Copilot などの Web ベースの展開とは異なり、会話のスレッドが無期限に保持され、会話履歴が永続的に保持されます。
※参考情報: Microsoft Teams でエージェントを展開する - Microsoft Copilot Studio
この動作により、過去にエージェントと行った会話履歴や、セッション上で保持されている変数、トークンなどが自動でリセットされずに半永久的に保持され、想定外の動作が発生するケースが多くみられます。
事例ベースでは、例えば以下のような事象が発生した事例があります。
- 過去の会話履歴が蓄積したことが原因で、AI モデルとのやり取り時にトークン (コンテキスト長) の上限を超過してエラーが発生する
- 過去のやり取りにおいてグローバル変数に格納された値がリセットされず、想定外の変数値が再利用されてしまう
- エージェントが過去にナレッジソースから検索した情報がセッション内に残り、最新のナレッジソースの情報を応答できない
また、エージェントの内部処理でエラーが発生した場合、多くは「SystemError」としてユーザーに応答が返されます。
そのため、原因の分析が難しく、お問い合わせをいただくまで原因や対処法が分からないことが多いです。
一度エラーが発生すると、同じエラーが繰り返し発生し、エージェントが全く使用できない状態となってしまうケースも存在します。
なお、以下のように、エージェントとの会話が始まっていない段階での問題については、この動作とは関連がない可能性が高いです。
この場合、エージェント側での対処ではなく、Teams 側の設定などが影響している可能性が高いため、まずは Teams の設定の確認などを進めていくことをおすすめいたします。
- エージェントを Teams にインストールできない
- Teams 上でエージェントが見つからない
- エージェントにメッセージを送信しても応答が来ない
Teams チャネルで会話中にエラーが発生した場合の切り分けについて
Teams チャネルでのエージェントとの会話中に原因不明なエラーが発生した場合、まず実施いただきたい切り分けは以下の通りです。
- Microsoft 365 Copilot チャネルでも同じ事象が発生するか
- 事象が発生したセッションにおいて
/debug clearhistoryや/debug clearstateコマンドを実行することで改善が見られるか
エージェントとの会話において、Teams チャネルでのみエラーが発生する場合、上述のセッション残存が影響している可能性が高いです。
また、/debug clearhistory や /debug clearstate コマンドは、エージェントとの会話履歴や、会話の状態、キャッシュされた情報を削除するコマンドです。
さらに、/debug clearstate を実行することで、エージェントの最新バージョンが読み込まれ、公開済みの新しいバージョンを取得することができます。
上記コマンドを実行することで事象に改善が見られる場合、Teams チャネルでのセッション保持が原因で問題が発生している可能性が高いため、後述するようなエージェント側での対策により、再発防止が期待できます。
エージェントの実装における対策について
Teams チャネルにエージェントを展開する場合、エージェントの設計として、明示的に会話履歴やグローバル変数をリセットする処理を組み込むことをおすすめします。
リセットのタイミングとしては、
- エラー発生時
- 一定時間セッションが非アクティブとなったタイミング
などが挙げられます。
非アクティブ時のリセットについては、以下の公開情報にて実装方法を紹介しておりますので、ご参照ください。
非アクティブ時のリセットを実装する
また、エージェントのシステムトピックである “エラー発生時” トピックにて、上記と同様の処理を実装することで、エラー発生時にセッションをクリアすることが可能です。
ユーザーのユースケースを複数想定し、実装の観点からもエラーが発生しない仕組みの導入をご検討ください。
非アクティブ トリガーの仕組みやユースケースに関して紹介している以下の公開情報も参考になりますので、ぜひご一読ください。
非アクティブ トリガー
エージェントをより快適に使用するために、チャネルの特性を考慮したエージェントの実装をご検討いただけますと幸いです。
※本情報の内容（添付文書、リンク先などを含む）は、作成日時点でのものであり、予告なく変更される場合があります。