11月16日、KDnuggetsが「Agentic System Design: A Self-Study Roadmap」と題した記事を公開した。LLMにツールと目標を与えて自律動作させる「エージェント」開発への関心が高まる一方、実際に本番環境で安定稼働させるための設計知識は体系化されていないことが多い。その核心にある問いが「どこまでモデルに判断を委ねるか」だ。制御をコードに持たせる「ワークフロー」とモデルに委ねる「エージェント」の選択を誤ると、コスト・レイテンシ・信頼性のすべてに響く。本記事はその設計判断を含む自己学習ロードマップを7ステップの実践プロジェクトで体系的に解説している。
7ステップで「インシデント調査エージェント」を作る
ロードマップの核心は1つのプロジェクトを7段階で構築していく点にある。題材は「本番アラートの根本原因を特定するインシデント調査エージェント」だ。ログ、メトリクス、デプロイ履歴、ランブックを収集し、証拠付きの根本原因レポートと修正案を返す。アクション実行には人間の承認が必要という設計になっている。
各ステップで追加するコンポーネントは以下の通りだ:
| ステップ | プロジェクトへの追加内容 |
|---|---|
| Shape(形状決定) | 合成インシデント10件と固定トリアージパイプライン |
| Loop(ループ構築) | ツール呼び出しループ |
| Tools(ツール設計) | MCPサーバー上の6ツール |
| Memory(記憶) | スクラッチパッド・出力圧縮・過去インシデント履歴 |
| Team(チーム化) | オーケストレーターと3並列ワーカー |
| Evals(評価) | 30インシデントのリプレイスイート |
| Deployment(本番化) | バジェット・読み取り専用アクセス・承認ゲート・トレーシング |
フレームワークはLangGraph、CrewAI、Google ADKなど何でも使えるが、Step 2ではあえてループを手書きする。フレームワークが自動化している「メッセージリスト、ツールレジストリ、ディスパッチャー、停止条件」の仕組みを理解するためだ。
一番の要点:「ワークフロー」か「エージェント」かの選択
記事が最初に強調するのが制御の所在をどこに置くかという設計判断だ。コードがステップ順序を固定するのが「ワークフロー」、モデルが次のアクションを自分で選ぶのが「エージェント」である。自律度が上がるほどコスト・レイテンシ・変動性が増す。
| 形状 | 仕組み | 向くタスク |
|---|---|---|
| 単一プロンプト | 1回のモデル呼び出し | 入出力が1対1 |
| プロンプトチェーン | 固定順序の複数呼び出し | 安定したステップに分割可能 |
| ルーティング | 分類器がハンドラーへ振り分け | カテゴリが明確 |
| 並列化 | 独立した呼び出しを同時実行 | 独立したサブタスクを含む |
| オーケストレーター-ワーカー | リードモデルが実行時に分担 | 作業中にサブタスクが出現 |
| エバリュエーター-オプティマイザー | 生成と批評を繰り返す | 品質基準が明確で反復改善が効く |
| エージェント | ループでツールを選択 | 各ステップの結果次第でパスが変わる |
設計の基本作業はタスクを人が従う番号付きステップとして書き、「固定」か「オープンエンド」かをマーキングすることだ。固定ステップはコードに、オープンエンドなステップはモデルに渡す。
ツール設計とメモリ管理のポイント
ツールはコントラクト(契約)として設計する。説明文の曖昧さがエージェントの品質問題の大半を引き起こすため、各ツールの説明には「何をするか、いつ使うか、何を返すか」を明記する。各ツールは1つの目的だけを持たせ、ドメインでネームスペースを切る(例: logs_search、metrics_query)。ツール定義の検証方法として、スキーマだけをモデルに渡して呼び出しを確認するというテスト手法が紹介されている。
ツール間の標準化にはMCP(Model Context Protocol)の採用が推奨されており、1つのツールサーバーを複数エージェントで共有できる構成を実現する。
メモリは3層に分けて考える:
- ワーキングメモリ:現在のコンテキストウィンドウ(トリミング・要約で管理)
- セッションメモリ:現タスクの計画・所見(スクラッチパッドファイル)
- 長期メモリ:過去ランをまたぐ知識(キーワード・埋め込み検索付きDB)
プロジェクトでは過去の解決済みインシデント(症状・根本原因・修正)をSQLiteに保存し、各ランの開始時に類似の過去3件を取得する設計が示されている。
ループの落とし穴4種
手書きループを実装すると必ず踏む失敗パターンが明示されている点は実用的だ:
| 失敗モード | 症状 | 最初の対処 |
|---|---|---|
| 不正な引数 | スキーマバリデーション失敗 | スキーマを厳密化してモデルが対処できるエラーを返す |
| 同一呼び出しの繰り返し | 1つのツールをループ | 呼び出し履歴をコンテキストに保持して上限を設ける |
| 早期終了 | 証拠収集前に回答 | 回答にツール結果の引用を必須とする |
| 暴走ループ | 有効期限を超えて継続 | ステップ上限と時間バジェットを設定 |
評価(Step 6):経路ごとスコアリングする
エージェントの評価は単一モデルの評価より根本的に難しい。正解が一通りでなく、最終出力だけでなく途中のツール呼び出し経路も判定対象になるためだ。記事では評価指標として「根本原因の正確さ」「証拠の引用率」「ツール呼び出し回数の妥当性」などを挙げており、自動グレーダー(LLMによるスコアリング)と人間レビューの組み合わせが推奨されている。
プロジェクトでは30インシデントのリプレイスイートを構築する。リプレイスイートとは過去の実インシデントをそのまま再現し、エージェントの応答を記録・比較するテスト群だ。コードを変更するたびにこのスイートを回すことで、リグレッションを検出できる。また、単体テストとしてツール1本ずつのモック呼び出しテストも推奨されており、ループ全体の統合テストと組み合わせて使う設計が示されている。
本番化(Step 7):4つの安全装置
Step 7では、開発環境で動いたエージェントを本番に持ち込む際に必要な設計上の安全装置が4点にまとめられている。
- 読み取り専用アクセスの徹底:エージェントが扱うツールのデフォルト権限を読み取り専用とし、書き込みアクションには明示的な昇格を要求する
- トークンバジェット管理:1インシデントあたりの最大トークン数を設定し、暴走した場合に強制終了させる
- 承認ゲートの設置:修正案の実行など副作用を伴うアクションは、人間の確認ステップを挟む。記事はこれを「human-in-the-loop」と呼ぶ
- トレーシングの組み込み:各ツール呼び出し・モデル応答・判断分岐をログに記録し、障害時に再現・デバッグできる状態を保つ
これら4点は独立した後付け機能ではなく、Step 1の設計段階から組み込む前提で構造を決めることが強調されている点が重要だ。本番化を後回しにすると、承認ゲートの挿入のためにループ構造を大幅に書き直す羽目になる。
詳細はAgentic System Design: A Self-Study Roadmapを参照していただきたい。




