AI エージェントとは、ツールとともにループで動く言語モデルです。何をするか決め、ツールを呼び、結果を読み、タスクが終わるまで続けます。エージェント向けのプロンプトは、1 回の回答のためのプロンプトとは異なります。もう質問を書くのではありません。あなたなしで多くの判断を下すものの、運用指示書を書くのです。
ワークフローかエージェントか
まず、そもそもエージェントが必要かどうかを決めます。
| AI ワークフロー | AI エージェント | |
|---|---|---|
| ステップを決めるのは | あなたのコード | モデル |
| 予測可能性 | 高い | 低め |
| コストと遅延 | 低く、事前に分かる | 高く、変動する |
| 向いているもの | 手順が分かっているタスク | 見つけたものによって道筋が変わるタスク |
| デバッグ | ステップごと | トレース全体を読む |
フローチャートが描けるなら、プロンプトチェーンでワークフローを作ります。バグの調査や調べものなど、ステップの数や順序が事前に分からない場合に、エージェントを使います。
エージェントのプロンプトの構成要素
エージェントの挙動は、読み取る 4 つのものから生まれます。システムプロンプト、ツール定義、タスク、そして返ってくる結果です。それぞれを意図して書く必要があります。
1. システムプロンプト
6 つのことを網羅します。
役割と目標。 エージェントが何のためのものかを 2 文で。
運用ルール。 何かを変更する前に調べる、小さなステップを優先する、結果を検証するなど、どう作業するか。
境界。 してはいけないことと、承認が必要なこと。
問題への対処。 ツールのエラー、情報不足、曖昧さ。
いつ止まるか。 タスクが完了したことを意味する条件と、労力の上限。
どう報告するか。 最終回答に含まれる内容。
You are a coding agent working in the user's repository.
## How to work
- Read the relevant files before proposing a change.
- Make the smallest change that satisfies the task.
- After editing, run the tests that cover the change.
## Boundaries
- Do not modify files outside the repository.
- Do not delete files or run destructive commands without asking.
- Do not change public interfaces unless the task says so.
## When things go wrong
- If a command fails, read the error and try a different approach once.
If it fails again, stop and report what you tried.
- If the task is ambiguous, ask one question before starting.
## When to stop
- Stop when the acceptance criteria are met and the tests pass.
## Final report
- What changed and why, files touched, how it was verified, and
anything left undone.
ルールの理由が自明でない場合は、その理由を説明します。エージェントは、あなたが列挙していない状況に出会います。理由付きのルールのほうが、単なる禁止より、うまく一般化されます。
2. ツール定義
モデルは、名前と説明を読んでツールを選びます。エージェントが間違ったツールを使う最も多い原因は、曖昧な定義です。
- ツールには、することにちなんだ名前を付ける。
query2ではなくsearch_orders。 - それぞれをいつ使い、いつ使わないかを説明する。
- 何が返るかを書く。 形式と上限を含めて。
- パラメーターを曖昧さなく定義する。 型、形式、許可される値、例。
- 機能が重なるツールを避ける。 2 つのツールのどちらでもできるなら、モデルの選択は一貫しなくなります。
- 対処できるエラーを返す。 「invalid input」ではなく「日付は YYYY-MM-DD でなければなりません」。
よく説明された少数のツールは、似たツールを大量に並べたものより優れています。Model Context Protocolは、ツールをエージェントに記述し提供する方法を標準化します。
3. タスクのプロンプト
エージェントには 1 文ではなく、仕様を渡します。自律性が高いほど、最初のブリーフが重要になります。
## Objective
Add rate limiting to the public API.
## Requirements
- 100 requests per minute per API key.
- Return 429 with a Retry-After header when exceeded.
## Constraints
- Existing clients must keep working: no changes to response schemas.
## Acceptance criteria
- New tests cover the limit and the 429 response.
- The existing test suite passes.
受け入れ基準は、エージェントに終わったことを知る手段を、あなたに確認する手段を与えます。PromptFlowEngine の VS Code 拡張機能は、1 行のタスクをこの構造に変換し、関連ファイルを添付します。
4. コンテキスト管理
エージェントが読んだものはすべてそのコンテキストに残り、毎ステップ読み直されます。放っておくと、コンテキストは古いツール出力でいっぱいになり、コストが上がり、品質が下がります。
- コンパクトなツール結果を返す。 ペイロード全体ではなく、必要なフィールドだけ。
- 使い終わった古い結果は要約するか捨てる。
- 長いタスクでは、エージェントが読み書きできるファイルに、永続的なメモをコンテキストの外で保持する。
- 委任する。 自己完結したサブタスクを、新しいコンテキストを持つサブエージェントに任せ、結論だけを受け取る。
トークン最適化を参照してください。
サブエージェント向けのプロンプトを書く
あるエージェントが別のエージェントに指示するとき、ブリーフは受け手が知るすべてです。良い委任プロンプトは、次を述べます。
- 目標と、それがなぜ重要か。
- すでに分かっていること。作業の重複を避けるため。
- 求める出力そのものと、その形式。
- 境界。何に触れ、何を触れずにおくか。
曖昧なブリーフを書くオーケストレーターのエージェントは、曖昧な成果を受け取ります。ここは自動チェックが役立つ場面です。エージェントは、委任する前に、ブリーフの下書きを PromptFlowEngine の MCP ツールに通して、目標や出力形式の欠落を見つけられます。
エージェントの安全性
エージェントは行動するので、ミスや攻撃には結果が伴います。
- 最小権限。 各ツールには、機能する最も狭い権限を。既定は読み取り専用。
- 元に戻せない操作には承認を。 削除、送信、支払い、デプロイ。
- ツールの結果は信頼できないものとして扱う。 Web ページやファイルには、エージェントを狙った指示が含まれうます。プロンプトインジェクションを参照してください。
- 上限。 最大ステップ数、最大支出、タイムアウト。
- シークレットをコンテキストに入れない。 認証情報はツールに直接渡します。個人情報とシークレットの検出を参照してください。
- すべてのツール呼び出しをログに記録する。 実行をレビューできるように。
よくある失敗パターン
| 症状 | ありそうな原因 | 対策 |
|---|---|---|
| 同じ操作をループする | 停止ルールもステップ上限もない | 両方を追加する |
| 早すぎる成功宣言 | 受け入れ基準がない | 定義し、検証を必須にする |
| 間違ったツールを使う | 説明が重なっている、または曖昧 | ツールの説明を書き直す |
| 頼まれた以上のことをする | 範囲が述べられていない | 境界を明示する |
| 以前の指示を忘れる | コンテキストが過負荷 | 結果を刈り込む、要約する、メモを使う |
| ファイル内のテキストに従う | 信頼できないコンテンツが示されていない | データとして示す。ツールを制限する |
エージェントの評価
経路ではなく結果を採点します。テストは通ったか、正しいレコードが更新されたか、答えは正しいか。そのうえでトレースを見直し、無駄なステップや危険な操作がないかを確認します。結果が良いと分かっているタスクのセットを保ち、プロンプト、ツール、モデルが変わるたびに再実行します。プロンプトのテストと評価を参照してください。
これらすべての土台にある推論ループについては、ReAct プロンプティングを参照してください。