design-agentic-architecture

エージェント型アーキテクチャを設計する

エージェント型の複雑さは、最初から前提とするものではなく、削減していくコストです。このスキルでは、エビデンスに基づいて段階を上がることで、ユースケースを設計ドキュメントにします。必要に迫られたときにだけ構造を追加し、永続状態を基盤として、メモリ、human-in-the-loop、可観測性を、それぞれ導入する価値がある場合にのみ組み込みます。

アーキテクチャのルールは2026年半ば時点の研究に基づいており、PRINCIPLES.md に記載されています。設計時に参照してください。ツールはすぐに古くなるため、リアルタイムで（ステップ7で）確認します。記憶に頼って推奨しないでください。出力は DESIGN-DOC-TEMPLATE.md に従います。

各ステップを順番に進めてください。各ステップには完了条件があります。条件を満たすまで次に進まないでください。

1. ユースケースを明確にする

目標（1文）、エージェントが実行できるすべてのアクション（読み取りか、書き込み／取り消し不能か）、リスクプロファイル（取り消し可能性、影響範囲、コンプライアンス）、想定される規模、レイテンシ／コストへの感度、料金体系（従量課金のAPIか定額サブスクリプションか。これはコスト抑制の強さを決めるため、段階を上がる前にどれほど積極的に最適化するかを左右します）を把握します。目標が曖昧な場合は、設計を始める前にユーザーに聞き取りを行ってください。ユースケースが不明瞭だと、抽象的で役に立たない設計になります。

**完了条件：**目標を1文で述べられ、読み取りまたは書き込みのタグを付けてすべてのアクションを列挙し、リスクプロファイル、想定される規模、レイテンシ／コストへの感度、料金体系を把握していること。

2. エビデンスに基づいて段階を上がる

段階1（単一エージェント＋型付けされ、検証済みのツール）から始めます。満たされていないニーズがある場合にのみ段階を追加します。正確性にはリフレクション（独立した批評役）、構造には制約付きプランニング、適応性にはReAct、厳格な組織境界にはマルチエージェントを使います。ニーズを満たす最も低い段階を選んでください。段階を上がる前に、プロンプト、検索、キャッシュ、コンテキストエンジニアリング（キュレーション／圧縮／外部への退避）、モデルのアップグレードなど、単一エージェントの最適化を徹底してください。コンテキストウィンドウがあふれている、または劣化している場合は、段階を追加するのではなく、まずコンテキストを修正する必要があるという兆候です。マルチエージェントは最後の手段です（トークン消費が4～220倍になり、引き継ぎにレイテンシが発生し、デバッグが困難になります）。組織境界がある場合にのみ使用し、並列化だけを理由に使ってはいけません。マルチエージェントを使う場合は、単一ライターのルールを徹底します。コーディネーター1体が計画とすべての書き込みを担当し、サブエージェントはアクションではなく、分析結果と完全なトレースを返します。

**完了条件：**選択した段階と、それを正当化する具体的なニーズを明記していること（または段階1で十分な理由を示していること）。さらに、段階を上がる前に、コンテキストエンジニアリングを含む単一エージェントの最適化を徹底していること。

3. 永続状態の基盤を築く

まず、チェックポイント／永続実行の方式を決めます。これは、メモリ、HITL、長時間の実行、再生可能なトレースがすべて依存する共通基盤です。後から導入するのは困難です。通常、チェックポイントや引き継ぎを通して渡すのは、生のトランスクリプトではなく、コンテキストを圧縮したもの（要約、メモファイル、引き継ぎ用の概要）です。コンテキストを永続化することと、そのコンテキストを予算内に保つこと（ステップ4）は、同じ問題を両側から見たものです。

**完了条件：**実行状態をどのように永続化し、再開するかを設計に明記していること。

4. メモリを配置する

まずはコンテキスト内から始めます。ただし、ウィンドウは最適な使用量の範囲がある予算として扱います。大きなウィンドウや外部メモリを使う前に、情報をキュレーションし、圧縮（削除／要約）し、永続的な事実をメモリに退避します。トークンコストやウィンドウの制限が実際に問題になった場合にのみ、外部メモリを追加します。基本はRAG／ベクトル検索です。関係性や時間経過による変化が重要な場合にのみ、ナレッジグラフを使います。コンテキストを大きくすることはメモリ戦略ではありません（長いコンテキストを扱うモデルは、敵対的な想起タスクで劣化し、幻覚を起こします）。必要であれば書き込み経路に投資しますが、ベンダーのベンチマークは割り引いて評価してください。

**完了条件：**エージェントが必要とする知識の種類ごとに、理由を添えて保存先のレイヤー（コンテキスト内または外部）を割り当て、コンテキスト予算の計画（キュレーション／圧縮／外部への退避）を明記していること。

5. 人間が介入できるようにする

想定されるエラーコスト > レビューによる遅延コストとなるアクションにのみ、ゲートを設けます。各アクションを不可逆性、影響範囲、コンプライアンス、信頼度に基づいて評価します。ただし、モデルの生の信頼度だけを理由にエスカレーションしてはいけません（LLM は過信しがちです）。信頼度とリスクを組み合わせます。ゲートはチェーンの境界に少数設け、非同期にします。すべてのステップに設けると、形だけの承認が常態化するため、避けてください。監督は全体的なモードではなく、アクションごとに調整するダイヤル（ループ内／ループ上／ループ外）です。

**完了条件：**すべての書き込み／高リスクアクションに明示的なゲート判断があり、定型的なアクションはループ外で処理されること。

6. 中間を測定する

エージェント型システムは中間で失敗します。OpenTelemetry GenAI の規約に沿って計測し、最終回答だけでなく、ステップ単位で軌跡（ツール呼び出しの正確性、検索結果の根拠付け、引き継ぎの品質）を評価します。ループを閉じます（本番環境のトレース → 評価用データセット → CI）。マルチエージェントでは、MAST を使って失敗の原因を特定します。

**完了条件：**何をトレースし、何をステップ単位で評価するかに加え、エンドツーエンドの確認方法が設計書に記載されていること。

7. ツールをリアルタイムで推奨する

ツールは急速に古くなるため、機能ごとに（オーケストレーション、耐久性のある実行／HITL、メモリ、可観測性／評価）、Web 検索で最新の選択肢を調べます。記憶に頼ってツールを列挙してはいけません。ランキングではなく、全体像を提示します。調査では、検証済みの直接比較による勝者は見つかっておらず、フレームワークは同じプリミティブを提供しています。エビデンスに裏付けられた2つの基準（OpenTelemetry、MAST）を明示します。常に自作か購入かの選択肢（最適なツールを個別に組み合わせるか、連携したエコシステムを採用するか）を提示します。自作か購入かを判断するためのヒューリスティクスについては、PRINCIPLES.md を参照してください。

**完了条件：**各機能に少なくとも1つの最新ツールが記載され、各ツールについて検索実施日が示され、ランキングを行わない旨の注意書きがあること。

8. ドキュメントを作成し、誤った確信がないか確認する

DESIGN-DOC-TEMPLATE.md に記入して保存します（ユーザーがパスを指定しない限り、既定の保存先は ./agentic-architecture-design.md です）。**「2026年半ば時点のアーキテクチャに関するガイダンス。ツール検索日：。」**と明記します。その後、誤った確信がないか確認します。設計を PRINCIPLES.md に記載された3つの落とし穴――一見問題ないように見えながら失敗を隠しているもの――に照らして監査し、見つかったものは納品前に修正します。

**完了条件：**ドキュメントが指定パスに存在し、日付が記載され、3つの誤った確信につながる落とし穴が含まれていないことを確認していること。