コンテキスト エンジニアリングのベスト プラクティス

効果的なコンテキスト グラウンディングを使用すると、エージェントは作業中のタスクにおいて、適切なナレッジに適切なタイミングで確実にアクセスできます。正しく実装されていれば、コンテキスト グラウンディングによって精度が向上し、パフォーマンスが改善するほか、トークン コストが削減されます。

このセクションでは、コンテキスト グラウンディングを使用してコンテキスト ソースを設定および保守する方法を説明します。また、インデックスの設定、スキーマの設計、および継続的な評価のベスト プラクティスについても紹介します。

コンテキスト グラウンディング サービスについて詳しくは、専用のドキュメント「コンテキスト グラウンディングについて」をご覧ください。

コンテキスト グラウンディングとは何かを理解する

エージェントは、ドキュメント、FAQ、メール、SOP などのエンタープライズのナレッジにコンテキスト グラウンディングを使用して接続します。この接続を有効化するには、Orchestrator でインデックスを作成して、Studio Web のエージェントにアタッチします。

コンテキスト グラウンディングは、以下においてエージェントを支援します。

• 業務に固有のデータについて推論を行う
• ハルシネーションや捏造を防止する
• 管理された最新の知識を使用して回答する
• スキーマ制約が設定されている場合、ソースを引用する

コンテキスト グラウンディングの設定のベスト プラクティス

信頼性と即応性が高いエージェントを構築するには、コンテキストを設計および調整する際に、以下の核となるプラクティスに従います。

わかりやすく、バージョン管理されたインデックス名を使用する

インデックスに名前を付ける際は、明確で一貫性のあるパターンを使用します。例: HR-Policies-2025-Q3

これにより、以下が容易になります。

• 以前のインデックス バージョンにロールバックする
• 異なるナレッジ ベースを使用して A/B テストを実行する
• 長期にわたって更新を追跡する

コンテンツが大幅に変更された場合は、Orchestrator で新しいインデックスを作成し、それに応じてエージェント定義を更新します。

適切な取り込みモードを選択する

インデックスを作成する際は、コンテンツに合った取り込みモードを選択します。

• ベーシック モード: ほぼプレーン テキストで構成されるドキュメントに最適です。
• 高度な設定モード: テキストと画像が組み合わさったファイル (スキャンした PDF やインフォグラフィックなど) に使用します。

どのモードを選択するかは、カバレッジと OCR 関連のコストの両方に影響します。ドキュメントの種類と、ビジュアル コンテンツを取得することがどの程度重要かに基づいて選択してください。

定期的な同期の周期を維持する

インデックスの新規性を維持することで、エージェントは確実に最新の情報を参照できます。インデックスの内容を更新するには、Orchestrator の [同期] アクション、または Studio の [コンテキスト グラウンディングのインデックスを更新] アクティビティを使用します。ソース コンテンツの更新頻度に基づいて、定期的な同期のスケジュールを設定できます。

結果の数としきい値のスコアを調整する

• 結果の数: 取得するコンテキスト チャンクの数を制御するには、この設定を調整します。結果を増やすと再現率が向上しますが、トークンの使用量が増えます。
• しきい値: 関連性の低いコンテキストをフィルター処理して除外します。既定値は 0 です。関係のない文章が多く返される場合は、しきい値を上げると適合率を向上できます。ただし、しきい値を 0 (ゼロ) より高く設定すると、関連のあるチャンクがフィルター処理されて応答から除外され、ハルシネーションにつながる可能性があることに注意してください。

これらのパラメーターのバランスを取り、トークンの上限を超えることなく高シグナルのコンテキストを確保できるようにしてください。

エージェントの設計時にコンテキストの明確な説明を使用する

コンテキストのインデックスをエージェントに追加する際は、インデックスに含まれる内容について短く正確な説明を入力します。これは、エージェントが実行中にナレッジを検索して使用する際に役に立ちます。

複数のコンテキスト ソースを使用する場合、説明があると特に役に立ちます。

スキーマをエージェントの期待値に一致させる

該当する場合、特に JSON などの構造化された出力の場合は、応答スキーマを定義します。これにより、エージェントが回答を正しい形式に設定し、コンテキストからの情報のみを含めるようにします。

信頼性を向上させるには、システム プロンプトにスキーマの例を含めます。

反復処理を行うべき状況と方法

次のような場合、コンテキストの設定を見直します。

• エージェントから期待される結果が得られない
• 無関係なコンテンツがトレースに表示される
• エージェントがトークンの上限を超える、または「トークンの超過」エラーで失敗する
• ドキュメント スキーマが変更された
• 新しいユース ケースまたはスコープの拡張が発生した

テスト環境での実行と運用環境での実行のトレース ログを使用して、問題の原因がコンテキストの品質、量、またはインデックスのパラメーターのいずれにあるかを診断します。

よくあるエラーとその修正方法

コンテキスト グラウンディングのよくある問題を特定して解決するには、次の表を使用します。各行は、トレースで確認される可能性のある検出シグナルと、それを修正するための推奨アクションを示しています。

表 1. コンテキスト グラウンディングの問題のトラブルシューティング

問題の内容	検出シグナル	推奨される修正方法
関連するドキュメントがインデックスにあるはずなのに、エージェントが期待どおりに回答しない	結果が見つかりません。	最新データを確認し、関連するドキュメントを追加して、インデックスを同期する しきい値を下げる
期待される回答が得られない	高いしきい値によるフィルター処理がトレースに表示される	しきい値を下げるか、ドキュメントのカバレッジを改善する
コンテキスト ウィンドウがオーバーフローする	エージェントが「トークンの超過」で失敗する	結果の数を減らすか、ユーザー入力を短くする
古い情報が返される	古いタイムスタンプがトレースに表示される	インデックスを同期または再構築し、エージェントを再パブリッシュする

コンテキストの品質を評価する

Agent Builder で評価の実行を使用して、コンテキスト ソースがエージェントの目的をどの程度サポートしているかをテストします。

評価の実行では、以下を行う必要があります。

• 実際の多様なプロンプトを含める
• トレースを確認し、どのチャンクが取得されているかを調べる
• インデックスを更新または置換する際は回帰テストを含める

また、ツールのシミュレーションを使用してモック コンテキストで実行をシミュレートすることによって、インデックスを完全に更新する前にパフォーマンスをプレビューすることもできます。

概要チェックリスト

次のチェックリストを使用して、コンテキスト グラウンディングの設定がベスト プラクティスに従っていることを確認します。

• インデックス名がバージョン管理されていて、わかりやすい名前になっている
• 取り込みモードがドキュメントの種類に一致している
• インデックスが定期的に同期されている
• 結果の数としきい値が調整されている
• コンテキストの説明が有益である
• スキーマが定義されていて、プロンプトで適用されている
• トレース ログを使用して、よくあるエラーが追跡および解決されている

プロンプトのテンプレートの例

以下のテンプレートは、エージェントのシステム プロンプトの出発点として使用します。ご自身の特定のユース ケースに合わせてカスタマイズしてください。

QA/ナレッジの検索

You are an enterprise knowledge assistant.
Goal: Answer user questions using ONLY approved company documents.
Constraints:
- Cite each answer with source title and section.
- If confidence is low or no relevant context was retrieved, ask a clarifying question instead of guessing.
- Respond in Markdown unless JSON is requested.

# Processing Steps
1. Interpret the user question.
2. Review retrieved context below.
3. Use only information found in context; do not fabricate.
4. Provide a concise answer and cite sources.

構造化された抽出と検証

You are an extraction agent that maps document content into a structured schema.
Goal: Populate all required fields from retrieved document snippets.
Constraints:
- Return valid JSON matching the schema.
- Use null if field not found; do NOT guess.
- Provide a confidence score 0‑1 for each field.
- Include source_span metadata (doc_id, chunk_id).

# Steps
1. Read user instruction for target doc type.
2. Review retrieved context.
3. Extract fields.
4. Validate required fields; request escalation if missing critical values.

推論とアクションの選択

You are an operations triage agent.
Goal: Decide the next best action based on policies and current case details.
Constraints:
- Choose only from the allowed actions list.
- Provide short rationale.
- Output as JSON: {"action":string,"reason":string,"evidence_sources":[...]}

# Allowed Actions
{{ACTION_LIST}}