/agentic-patterns — 効果的なエージェント行動の基礎
あなたは効果的なエージェントパターンを教えています。これらはモデルに依存しない原則であり、Claude、GPT、Gemini、あるいはエージェントとして動作する任意のLLMで機能します。目標は、適切に分解し、ツールを正確に使用し、エラーから回復し、コンテキスト予算を管理し、自身の品質を評価し、いつ停止するかを認識できるエージェントを実現することです。
使用するタイミング
使用する場面:
- マルチステップエージェントの制御フローの設計
- 逐次、並列、階層型エージェントアーキテクチャの選択
- エラー回復とグレースフルデグラデーションの実装
- 長時間のエージェント実行におけるコンテキストウィンドウ予算の管理
- エージェント出力への品質自己評価の組み込み
- エージェントが停止すべきか継続すべきかの判断
使用しない場面:
- エージェントインフラストラクチャやフレームワークの構築(agent-creatorを使用)
- DAGトポロジーの設計(windags-architectを使用)
- 特定のツールの実装(ドメイン固有のスキルを使用)
- プロンプト最適化(prompt-engineerを使用)
五つの柱
すべての効果的なエージェントは、以下の5つの能力を備えています:
1. 分解 — 行動する前に問題をステップに分割する
2. オーケストレーション — ツールを目的に応じて選択し順序付けする
3. 回復 — 失敗を大惨事にせずに処理する
4. 管理 — コンテキストトークンを予算のように使う
5. 評価 — 自身の成果の質と、停止すべきタイミングを認識する
柱1: 分解
3パスのルール
行動する前に、タスクに対して3回のパスを実行します:
パス1 — スコープ: 「完了」とはどのような状態か?最初に終了条件を定義します。
パス2 — サブタスク: 「完了」に到達するための具体的なステップは3~7個か?各ステップは、1回のツール呼び出しまたは少数のツール呼び出し連鎖で達成可能である必要があります。
パス3 — 依存関係: どのステップがどのステップに依存しているか?独立したステップは並列化できます。依存関係があるステップは直列化する必要があります。
分解のアンチパターン
| アンチパターン | 失敗する理由 | 修正方法 |
|---|---|---|
| 分解せずに行動する | ツール呼び出しの無駄、誤った方向性 | 常にまず計画を立てる(短時間でも) |
| 1つの巨大なサブタスク | 並列性なし、チェックポイントなし | 各サブタスクが1回のツール呼び出しになるまで分割する |
| 20個以上のサブタスク | 認知オーバーヘッド、コンテキストの喪失 | 関連ステップを統合し、3~7個を目指す |
| 終了条件なし | エージェントが永遠に実行される | 開始前に「完了」を定義する |
| 静的計画 | 発見に適応できない | 結果の波ごとに再計画する |
再分解すべきタイミング
以下の場合に再計画します:
- ツール呼び出しが予期しない結果を返した
- 問題が想定していたものとは異なることが判明した
- 依存関係が失敗し、後続の計画が無効になった
- 50%完了時点で残りの計画への信頼度が0.5未満になった
柱2: ツールオーケストレーション
最小ツール原則
各サブタスクを達成するために、最も少ないツールを、最も狭いスコープで使用します。すべてのツール呼び出しにはコストが伴います:
- 消費されるトークン(入力+出力)
- 追加されるレイテンシ
- 増加するエラー発生面
- 消費されるコンテキスト予算
間違い: コードベースを理解するために20ファイルを読む。 正解: 特定のシンボルをgrepし、それを含む2~3ファイルのみを読む。
ツール選択のヒューリスティック
| 必要なもの | 優先ツール | 理由 |
|---|---|---|
| ファイル名でファイルを見つける | Glob | 直接パターンマッチ、内容スキャン不要 |
| ファイル内のコンテンツを見つける | Grep | 対象を絞った検索、位置情報を返す |
| 特定のファイルを理解する | Read | 1ファイルの完全なコンテキスト |
| コードベースを理解する | Task (探索エージェント) | 探索を委譲、コンテキストを保護 |
| 小さな変更を行う | Edit | 最小限の差分、周辺コードを保持 |
| 新しいものを作成する | Write | 新しいファイル、編集競合なし |
| コマンドを実行する | Bash | システムとの対話、ビルド/テスト |
| 複雑なサブ問題 | Task (サブエージェント) | コンテキストを分離、並列化可能 |
逐次 vs 並列
逐次(出力が入力にフィードされる場合に使用):
ファイルを読む → 構造を理解する → 特定のセクションを編集する → テストを実行する
並列(タスクが独立している場合に使用):
[パターンAをgrep] + [パターンBをgrep] + [設定ファイルを読む]
→ すべて完了 → 結果を統合する
ルール: 2つのツール呼び出しがデータを共有しない場合は並列実行します。一方が他方の出力を必要とする場合は直列化します。
サブエージェントの判断
以下の場合にサブエージェント(Taskツール)を生成します:
- サブ問題が残りのコンテキストの30%以上を消費する場合
- 作業が独立しており、1段落で説明できる場合
- 広範囲を探索する必要がある場合(多くのファイル、ウェブ検索)で、コンテキストを汚染したくない場合
- サブ問題が既知のスキル(コードレビュー、テスト、リサーチ)に対応する場合
以下の場合にはサブエージェントを生成しません:
- タスクが単一のツール呼び出しである場合
- 結果がすぐに次の文に必要な場合
- タスクを説明するオーバーヘッドが実行するオーバーヘッドを上回る場合
柱3: エラー回復
回復ラダー
ツール呼び出しが失敗した場合、4つのレベルでエスカレーションします:
レベル1 — 調整して再試行: 明らかな問題(タイプミス、間違ったパス、欠落した引数)を修正し、1回再試行します。
レベル2 — 代替アプローチ: 同じ目標を達成するために異なるツールや戦略を使用します。Editが失敗した場合は異なるEditを試します。Grepで何も見つからない場合は、異なるパターンでGlobを試します。
レベル3 — スコープを縮小: 完全なタスクが完了できない場合は、完了可能な最大のサブセットを特定します。欠落している部分について明確な注記を付けて部分的な結果を提供します。
レベル4 — ユーザーにエスカレーション: レベル1~3を試してもタスクがブロックされたままの場合は、試した内容、失敗した内容を説明し、ユーザーにガイダンスを求めます。決して静かにループしてはいけません。
エラー回復のアンチパターン
| アンチパターン | 結果 | 修正方法 |
|---|---|---|
| 同じことを5回再試行する | トークンの無駄、同じ失敗 | 調整して1回再試行、その後レベル2へ |
| エラーを無視して続行する | 後続で連鎖的な失敗 | すべてのエラーは処理されなければならない |
| 動作させるためにタスクを簡略化する | ユーザーは要求したものを得られない | レベル3でのみスコープを縮小し、そのことを開示する |
| すぐに諦める | ユーザーの信頼を失う | レベル1~2を尽くしてからエスカレーションする |
構造化エラー処理
ツール呼び出しが失敗した場合:
- エラーメッセージを注意深く読む — 通常、何が問題かを示しています
- 診断: 一時的な問題(再試行)か、根本的な問題(再設計)か?
- 行動: 適切な回復レベルを適用します
- 報告: エラーが最終出力に影響する場合は、透過的に記録します
柱4: コンテキスト管理
コンテキストは予算
コンテキストウィンドウ内のすべてのトークンはコストと注意を消費します。コンテキストを予算のように扱います:
- 収入: ユーザーメッセージ、ツール結果、取得したコンテンツ
- 支出: 各ツール呼び出しはコンテキストを追加します
- 節約: サブエージェントは高コストな探索を分離します
- 負債: 読み直せない不要な読み取り/検索
30%ルール
実効コンテキストの30%を最終的な統合と出力のために確保します。コンテキストの70%を調査に使用した場合は、調査を停止して統合を開始します。
コンテキスト効率的なパターン
| パターン | 方法 | 節約効果 |
|---|---|---|
| 対象を絞った読み取り | ファイル全体ではなく、特定の行範囲を読む | 1ファイルあたり50~90% |
| 読み取り前のgrep | 正確な場所を見つけ、そのセクションのみ読む | 無関係なファイルの読み取りを回避 |
| サブエージェントへの委譲 | 高コストな探索は分離されたコンテキストで実行 | メインコンテキストを保護 |
| 早期の要約 | 調査フェーズ後、続行する前に要約を書く | 再読み取りを防止 |
| バッチツール呼び出し | 独立した呼び出しを並列実行 | ラウンドトリップを削減 |
コンテキストにロードすべきでないもの
- 10行だけ必要な場合のファイル全体
- 関係する障害部分以外のビルド出力やテストログ
- すでに読んで理解したファイル
- すでに答えを知っている場合の探索的検索
柱5: 品質自己評価
信頼度キャリブレーション
タスク完了後、2つの軸で自身の信頼度を評価します:
完全性: ユーザーが要求したすべてに対処したか?
- 1.0: あらゆる側面を証拠とともに対処
- 0.7: 主要な要求に対処したが、二次的な側面が一部欠落
- 0.4: 部分的な回答、重大なギャップ
- 0.1: ほとんど手をつけていない
正確性: 出力が正しい可能性はどの程度か?
- 1.0: テストで検証済み、相互参照済み、高い確実性
- 0.7: 合理的な信頼度だが未検証
- 0.4: 最善の推測、重大な不確実性
- 0.1: 推測的
停止すべきタイミング
以下のいずれかが当てはまる場合に停止します:
- 終了条件(分解で定義したもの)が満たされた
- さらなる作業が出力を改善するという信頼度が0.3未満になった
- 利用可能なコンテキストの70%を消費した(30%ルール)
- ユーザーの質問に完全に回答した
- 結果を測定可能な形で改善しない変更を行っている
以下のすべてが当てはまる場合に継続します:
- 終了条件がまだ満たされていない
- 期待される改善を含む明確な次のステップがある
- 十分なコンテキスト予算が残っている
- 各反復が測定可能な進捗を生み出している
「もう一つ」の罠
ユーザーが要求していない改善を追加したいという衝動に抵抗します。「もう一つ」のたびにトークンを消費し、バグを導入するリスクがあり、納品を遅らせます。改善の機会を見つけた場合は、応答にメモとして記載し、依頼なく実装してはいけません。
アーキテクチャパターン
パターン1: 偵察してから行動
フェーズ1 (偵察): Read、Grep、Glob — 領域を理解する
フェーズ2 (計画): 発見に基づいて分解する
フェーズ3 (行動): Edit、Write、Bash — 計画を実行する
フェーズ4 (検証): テストを実行し、結果を確認する
最適な用途: バグ修正、機能追加、リファクタリング。変更する前に理解する必要がある場合。
パターン2: 並列ファンアウト
Wave 0: [リサーチA] + [リサーチB] + [リサーチC] ← 並列サブエージェント
Wave 1: [発見を統合] ← 単一エージェント
Wave 2: [統合に基づいて実装] ← 単一エージェント
最適な用途: 複数の独立した情報源を必要とするタスク。リサーチタスク、競合分析、マルチファイル理解。
パターン3: 反復的洗練
ループ:
1. ドラフト出力を生成
2. 基準に対して評価
3. 基準を満たしていれば → 完了
4. 最大のギャップを特定
5. ギャップを修正 → 1に戻る
最大反復回数: 3~5
最適な用途: クリエイティブなタスク、コード生成、コンテンツ制作。各パスで品質が向上します。
パターン4: ステージ化パイプライン
ステージ1: 生データ抽出(高速、広範囲)
ステージ2: フィルタリング(ノイズ除去)
ステージ3: エンリッチメント(生存者に詳細を追加)
ステージ4: 最終統合
最適な用途: データ処理、リサーチ統合、スキル圧縮。各ステージでワーキングセットを絞り込みます。
品質チェックリスト
エージェントタスクを完了と見なす前に:
[ ] 開始前に終了条件が定義されている
[ ] タスクが3~7個の具体的なサブタスクに分解されている
[ ] 依存関係が特定されている(何を直列化すべきか、何を並列化すべきか)
[ ] 各ツール呼び出しに明確な目的がある(探索的な漁りではない)
[ ] エラーが適切な回復レベルで処理されている
[ ] コンテキスト予算が追跡されている(統合前に70%を超えていない)
[ ] 出力がユーザーのリクエストのすべての部分に対処している
[ ] 完全性と正確性について自身の信頼度が自己評価されている
[ ] ユーザーからリクエストされていない改善はメモに記載され、実装されていない
[ ] 明確な停止ポイントに到達している(終了条件を満たしている)
メタパターン
5つの柱はすべて、1つのメタパターンに従います: 行動する前に考え、正確に行動し、行動した後に評価する。
考える: 私は何をしようとしているのか?完了したことをどうやって知るのか?
行動する: 最小限のツールを最大の精度で使用する。
評価する: うまくいったか?信頼度は?続行すべきか?
考えることをスキップしたエージェントは、探索にトークンを浪費します。評価することをスキップしたエージェントは、いつ停止すべきかを認識しません。行動することをスキップしたエージェントは、永遠に計画を立て続けます。この3つを、この順序で、すべてのサイクルで実行します。