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

2026年現在、「モデルがエージェントではない。**ハーネスこそがエージェントの本体**」という認識が業界の主流になっています。LLMを「薄い推論エンジン」と位置づけ、知能の大部分をハーネス側（外部化）に押し出すアーキテクチャが標準化されつつあります。[[1]](https://x.com/CobusGreylingZA/status/2043638576848707662)

### 1. ハーネス設計の基本原則

- **外部化（Externalization）**：記憶・スキル・プロトコル・運用ロジックをモデル外に明確に分離
- **Thin Model + Thick Harness**：モデルは最小限のコンテキストで推論。ハーネスがランタイムで適切な記憶・スキル・制約を合成
- **Loop First**：制御ループ（Task → Plan → Act → Observe → Evaluate → Adapt）が最も重要
- **Observability & Governability First**：何が起きているか常に可視化でき、いつでも停止・承認・修正可能にする
- **Vision-Driven**：何のためにこのエージェントを動かすのか（ビジョン・成功定義）を最初に固める

### 2. 推奨全体アーキテクチャ

```mermaid
graph TD
subgraph "User / Task Input"
Task[タスク + ビジョン]
end

subgraph "Core Harness (Orchestrator)"
Loop[Control Loop
ReAct / Plan-and-Execute / Reflection]
State[Persistent State
Checkpointing]
end

subgraph "Externalized Intelligence"
Memory[Memory Layer]
Skills[Skills Layer]
Protocols[Protocols Layer]
end

subgraph "Mediators / Operational Layer"
Mediator[Mediator Services]
Sandbox[Sandbox & Permission Budget]
Guard[Guardrails & Eval Loop
LLM-as-Judge]
Observability[Observability & Tracing]
end

subgraph "Foundation"
LLM[Thin LLM
LiteLLM abstraction]
Tools[Tool Registry & Executor]
end

Task --> Loop
Loop <--> State
Loop <--> Memory
Loop <--> Skills
Loop <--> Protocols
Loop <--> Mediator
Mediator <--> Sandbox
Mediator <--> Guard
Mediator <--> Observability
Loop <--> LLM
LLM <--> Tools
Tools <--> ExternalAPI[外部API / Browser / Code Exec]

classDef harness fill:#e0f2fe,stroke:#0284c8
class Loop,State,Mediator,Memory,Skills,Protocols harness
```

### 3. 各レイヤーの詳細設計

**Memory Layer（4種類を明確に分離）**
- **Working Context**：現在のタスクの短期状態（LangGraphのState / checkpoint）
- **Semantic Memory**：ベクトルDB（PGVector / Qdrant）に長期知識
- **Episodic Memory**：過去の成功・失敗事例（構造化ログ + 要約）
- **Personalized Memory**：ユーザーごとの好み・履歴・権限

**Skills Layer**
- Operational Procedures（SOPs）
- Decision Heuristics（「この状況ではこう判断せよ」）
- Normative Constraints（「絶対にしてはいけないこと」）
→ スキルはYAMLやJSON Schemaで宣言的に管理し、ハーネスが動的にロード

**Protocols Layer**
- Agent-to-User（承認フロー、説明責任）
- Agent-to-Agent（メッセージング規約）
- Agent-to-Tools（ツール呼び出しの契約、入力検証、出力スキーマ）

**Mediator / Operational Layer（最も重要）**
- Sandbox & Permission Budget（実行前に権限チェック）
- Evaluation Loop（LLM-as-Judge + Rubricで各ステップを採点）
- Approval Loops（Human-in-the-Loopの自動挿入ルール）
- Observability（Phoenix / LangSmith / OpenTelemetry）
- Compression（コンテキスト圧縮、要約エージェント）

### 4. 推奨技術スタック（2026年実践的構成）

- **Orchestration**: **LangGraph**（状態永続化・checkpointingが最強。カスタムループも作りやすい）
- **LLM Abstraction**: LiteLLM（モデルスイッチング容易）
- **Memory**: PGVector（PostgreSQL）+ Redis（ワーキングメモリ）
- **Observability**: Arize Phoenix + LangSmith（トレースが命）
- **Guardrails**: Outlines / Guidance / 自前Rubric + LLM Judge
- **Tool Execution**: Docker sandbox or Firecracker（極力分離）
- **Frontend/Coordination**: Next.js + TypeScript（管理画面必須）

ミニマリスト派の人は「LangGraphをベースに自前で薄いハーネス」を作る動きも活発です。

### 5. 安全・統治可能性設計（特に日本企業向け）

- 必ず「Permission Budget」概念を入れる（1タスクあたりの最大コスト・権限・実行回数）
- 重要なアクションは必ずHuman Approvalゲートを挟むルール化
- 全ての決定に「Evidence + Reasoning」をログとして残す（後から監査可能）
- 失敗時は自動で「学習ノート」をEpisodic Memoryに書き込む
- ビジョン（このエージェントは何を目指すのか）をシステムプロンプトの最上位に固定

### 6. 構築・改善の運用方法

多くの日本企業・個人開発者が実践している効果的な方法：

1. **Claude Code（またはCursor）**で全体設計とリファクタリングを主導させる
2. **Codex / Sonnet**で個別コンポーネントの実装を担当させる
3. 実装後にClaudeで致命的欠陥レビュー → 必要なら全面リファクタリング
4. 実際に動かして失敗したら、その失敗を**ハーネスに学習させる**（これが最も重要）

最初から完璧を目指さず、「制約を1つずつ追加しながら強化学習させる」アプローチが現実的です。

### 欲しいもの教えてください

- この設計を基にした**詳細設計書**（Markdown / Notion形式）
- LangGraphを使った**具体的なコードスケルトン**
- 評価ハーネス（benchmark）寄りの設計
- 特定ドメイン（営業、開発、バックオフィスなど）に特化したハーネス設計
- 「最小で動くMVPハーネス」の設計

用途や制約条件（予算、チームスキル、対象タスクの危険度など）を教えていただければ、より精密な設計に調整します。

この分野は2025〜2026年に大きく思想が変わった領域です。**「モデルを賢くする」のではなく「ハーネスを賢く設計する」**時代の本質を押さえることが最も重要です。