【Microsoft×生成AI連載】シリーズです！
Microsoft Copilot Studio（以下、Copilot Studio）のエージェントを作成すると、Microsoft TeamsやMicrosoft 365 Copilotのチャットから利用できます。その際に、ユーザーがファイルを添付することも可能です。
今回はCopilot Studioでユーザーの添付したファイルを処理するための実装方法を大きく2つ紹介し、それぞれの利用シーンとメリット、注意点を解説します。
これまでの連載
これまでの連載記事一覧はこちらの記事にまとめておりますので、過去の連載を確認されたい方はこちらの記事をご参照ください。
Copilot Studioで添付ファイルを処理する実装方法の紹介
Microsoft TeamsやMicrosoft 365 Copilotでは、チャット上でファイルを添付すると個人のOneDriveにファイルがアップロードされます。
そのためCopilot Studioで添付ファイルを扱うためには、ファイルの実体が存在するOneDriveからファイルを取得して処理を行う方法と、エージェント上で添付されたファイル情報を利用する方法の大きく2つの方法が考えられます。
OneDriveからファイルを取得
添付ファイルがアップロードされているOneDriveのフォルダーからファイル名と一致するものを取得し、そのファイルのIDなどを後続のコネクタに渡すことでファイル処理を実現することが可能です。
アップロードされるフォルダー名はユーザー設定などによって異なりますが、Microsoft Teamsでは「Microsoft Teams チャット ファイル」、Microsoft 365 Copilotでは「Microsoft Copilot チャット ファイル」が一例として挙げられます。
このフォルダーの中からファイル名と一致するファイルを取得する方法は2つ挙げられます。
指定フォルダーのファイル一覧リストを取得
OneDrive for Businessの「フォルダー内のファイルのリスト」コネクタを利用すると、指定したフォルダーに配置されているファイル一覧を取得することができます。
この一覧の中から添付されたファイル名と完全一致するファイルを特定します。添付されたファイル名は、システム変数「Activity.Attachments」の「Name」に格納されています。
特定できたファイルのIDを後続のファイル編集のコネクタに渡すなどで、添付されたファイルに対して直接編集が可能となります。
指定フォルダー内のファイルをファイル名で検索
OneDrive for Businessの「フォルダー内のファイルの検索」コネクタを利用すると、指定したフォルダーに配置されているファイルの中から条件に合ったファイルを検索し、取得することができます。
「File Search Mode」では「OneDriveSearch」と「Pattern」が選択可能です。添付されたファイル名と完全一致するファイルを取得するのであれば、正規表現を指定できる「Pattern」を選択することをおすすめします。
エージェント上で添付されたファイル情報を利用
添付ファイルの内容のみを後続のアクションで利用したい場合には、OneDriveコネクタを利用する必要はありません。システム変数「Activity.Attachments」の「Content」に格納された値を、後続のコネクタでファイルコンテンツを指定する項目に設定することが可能です。
例えばOneDriveに添付ファイルと同一内容のファイルを複製する場合は、OneDrive for Businessの「ファイルの作成」コネクタで「File Content」にシステム変数「Activity.Attachments」の「Content」を指定します。
利用シーンとメリット、注意点
利用シーン
OneDriveからファイルを取得
添付ファイル自体を編集したい場合に利用できます。
添付ファイルにエージェントの出力結果を記載するなど編集する際には、OneDriveコネクタを利用してファイルを取得する必要があります。
エージェント上で添付されたファイル情報を利用
添付ファイル自体を編集するなどの動作が不要で、一時的にファイルの内容を処理したい場合に利用できます。
ファイルを複製する際や、プロンプトの入力値がファイル形式の場合にファイルを指定する際には、エージェント上で添付されたファイル情報を利用することが可能です。
メリット
OneDriveからファイルを取得
アップロードされたファイルをOneDriveから取得するため、ファイル名やコンテンツ以外のメタデータも利用することが可能です。
また、ファイル自体が編集される方法を実現できるので、エージェント利用者はチャット上で添付したファイルのみ確認対象とすることができます。
エージェント上で添付されたファイル情報を利用
OneDriveコネクタを利用しないため、エージェント初回実行時などに表示される接続許可を、添付ファイル取得時にエージェント利用者に求めません。
接続の許可を行う回数が減ることで、エージェント利用者の利便性を高めることが期待できます。
注意点
システム変数は、接続の許可を行うと変数の値がリセットされる場合があります。回避策として、システム変数「Activity.Attachments」を利用する際は、OneDriveなどのコネクタを実行する前にトピック変数を作成し、その値にシステム変数「Activity.Attachments」を代入してください。以降の処理では、作成したトピック変数を利用します。
また、Microsoft 365 Copilotのチャットでは、現時点の仕様として、添付ファイルとして選択されたファイルがOneDriveにアップロードされる際、同名のファイルが存在する場合は上書きされます。
一方、Microsoft Teamsではファイル名が変更された状態でアップロードされるため、上書きは発生しません。
指定フォルダーのファイル一覧リストを取得
指定したフォルダーに20件を超えるファイルが配置されている場合、エラーが発生します。実際に利用する際には、エージェントフローを用いた例外処理を行うなどの実装が必要です。
指定フォルダー内のファイルをファイル名で検索
指定したフォルダーに200件を超えるファイルが配置されている場合、実在するファイル名を検索しても見つからない可能性があります。検証時には、フォルダー内に400件を超えるファイルを配置した際にこの現象が発生しました。
なお、ファイルが見つからない場合でもエラーは発生しません。
エージェント上で添付されたファイル情報を利用
システム変数「Activity.Attachments」に含まれる「Content」はファイル型変数であり、ファイルの内容を文字起こしした文字列変数ではありません。ファイルの内容を文字データとして扱う場合は、ファイル型変数を用いてOCR処理を行う必要があります。
まとめ
用途に応じて添付ファイルを処理する実装方法を使い分けることで、よりニーズに合ったエージェントを実装することが可能になります。
添付ファイル機能を利用して、Copilot Studioのエージェントをより活用させていきましょう！
おまけ（Copilot Chatによる本記事の要約）
本記事ここまでの執筆内容をCopilot Chatに転記し、記事内容の要約をしてもらいました。
Copilot Studio で作成したエージェントは、Microsoft Teams や Microsoft 365 Copilot のチャットから利用でき、ユーザーがファイルを添付することも可能です。
チャットに添付されたファイルはユーザーの OneDrive にアップロードされるため、Copilot Studio では OneDrive からファイルを取得して処理する方法と、エージェント上で添付ファイル情報を直接利用する方法の2通りで実装できます。
OneDrive から取得する方法は、添付ファイルそのものを編集したい場合に適しており、ファイル ID やメタデータを含めた処理が可能です。一方、エージェント上で添付ファイル情報を利用する方法は、ファイル内容をそのまま後続処理や AI プロンプトに渡したい場合に向いており、OneDrive 接続許可が不要な点が特徴です。
用途に応じてこれらを使い分けることで、ユーザー体験と実装のシンプルさを両立したエージェントを構築できます。ただし、フォルダー内のファイル数制限や、システム変数がリセットされる仕様など、いくつかの注意点もあります。
Copilot Studio では、添付ファイルの扱い方を理解することで、より実務に即したエージェント設計が可能になります。
