**AIエージェント ハーネス設計**（2026年現在のベストプラクティス）

「モデルはエンジン、ハーネスは車である」というのが現在のコンセンサスです。LLM自体をどれだけ賢くしても、**ハーネス（実行基盤・足回り）**の質がエージェントの性能・信頼性・安全性をほぼ決定します。

### 1. ハーネスの本質的な役割

現代的なハーネスは、**知能をモデルから外部化（externalize）する仕組み**です。

中心に薄いLLM + シンプルな実行ループを置き、その周りを以下の3次元が周回するアーキテクチャが主流です：

- **Memory（記憶）**：Working Context / Semantic Knowledge / Episodic Memory / Personalized Memoryの4層
- **Skills（技能）**：運用手順、意思決定ヒューリスティック、規範的制約（normative constraints）
- **Protocols（プロトコル）**：Agent↔User、Agent↔Agent、Agent↔Toolの契約面

これらを仲介するのが**Mediator Layer**です：
- Sandboxing
- Observability / Tracing
- Context Compression
- Evaluation / Scoring
- Approval Loops（Human-in-the-Loop）
- Sub-agent Orchestration

この「外部化して仲介する」考え方が、2026年現在の最も重要な設計思想です。[[1]](https://x.com/CobusGreylingZA/status/2043638576848707662)

### 2. 設計のスペクトラム（Thin vs Thick）

| タイプ | 代表例 | 思想 | メリット | デメリット |
|--------------|----------------|-----------------------------------|------------------------------|--------------------------------|
| **Thin** | Anthropic系 | モデルにできるだけ任せる | モデル更新時に足回りが軽い | 現時点では不安定になりやすい |
| **Thick** | LangGraph, CrewAI | ロジックをコード/グラフで明示的に制御 | 制御性・再現性が高い | モデルが進化すると足枷になる可能性 |
| **Minimal** | 多くの人が現在自作中 | 「退屈で小さなループ」を目指す | 保守性が高く、将来的に強い | 最初に作るのが意外と難しい |

重要な原則：「**Scaffolding（足場）は一時的なものであり、取り外せるように設計する**」。ただし、モデルが特定のハーネスで訓練されている場合、急に大きく変えると性能が落ちるので注意が必要です。[[2]](https://x.com/akshay_pachaar/status/2042586319390674994)

### 3. 実践的な設計原則（強く推奨）

1. **Append-only Session Record**
履歴を絶対にインラインで書き換えない。壊れたツール呼び出しを後から修正して履歴を改変すると、再現性とデバッグが死ぬ。

2. **Progressive Disclosure**
システムプロンプトに全ツール・全スキル説明を詰め込まない。名前＋短い説明＋必要時に「詳細を要求する」仕組みにする。

3. **Commoditized Loop**
実行ループは小さく、退屈で、誰が書いても似たものになるようにする。独自の複雑ループを作らない。

4. **Model Quirks as Data**
各モデルのトークン制限、呼び出し形式の癖、JSONモードの信頼性などはハードコードせず、設定データとして持つ。

5. **将来の必須要件**
Tamper-evident Execution Trace（改ざん不可能な実行証跡）。外部者が検証可能なログ構造を目指す。

### 4. 推奨アーキテクチャ構成（実装イメージ）

**コアコンポーネント**

- **Executor / State Machine**：`Thinking → Planning → Tool Selection → Execution → Observation → Evaluation` の状態遷移を明示的に管理（LangGraph風グラフでもシンプルwhileループでも可）
- **Memory Hierarchy Manager**：短期（会話履歴）、中長期（Vector + Graph）、エピソード記憶、ユーザー個人記憶を適切にロード/圧縮/退避
- **Skill & Tool Registry**：ツールは遅延ロード（lazy loading）＋ Intent Router（どのスキルセットをこのターンで使うかを動的に決定）
- **Protocol Enforcer**：各インターフェースごとに契約を強制（出力スキーマ、権限チェック、フォーマット検証）
- **Mediator Services**（横断的）：
- Guardrails（入出力フィルタリング）
- Sandbox / Executor（Code Interpreter、Browserなど）
- Observer（OpenTelemetry + 完全Trajectoryログ）
- HITL（Human Approval）Hooks
- Evaluator（LLM-as-Judge + ルールベース）

**永続化層**
- すべてのRunをAppend-only JSONL + メタデータとして保存
- Checkpoint機能で途中再開可能
- 将来的にはMerkle Treeなどでログの完全性を保証

### 5. 実装時のTips（日本向け）

- **最初はミニマルハーネスから作る**ことを強く推奨。Bash + シンプルPythonループから始め、徐々に厚くしていくと理解が深まる。
- すべての状態・イベントはPydantic v2で厳密に型付け。
- ログは人間が読めて、LLMが再消費でき、第三者が検証可能な形式にする。
- 日本語業務では「暗黙知の形式知化」が特に重要。Skills層に業務手順をしっかり落とし込む。

日本語の良質な資料として、**「ハーネス設計入門〜コンテキストの次〜」**というSpeakerDeckが非常に参考になります（コンテキスト管理の先の話が整理されています）。[[3]](https://x.com/SkillupAi/status/2099830608449175607)

---

この設計思想で作られたハーネスは、モデルが変わっても比較的長持ちしやすく、企業実装にも耐えられます。

具体的に深掘りしたい部分があれば教えてください：
- 状態遷移マシンの詳細設計
- Memory Hierarchyの実装パターン
- Tool Router / Intent Routerの設計
- 安全・監査向けのGuardrails + Tamper-evident Log
- ミニマルハーネスのサンプルコード構成
- 評価（Evaluation）レイヤーの設計

必要に応じて、図やコードスケルトンも用意できます。