**AIエージェント ハーネス設計**（2026年現在の実践的ガイド）

「ハーネス（Harness）」はもはや単なるテストフレームワークではなく、**AIエージェントを信頼性高く運用するための制御・観測・評価・矯正の全レイヤー**を指します。馬具（手綱と鞍）の意味そのもので、「Humans steer, Agents execute（人間が方向を決め、エージェントが実行する）」を実現する仕組みです。

日本コミュニティでは「**Harness Engineering（ハーネスエンジニアリング）**」という言葉が定着しており、デザイナー・QA・セキュリティ・テックリードの役割が「Agentを作る」から「Agentを制御するハーネスを作る」へとシフトしています。

### 1. 優れたハーネスの設計原則

以下の原則は2026年現在の実践から抽出されたものです：

- **変更容易性第一**：ハーネスは肥大化しやすい。Gotaさんの資料にあるように、**「どの部分を先に安定させるか」**の優先順位を明確に設計する。
- **判断の階層化（Jevパターン）**：重いLLM（複雑な推論・生成）は最小限に。危険判定、一次フィルタ、ツール結果検証などは高速な小型モデル・分類器（Jevのようなもの）に任せる。
- **Continuity（継続性）**：1回の会話で終わらせず、セッションを跨いだ状態・記憶・学習を維持。
- **Observability First**：すべての思考・行動・判断・分岐を構造化トレース。
- **Evaluation as Code**：成功基準を最初にコード（ルール＋LLM Judge）で定義する。
- **メタ設計の意識**：ハーネスが複雑になったら「**Agent HarnessのHarness**」を考え始める（複数のサブエージェントを統括する上位レイヤー）。

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

```mermaid
graph TD
A[Specification Layer
ゴール・制約・成功基準] --> B[Guardrail / Safety Layer
Jev + Permission + Sandbox]
B --> C[Orchestration Layer
LangGraph状態機 + Step Controller]
C --> D[Observation Layer
構造化Trace + Memory]
D --> E[Evaluation Layer
Rule + LLM Judge + Metrics]
E --> F[Escalation / Human-in-the-Loop]
F --> G[Experiment & Harness Evolution Layer]
```

**主要コンポーネントの設計ポイント**：

1. **Specification Layer**
- Pydanticモデルで宣言的に記述（Goal, Constraints, SuccessCriteria, AllowedTools, MaxCost, MaxSteps）。
- 成功基準は**verifiable**なもの（ファイル内容、API結果、数値指標）と**open-ended**（LLM Judge）を明確に分ける。

2. **Guardrail / Safety Layer**
- ツール呼び出し前後にJev（高速分類器）を挟む。
- 許可リスト方式のPermission System。
- Sandbox（E2B、専用コンテナ、仮想API）必須。

3. **Orchestration / Control Layer**
- LangGraphをベースに状態機械として実装。
- ループコントローラー（Think → Act → Verify → Reflect → Escalate）の明確な遷移ルール。
- 早期終了・再試行・計画修正のポリシーをここで集中管理。

4. **Observation & Memory Layer**
- OpenTelemetry互換の詳細トレース（LLM Call, Tool Call, Thought, Decision, State Change全部）。
- 長期記憶はベクトルDB＋要約＋重要な失敗パターンの構造化記憶。

5. **Evaluation Layer**
- **Outcome Evaluation**（最終結果）
- **Process Evaluation**（軌跡の質、不要な迂回、コスト効率）
- 自動Verifier（ルールベース）とLLM-as-Judgeのハイブリッド。
- 指標例：Success Rate, Cost Efficiency, Step Efficiency, Safety Violation Rate, Human Override Rate。

6. **Harness Evolution Layer**
- ハーネス自体のA/Bテスト。
- 過去の実行ログからハーネスの改善点を自動提案させるメタエージェント。

### 3. 実装時の実践Tips

- **すべて構造化**：LLMの出力は100% Pydanticでパース。パース失敗時は自動リトライ＋エスカレーション。
- **コストと速度の最適化**：Jev（小型モデル）を多用して frontier model の呼び出し回数を劇的に減らす。
- **Debuggability**：トレースを見れば「なぜこの判断をしたか」が一目で分かる状態を目指す。
- **ハーネスが肥大化したら**：GotaさんのSpeakerDeckで紹介されている優先順位付け（コア制御ロジック → 評価 → ガードレール → 実験機能）の考え方を参考にリファクタリング。

### 4. おすすめ参考資料（2026年現在）

- Gotaさん「無駄にハネスの設計」SpeakerDeck（変更容易性を高める優先順位が非常に参考になる）
- Neuromagic「Agent Harness Architecture」
- LayerX松本勇気さんのポスト（役割変化の考察）
- Oracle「Building an Agent Harness That Survives Production」
- 「An Empirical Study of Harness Design for Coding Agents」（計画機能のモデル依存性など実証研究）
- AnthropicのManaged Agents（サーバーサイドでLoopごと管理するアプローチ）

### さらに詳しく知りたい場合

- Coding Agent向けハーネス設計
- ビジネスプロセス（長時間実行）向けハーネス
- 具体的なLangGraph実装例
- Jev風軽量分類器の作り方
- 評価指標の設計テンプレート

どの部分を深掘りしたいか教えてください。実際の設計図やコードスケルトンも必要であれば作成します。