宣言型エージェント構築のベスト プラクティス

宣言型エージェントは、指示、ナレッジ ソース、サポートされている機能を通じて、特定のビジネス シナリオに合わせて Microsoft 365 Copilot をカスタマイズします。 これらの手法を使用して、エージェントを集中させ、アクションを安全に構成し、進化に伴う動作を評価します。

定義された対象ユーザー、ユーザー タスク、予想される結果から始めます。 マネージド ランタイムと運用するサービスの境界については、「 宣言型エージェントのアーキテクチャ」を参照してください。

注

この記事では、Copilot のマネージド ランタイムを使用する宣言型エージェントについて説明します。 Microsoft 365 のグラウンディング データを取得するカスタム エンジン エージェントを構築している場合は、 Retrieval API のベスト プラクティス と アクセス許可と制限事項に従ってください。 このガイダンスは、宣言型エージェントのナレッジ ソースの構成とは別のものです。

宣言型エージェントのコンポーネント

エージェントの意図するタスクをサポートする各コンポーネントを選択します。 選択した オーサリング ツール と マニフェスト スキーマの制限に従います。

要素 ベスト プラクティス
Name エージェントの目的を伝える明確な名前を使用します。 エージェントビルダーは最大30文字まで使用できます。宣言型エージェント マニフェストでは、最大 100 個まで許可されます。
説明 1,000 文字の制限内で、タスクとドメインをいくつかの正確な文で要約します。 詳細な動作指示は [指示] フィールドに保持してください。
説明 エージェントの目的、サポートされるタスク、ソースとツールの使用、出力形式、エラー動作を 8,000 文字の制限内で定義します。
ナレッジ ソース 目的の質問に関連するソースを追加します。 サポートされているスコープ、更新性、アクセス許可、ライセンスを確認します。
組み込み機能 コード インタープリターや画像ジェネレーターなどの機能は、目的のタスクをサポートしている場合にのみ有効にします。
カスタム スキル (プレビュー) モジュール タスクの指示、リソース、スクリプトに スキル を使用します。 詳細な指示を複製するのではなく、構成されたスキルの概要を参照します。
アクション 外部サービスとの対話には、 MCP または API プラグイン を使用します。 各ツールの目的、インプット、アウトプット、および障害状態を説明します。
話の始め方 サポートされているタスクを示す代表的なプロンプトを提供します。 最小回数は必要ありません。 各プロンプトをテストし、選択したツールの制限に従います。

エージェント命令のベスト プラクティス

指示を使用して、エージェントが目的のタスクにどのようにアプローチするかを定義します。

  • 結果と境界を述べます。 エージェントがユーザーの作業を支援する内容、エージェントに必要な情報、サポートされていない要求にエージェントがどのように対応すべきかを説明します。
  • ソースとツールの使用を明示的にします。 どの構成済みのソース、機能、またはアクションが各タスクに適用されるかを特定します。 推測するのではなく、不足している入力を求めます。
  • プレゼンテーションとは別の手順。 順序が重要な場合は明確なタスク ステップを使用し、期待されるトーン、構造、応答の詳細レベルを指定します。
  • 不足している情報と障害を計画します。 使用できないソース、不完全な結果、アクセス拒否、失敗したアクションを成功を主張せずに処理する方法を説明する。
  • 指示を知識から切り離しておいてください。 命令の制限を回避するために、SharePoint ドキュメントやその他のナレッジ ソースに動作指示を配置しないでください。 取得されたコンテンツは、信頼された作成者が作成した命令コンテンツではありません。

モデル変更に関する詳細なパターン、例、ガイダンスについては、「 効果的な命令を記述する」を参照してください。 ナレッジと API 呼び出しを組み合わせるタスクについては、「 API プラグインを使用したエージェントの手順の記述」を参照してください。

適切なナレッジ ソースを選択する

エージェントが回答する必要がある質問に基づいて ナレッジ ソース を選択します。

  • 量よりも関連性を優先します。 リソースを、タスクに必要なファイル、サイト、チャットまたはその他のコンテンツに限定します。 SharePoint と埋め込みファイルについては、「 コンテンツ取得の最適化」に従ってください。
  • 取得を鮮度要件と一致させます。 ソース コンテンツと所有権を定期的に確認します。 範囲付き Web 検索では、基になるデータの直接クエリではなく、Bing でインデックス化されたコンテンツが使用されます。 現在の構造化データでは、代わりにサポートされている API または MCP アクションを評価します。 Web 検索のグラウンディングと動的コンテンツを参照してください。
  • 共有する前にアクセスを確認します。 目的の対象ユーザーと権限を代表するユーザーでテストします。 埋め込みファイルの共有動作を、元のファイルへのアクセスとは別に確認します。
  • 機能とライセンス サポートを確認します。 ソースとスコープ オプションは、作成ツールとテナント構成によって異なります。 ナ レッジ ソースのサポート マトリックス と ライセンス ガイダンスに従います。
  • 流暢さだけでなく、グラウンディングを評価します。 既知の回答を使用して質問をテストし、回答と引用が意図したソースと一致することをチェックします。 回答がない質問を含めます。

ソースを追加しても、エージェントが組み込みのモデルナレッジを使用できなくなるわけではありません。 シナリオでソースに基づいた応答が必要な場合は、 behavior_overrides.special_instructions.discourage_model_knowledge を true するように設定し、指示内で意図されたソースの使用を強調します。 このコントロールは、応答が構成されたソースのみを使用することを保証するものではありません。 証拠が見つからない場合は、引き続きソースの帰属と行動を評価します。 構成されたナレッジ・ソースに対する地上応答および特別な指示リファレンスを参照してください。

安全なアクションを設計する

外部サービスとサポートされている対話にはアクションを使用し、ナレッジ ソースと区別します。 接地に使用される Copilot コネクタは、外部データを変更する API または MCP ツールと交換できません。

  • 操作を正確に記述します。 ツールを使用するタイミング、必要なパラメーター、予想される結果とエラーを説明します。 REST API の場合は、 OpenAPI ドキュメントのガイダンスに従ってください。
  • 統合の確認を構成します。 API プラグインの場合は、isConsequentialではなく OpenAPI 拡張機能x-openai-isConsequentialを使用し、副作用のある操作を結果としてマークします。 MCP ツールの場合は、読み取り専用のツールに対してのみ readOnlyHint を使用します。 サポートされている設定と動作については、 MCP および API プラグインの確認プロンプト に従ってください。
  • サービスへのアクセスを強制します。 サポートされている 認証方法 を使用し、外部サービスでの承認と入力を検証します。 指示と確認プロンプトは、それらのチェックに取って代わるものではありません。
  • エラーと繰り返しの要求を考慮した設計。 テストの拒否確認、期限切れの認証、無効な入力、サービス エラー。 データを変更する操作の場合は、再試行で意図せず変更が繰り返されないようにします。

プラン データ、プライバシー、セキュリティを使用して、各アクションのデータ フロー、アクセス許可、人間による監視要件を識別します。

テストと反復処理

エージェントを変更する前に予想される動作を定義し、テスト ケースの繰り返しセットを保持します。 オーサリング ツールのテスト エクスペリエンスを使用して早期フィードバックを取得し、展開されたエージェントを目的のホストで検証します。

テスト領域 検証対象
サポートされているタスク 会話のきっかけ、現実的なユーザーの言い回し、フォローアップの質問により、意図した結果が得られます。
情報が不足しているか、サポートされていない エージェントは必要な入力を求め、入手できない証拠を説明し、事実をでっち上げたり、失敗したアクションが完了したと主張したりしません。
根拠付けとアクセス許可 回答と引用は意図したソースと一致します。 異なるアクセス権を持つユーザーをテストし、制限された情報が公開されていないことを確認します。
アクションと失敗 実際の外部結果と応答を確認します。 テストの確認、取り消し、認証の失敗、サービス エラー、繰り返しの要求。
ホスト エクスペリエンス デプロイする予定のサポート対象の各アプリをテストします。 すべてのアプリで同じ動作を想定するのではなく、ドキュメントのコンテキスト、応答の表示、使用可能な機能を確認します。
パフォーマンスと変更点 応答時間を測定し、命令、知識、ツール、スキル、またはプラットフォームの動作が変更された後に回帰ケースを再実行します。

指示を記述していないユーザーを含めて、テストで予期しない言い回しや思い込みをキャプチャできるようにします。 再現可能なユーザーから報告された問題を回帰ケースに変えます。

テストケースの設計、アサーション、反復可能な評価については、「 エージェント評価の概要」を参照してください。 リリース チェックについては、「 責任ある AI 検証 」および 「プラグインの検証とテスト」を参照してください。