**AIエージェント ハーネス設計（2026年最新プラクティス）**

「AIエージェント ハーネス 設計」というクエリから、単なるツール呼び出しラッパーではなく、**本番で使える信頼性・再現性・評価可能性の高いAgent実行基盤（Harness）の設計**を求めていると解釈しました。

2026年現在、優れたハーネス設計の考え方は大きくシフトしています。従来の「LLMにツールをくっつける」ではなく、**「薄いモデル（Thin Model）を、賢いハーネスがランタイムで構成する」**という思想が主流です。

### 1. 核心原則：3 Layer Architecture

最も重要な設計原則は**明確な3層分離**です。これが曖昧だとほぼ確実にデバッグ不能・再利用不能になります。[[1]](https://x.com/rvaniaaaa/status/2087573102104318437)

- **Harness Layer（環境層）**：エージェントが動作する「OS」のようなもの
- Tools, Memory, Filesystem, Permissions, Sandbox, Protocols
- **エージェントが実行される前**に存在する
- ここをしっかり作ると「何に触れて良いか」が明確になる

- **Loop Layer（反復層）**：Think → Act → Observe → Evaluate → Reflectのフィードバックループ
- 1ターンごとの推論サイクルを司る
- ReflectionやSelf-critiqueの仕組みが入る

- **Graph Layer（編成層）**：ワークフロー全体の制御
- ノード・分岐・並列実行・階層構造（Supervisor-Worker）
- エラー回復経路や状態遷移を定義（LangGraphがここで非常に強い）

この3つを**意図的に分離して組み合わせる**のが2026年の正解です。

### 2. Harness Coreの構成（Thin Model, Fat Harness）

優れた設計の多くで共有されているフレームワーク（特にAkshayの整理が秀逸）です。[[2]](https://x.com/akshay_pachaar/status/2045510648474530263)

ハーネスの中心に**Core**を置き、そこに3つのモジュールが周回します：

- **Memory**（状態・知識）
- Working Context（現在進行中のタスク）
- Semantic Memory（ベクトル検索）
- Episodic Memory（過去の実行履歴）
- Personalized/Long-term Memory

- **Skills**（手続き的知能）
- Operational procedures、decision heuristics、playbooks
- 「この状況ではこうする」という暗黙知を外部化

- **Protocols**（契約）
- Agent ↔ User
- Agent ↔ Agent
- Agent ↔ Tools の各インターフェースと失敗モード定義

これらを繋ぐ**Mediators**：
- Sandboxing & Permission System
- Observability / Tracing
- Evaluation & Verification
- Approval / Human-in-the-loop Gates
- Sub-agent Orchestration
- Context Compression

新しい機能を追加するときに「これはMemoryに入れるべきか？Skillsか？Protocolか？Mediatorか？」と問う習慣が非常に有効です。

### 3. Evaluation Harness（特に重要）

Anthropicなどの先進事例では、**「テキスト出力の評価」から「エージェントの最終Outcomeの評価」**へ完全にシフトしています。[[3]](https://x.com/4rblaber/status/2080228516541472801)

推奨構成：
- Productionで実際に起きた失敗を自動的にTest Case化
- Regression Suite（既知の失敗を繰り返さない）
- Capability Suite（新しい能力の検証）
- 評価方法：Code-based Verifier + Calibrated LLM-as-Judgeのハイブリッド
- 検証項目：Invariants（不変条件）、Performance Metrics、Failure Modes

### 4. 推奨アーキテクチャ概要

```mermaid
graph TD
subgraph Harness_Core ["Harness Core (Environment)"]
Permissions[Authority Gate\n+ Permissions]
Sandbox[Sandbox Executor]
Memory[Memory Systems\n(4種類)]
Tools[Tool Registry\n+ Protocol]
Skills[Skill Library]
end

subgraph Agent_Loop ["Loop Layer"]
ReAct[Think → Act → Observe → Reflect]
Evaluation[Outcome Evaluator]
end

subgraph Orchestration ["Graph Layer"]
StateGraph[LangGraph / Custom State Machine]
Supervisor[Supervisor-Worker Pattern]
Recovery[Error Recovery Routes]
end

Config[Intent (AGENTS.md)\n+ Experiment Config] --> Harness_Core
Harness_Core <--> Agent_Loop
Agent_Loop <--> Orchestration

Observability[OpenTelemetry + Tracing] -.-> Harness_Core
Observability -.-> Agent_Loop
Observability -.-> Orchestration
```

### 5. 実装時の重要パターン

- **Intentの明文化**：各タスクに`AGENTS.md`的なドキュメントを強制（Scope, Invariants, Non-goals, Acceptance Criteria, Failure Modesを記述）
- **Repeated Tool Call対策**：即ブロックではなく、3回目・5回目・8回目で警告をエスカレーション（DeepSeekのハーネスで好評のパターン）
- **Smallest Complete Slice**：権限境界で最小の完全な実行単位だけを走らせる
- **Lifecycle Hooks**：pre-tool, post-tool, on-reflection, on-failure などハーネスが全ライフサイクルをフックできるようにする

### 技術スタック例（2026年時点おすすめ）

- **Orchestration**: LangGraph（最強クラス）
- **Config & Schema**: Pydantic v2 + Strict YAML
- **Observability**: OpenTelemetry + Phoenix / LangSmith相当
- **Sandbox**: gVisor or Firecracker（本気でやるなら）
- **Memory**: PGVector + Redis + File-based episodic memory
- **Evaluation**: Custom framework（LLM Judge + Code Executor）

---

この設計は「実験用のAgent」ではなく、「プロダクションで信頼できるAgent」を作るためのものです。

もっと深掘りしたい部分があれば教えてください：
- 特定のレイヤー（特にEvaluation HarnessやSandbox）の詳細設計
- コード例（LangGraphベースの最小ハーネス）
- System Designドキュメントのテンプレート
- 3層を実際に分離したリポジトリ構成例

必要に応じて、さらに具体的な設計資料を作成します。