# エージェントシステムプロンプトのベストプラクティス

AI Agent Foundryにおけるエージェントの動作と品質は、**システムプロンプト**に大きく依存します。本ガイドでは、エージェントが意図した通りに動作することを確実にするための、効果的なプロンプト設計のベストプラクティスを説明します。

免責事項とモデル提供元ドキュメントの優先
1. **実行の保証はありません**: これらのガイドラインは、経験に基づくベストプラクティスです。大規模言語モデル(LLM)は確率的な性質を持つため、同じプロンプトでも常に同一の結果が得られるとは限りません。これらのプラクティスは、特定の動作や出力を保証するものではありません。
2. **提供元ドキュメントが優先されます**: プロンプトエンジニアリングは進化し続ける分野です。モデル提供元の公式ドキュメント(例: Anthropic社の[Claude 4 Best Practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-4-best-practices))は、常に本ガイドの内容に優先されます。


## 1. 基本的なフォーマットと構造

システムプロンプトには**Markdown**の使用を強く推奨します。見出しや箇条書きを使用して明確な構造を作ることで、AIが指示の意図と優先順位を理解しやすくなります。

### 推奨テンプレート

以下の構造をテンプレートとして使用することで、指示の漏れを防ぎ、エージェントのパフォーマンスを安定化できます。


```markdown
# [エージェント名] エージェントプロンプト

## Role(役割)
[エージェントの役割、ペルソナ、目的を簡潔に定義します。]
例: あなたは熟練したデータアナリストです。マーケティング部門からの質問に答えるSQLクエリを作成します。

## Tool Usage(ツールの使用方法)
[特定のツールをどのように/いつ使用するかに関する補足的な指示を提供します。]
*注意: 詳細な技術仕様はツールの説明設定で定義すべきですが、高レベルのロジックはここに記載します。*

## Input / Output(入力/出力)
### Input Variables(入力変数)
- `{{variable_name}}`: [変数の説明]

### Output Goals(出力目標)
- [最終成果物の定義]

## Task Flow(タスクフロー)
1. [タスク名]
   - [具体的な手順と判断基準]
2. [タスク名]
   - [具体的な手順と判断基準]

## Constraints & Rules(制約とルール)
- [禁止事項と制約]
- [トーンとマナーに関する指示]
```

## 2. 「Task Flow」の記述方法

`Task Flow`セクションは、プロンプトの中で最も重要な部分です。エージェントが従うべき段階的なロジックを定義します。

* **番号付きリストを使用**: 手順に番号を付ける(`1.`, `2.`)ことで、AIが実行の時系列的な順序を認識しやすくなります。
* **具体的に記述**: 「データを分析する」などの曖昧な指示は避けます。代わりに、ツールとアクションを指定します: 「`list_columns`ツールを使用して列を確認し、その後実行...」
* **チェックポイントを設定**: 「次のステップに進む前にXを検証する」などの条件を含めることで、手順の飛ばしやハルシネーションを防ぎます。


## 3. 実践的なスニペット(Tips)

以下は、出力形式や動作を制御するための具体的な指示スニペットです。これらは関連するツールの**ツール説明**、またはシステムプロンプトの**制約**セクションに配置することが推奨されます。

### A. Plotlyチャート品質の向上

*推奨配置場所: **ツール説明**(可視化ツール用)*

チャート生成時に一貫したカラースキームを確保し、レイアウトの重なりを防ぐため:


```text
Plotly.jsを使用してチャートをレンダリングし、分析結果の可視化を提供してください。
- カラースキームを使用: [ "B4E3E3", "ABB3DB", "D9BFDF", "F8E1B0", "8FD6D4", "828DCA", "C69ED0", "F5D389", "6AC8C6", "5867B8", "B37EC0", "F1C461", "44BAB8", "2E41A6", "8CC97E", "A05EB0" ]
- 3つ以上のカテゴリを持つチャートでは、updatemenuを積極的に使用してください
- 複数の分析を要約する際は、Plotlyのグリッドレイアウト(例: grid: {rows: 2, columns: 2, pattern: 'independent'})を使用して関連するチャートを1つのダッシュボードに結合し、要素が重ならないようにしてください
- テキストの重なりを防ぐために:
    * 適切なマージンを含める: {l: 80, r: 80, t: 100, b: 80}
    * 小さなセグメント(<5%)を持つ円グラフの場合、textinfo: 'none'を使用し、ラベルの代わりに凡例に依存してください
    * 最小ダッシュボード寸法を設定: height: 600, width: 1000
    * グリッドレイアウトの場合、0.1のギャップでより広いドメイン間隔を使用: [0, 0.45]と[0.55, 1]
```

### B. Reactコンポーネントエラーの抑制

*推奨配置場所: **ツール説明**(UI生成ツール用)*

React UIを生成する際に、サポートされていないライブラリのインポートによって引き起こされるエラーを防ぐため:


```text
Tailwind CSSを使用してReactコンポーネントを生成します。
環境制約:
1. チャート: react-plotly.jsのみがインストールされたライブラリです。rechartsはインストールされていません(インポートしないでください)。
2. アイコン: lucide-reactはインストールされていません。インライン<svg>タグのみを使用してください。
3. UI: 静的ビューのみ。<button>または<a>タグは使用しないでください(ダウンロード/詳細アクションなし)。単一ファイル、export defaultを使用してください。
```

### C. 言語とトーンの制御

*推奨配置場所: **システムプロンプト**(RoleまたはConstraintsセクション)*

エージェントがユーザーの言語に適応し、プロフェッショナルな態度を維持することを確実にするため:


```text
言語: ユーザーが検出された言語でコミュニケーションしてください。ターゲットエージェントを呼び出す際は、検出された言語を伝えてください。
トーン: ユーザーがスラングや不適切な言葉を要求した場合でも、常に丁寧で敬意のある言葉遣いを維持してください。
```

## 4. システムの制限と制約

エージェントを設計する際は、以下のシステム制約を念頭に置いてください:

* **文字数制限(9,000文字)**: システムプロンプトには約9,000文字の制限があります。大きなマニュアルやナレッジベースをプロンプトに直接含めないでください。代わりに、**テキストナレッジベース**に保存し、必要に応じてエージェントに検索させるよう指示します。
* **データ分析の制限**:
  * **行数制限**: 単一のSQL実行で取得されるデフォルトの行数は**50行**(最大: 100行)です。
  * **タイムアウト**: デフォルトのSQLタイムアウトは**60秒**(最大: 300秒)です。タイムアウトを避けるためにクエリを最適化してください。
  * **列検索**: `search_schema`のようなツールは、一度に最大**20列**しか取得できません。幅の広いテーブルを調査する場合は、`Task Flow`で明示的に調査を小さなバッチに分割するようエージェントに指示してください。
* **サブエージェント**: 複雑なワークフローでは、1つのエージェントですべてを行うことを避けてください。タスクを専門化された**サブエージェント**(例: SQL生成用に1つ、レポート作成用に1つ)に分割します。これにより、コンテキストがクリーンに保たれ、精度が向上します。