int-patterns

Copilot Studio パターンライブラリ

現在のタスクに関連するパターンファイルだけを読んでください — すべてのファイルを読まないでください。

パターンの使い方

パターンは推奨事項であり、必須要件ではありません。提示方法は、あなたの役割によって異なります。

Advisor エージェントの場合：

• 各パターンを提案として提示し、解決する課題と関連する理由を説明します
• ステータスに応じた表現を使います。
  • proven：「本番環境で使われている実績のあるパターンです。…に活用できるか検討してください」
  • recommended：「有効な推奨アプローチです。…に活用できるか検討してください」
  • experimental：「まだ十分に検証されていない実験的なアプローチです。採用する前に十分にテストすることをお勧めします」
• 常に「検討できるのは…です」または「一般的なアプローチは…です」と伝え、「必ず…してください」とは言わないでください
• ユーザーに判断を委ねてください。確認なしにパターンを自動適用しないでください

Author エージェントの場合：

• ユーザーまたは Advisor がすでに選択したパターンを実装するときは、正しい YAML 構造を確認するため、該当するパターンファイルを読んでください
• パターンを自分から提案しないでください。それは Advisor の役割です
• 正しい kind、フィールド、構造を確認するため、YAML の例を参照してください

パターン一覧

JIT 用語集 → jit-glossary.md

最初のメッセージで顧客固有の頭字語をグローバル変数に読み込み、オーケストレーターがナレッジソースを検索する前に展開できるようにします。

このパターンを読む場合：

• 用語集、頭字語一覧、用語表を追加したい場合
• エージェントが社内の略語を理解できず、ナレッジ検索の品質が低い場合
• 会話の開始時に CSV やテキストデータを変数に読み込む方法について質問された場合

JIT ユーザーコンテキスト → jit-user-context.md

現在のユーザーの M365 プロファイル（国、部署）をグローバル変数に読み込み、回答をパーソナライズします。

このパターンを読む場合：

• 国、部署、または役割を考慮した回答を実現したい場合
• エージェントが M365 Users コネクタを呼び出す必要がある場合
• チャット相手に基づいて回答をパーソナライズする方法について質問された場合

動的トピックリダイレクト → dynamic-topic-redirect.md

BeginDialog ノード内の Switch 式を使い、変数に基づいて異なるトピックにルーティングします。

このパターンを読む場合：

• 変数に基づいて複数のトピックのいずれかにルーティングする必要がある場合
• 入れ子になった ConditionGroup ノードを、より簡潔な方法に置き換えたい場合
• 動的なトピックリダイレクトや Switch 式について質問された場合

子エージェントからの応答を防止 → prevent-child-agent-responses.md

出力変数を使うよう子エージェントに指示し、ユーザーに直接メッセージを送らないようにします。

このパターンを読む場合：

• 子エージェントに、ユーザーにメッセージを送らずデータを返してほしい場合
• 子エージェントの完了設定についてユーザーが困惑している場合
• 親エージェントがユーザー向けのすべての応答を制御する必要がある場合

日付コンテキスト → date-context.md

Power Fx を使って現在の日付をエージェントの指示に挿入し、日付に基づく正確な回答を実現します。

このパターンを読む場合：

• 「来週は何がありますか？」や「今後のイベント」など、日付に関する質問がある場合
• エージェントがスケジュール、カレンダー、締め切り、または時間に依存するコンテンツを扱う場合
• 日付の解釈が混乱やハルシネーションの原因になっている場合

オーケストレーターが生成する変数 → orchestrator-variables.md

AutomaticTaskInput を使用して、オーケストレーション時にユーザーのメッセージを分類するか、構造化データを抽出します。追加コストや遅延は発生しません。

次のような場合にこのパターンをお読みください：

• カテゴリ別にナレッジ検索をルーティングしたい
• ユーザーに質問したり、AI Prompt を使用したりせずに分類を抽出したい
• すべてのソースを無差別に検索するため、ナレッジ検索の品質が低下している

ツール呼び出し情報の漏えいを防止 → prevent-tool-call-leaks.md

オーケストレーターが内部推論やツール呼び出しのメタデータをエンドユーザーに漏えいするのを防ぎます。

次のような場合にこのパターンをお読みください：

• エージェントの応答に生の JSON が表示されるとユーザーから報告があった
• オーケストレーターが間接的に呼び出すコネクターアクションがエージェントにある
• 応答に explanation_of_tool_call などの内部メタデータが含まれる

チャネルを考慮した動作 → channel-aware-behavior.md

System.Activity.ChannelId からホストチャネルを検出し、チャネル（Teams、M365 Copilot、Web チャット、Direct Line、音声）ごとに動作を制御します。

次のような場合にこのパターンをお読みください：

• あるチャネルでは機能するものが、別のチャネルでは動作しない（ファイルのアップロード、Adaptive Card のバリエーション、ハイパーリンクなど）
• Teams、M365 Copilot、Web、音声を識別したい
• 単純な =Lower(ChannelId) = "msteams" チェックが、msteams:Copilot やその他の複合チャネル ID ではひそかに失敗している

RAI エラー処理 → rai-error-handling.md

OnError トピックで Azure OpenAI のコンテンツフィルターエラーをサブコード別に分類し、テレメトリとともにカテゴリに応じたユーザーメッセージを返します。Azure OpenAI モデル専用です。Anthropic モデルや xAI モデルでは動作しません。

次のような場合にこのパターンをお読みください：

• RAI のコンテンツフィルター違反に対して、業界に特化した、または共感を示すエラーメッセージが必要
• カテゴリに応じた処理を行いたい（例：自傷行為には危機対応リソースを、ジェイルブレイクの試みにはセキュリティに関するメッセージを表示する）
• OnError、ContentFiltered、Azure OpenAI のコンテンツフィルター、RAI のサブコードについて知りたい

メッセージ内の改行 → line-breaks-in-messages.md

メッセージノードと質問ノード内で <br /><br /> を使用し、チャネルを問わず、段落間に安定した余白を表示します。

次のような場合にこのパターンをお読みください：

• ボットのメッセージが文字の壁のように感じられるとユーザーから報告があった
• 複数の質問やウェルカムメッセージを視覚的に区切りたい
• メッセージや質問における改行、<br />、書式設定について知りたい

ナレッジ検索中の待機メッセージ → knowledge-hold-message.md

ナレッジ検索中にランダムな待機メッセージを送信し、エージェントが処理中であることをユーザーに知らせます。

次のような場合にこのパターンをお読みください：

• エージェントのナレッジ検索に目立った遅延がある
• 遅延中にユーザーが会話を中断したり、質問を再送したりしている
• OnKnowledgeRequested、入力インジケーター、待機メッセージについて知りたい

決定論的な MCP 呼び出し → deterministic-mcp-calls.md

指示による促しや専用の子エージェントラッパーを使用して、MCP ツールの呼び出しの信頼性を高めるための回避策です。

次のような場合にこのパターンをお読みください：

• 特定のインテントに対して MCP ツールを毎回実行する必要があるが、オーケストレーターが呼び出しをスキップする
• MCP ツールでの呼び出しの強制や / 構文について知りたい
• ビジネス上重要なワークフローで決定論的なツール呼び出しが必要

Chain of Thought Logging → chain-of-thought-logging.md

複数ステップのオーケストレーション中に概要レベルの「思考」メッセージを送信し、可観測性と応答性の体感を向上させます。

このパターンを読むタイミング：

• エージェントが複数のツール、MCP サーバー、または連携する子エージェントを使用する場合
• 複数ステップの推論中にユーザーが長い無応答時間を経験している場合
• ユーザーがオーケストレーターの動作をデバッグまたは可観測性のトレースで確認したい場合
• ユーザーが複雑なフローにおけるストリーミング、入力中インジケーター、または進行状況メッセージについて尋ねた場合

Conversation History Variable → conversation-history-variable.md

エスカレーション、ログ記録、後続の自動化に使用するため、可能な範囲で会話の記録を変数に保存します。

このパターンを読むタイミング：

• ユーザーがライブエージェントへのエスカレーション用に会話のコンテキストを取得する必要がある場合
• 後続のツールまたはコネクタが入力として会話履歴を必要とする場合
• ユーザーが会話を Dataverse、チケット管理システム、またはメールに記録したい場合

Teams Production Hardening → teams-production-hardening.md

Teams および M365 Copilot エージェント向けに、再インストール、古いコンテキスト、リセット、診断、提案プロンプトを扱う、連携した 8 つの本番運用パターンです。

このパターンを読むタイミング：

• ユーザーが Microsoft Teams 上の Copilot Studio エージェントをデプロイまたは強化する場合
• 長時間続いた Teams の会話に戻った際、古いコンテキストが残っているとユーザーから報告された場合
• コンテキスト変数が Web チャットでは動作するものの、Microsoft 365 Copilot では動作しない場合
• ユーザーが診断情報を含む、より充実した OnError または Start Over のエクスペリエンスを求めている場合
• ユーザーが OnInstallationUpdate、OnInactivity、OnSystemRedirect、提案プロンプト、または Teams 固有の動作について尋ねた場合

パターンの組み合わせ

複数のパターンを 1 つのエージェントで組み合わせられます。一般的な組み合わせ：

• JIT Glossary + JIT User Context → 1 つの conversation-init OnActivity トピックに統合します（テンプレートは templates/topics/conversation-init.topic.mcs.yml）
• Date Context + JIT User Context → どちらもエージェントの指示に記述します。日付には Power Fx 式を、ユーザーコンテキストにはグローバル変数への参照を使用します
• Orchestrator Variables + JIT User Context → カテゴリで分類し、国でパーソナライズすることで、ナレッジのルーティングを正確に行います
• RAI Error Handling + Teams Production Hardening → OnError で最初に RAI サブコードを処理し、その後 Pattern 7 の汎用診断カードにフォールスルーします
• Knowledge Hold Message + Chain of Thought Logging → ナレッジ中心のエージェントには保留メッセージを、複数ツールを使うエージェントには CoT ログ記録を使用します。どちらも応答遅延の体感を軽減しますが、解決する問題は異なります
• Teams Production Hardening + JIT User Context → Pattern 4 はチャネルをまたいで Global.UserContext を設定します。ハードコードされた値を JIT User Context コネクタの呼び出しに置き換えると、実際のプロファイルデータを取得できます