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

「AIエージェント ハーネス設計」は、現在**ハーネスエンジニアリング**と呼ばれる領域です。プロンプトエンジニアリングの次のレイヤーとして広く認識されており、「モデル単体ではなく、モデルを本番で信頼性高く動かすための土台（OSのようなもの）を設計する」考え方です。[[1]](https://x.com/bonnou7/status/2086932789421814212)

多くの実務家が使っている整理として、**Agent = Model + Harness** が非常にわかりやすいです。さらに深掘りすると、現在は以下の**3層モデル**で考えるのが主流です。

### 3層モデル（環境 → フィードバック → 流れ）

1. **ハーネス層（Harness Engineering）** — モデルが「動ける」環境を作る
2. **ループ層（Loop Engineering）** — 「繰り返し改善・検証できる」仕組みを作る
3. **グラフ層（Graph Engineering）** — 複雑な業務を「明示的に制御できる」構造にする

**診断の鉄則**：エージェントが期待通りに動かない場合、症状からどの層を直すべきかを特定する。
- そもそも動かない → **ハーネス**
- ほぼ動くが不安定・成功率がばらつく → **ループ**
- プロセスが複雑で管理不能 → **グラフ**

（この整理は2026年現在、日本コミュニティで特に強く議論されているフレームワークです。）

### 推奨アーキテクチャ（Production-grade Harness）

```mermaid
graph TD
subgraph Harness_Core [Harness Core - 環境]
Context[Context Manager\n(ポリシー・記憶・ADR)]
Tools[Tool Registry\n(権限 tier + Sandbox)]
Persistence[Persistence\n(Checkpoint + State + Artifacts)]
Control[Execution Control\n(Timeout/Budget/Retry/Gate)]
Safety[Safety & Governance\n(承認・最小権限・Filter)]
Observability[Observability\n(OpenTelemetry + Trace DB)]
end

subgraph Loop [Loop Controller - フィードバック]
LoopEngine[7要素ループ\n(Trigger, Goal, State, Policy, Evidence, Feedback, StopRule)]
Evaluator[Evaluator\n(LLM Judge + Rule-based + Human)]
end

subgraph Graph [Graph Orchestrator - 流れ]
StateMachine[State Machine\n(LangGraph or equivalent)]
HumanGate[Human-in-the-Loop Gates]
end

Experiment[Experiment Manager\n(Versioning / A/B / Replay)]
Dashboard[Dashboard & Analytics]

Experiment --> Harness_Core
Harness_Core <--> Loop
Loop <--> Graph
Harness_Core --> Observability --> Dashboard
```

### 1. ハーネス層の詳細設計（最も重要な基礎）

本番耐性のあるハーネスが最低限備えるべき**6大要素**：

- **コンテキスト注入**：システムプロンプト、会社ポリシー、ADR（Architectural Decision Record）、長期記憶、タスク固有ルール、RAG
- **アクション面（Tool Registry）**：ツールを「読み取り専用」「書き込み」「破壊的」「外部連携」に分類し、権限を強制。ツール定義は常に最新ドキュメント付き
- **永続化**：セッション状態のチェックポイント、git-like履歴、ファイル作業空間、中断からの復帰機能
- **実行制御**：最大ステップ数・トークン予算・タイムアウト・自動リトライ（指数バックオフ）・サブエージェント生成制御
- **安全性と統治**：最小権限原則、Sandbox（Docker/Firecracker/isolated browser）、危険アクション時のHuman Approval、シークレット管理、PII/有害コンテンツフィルタ
- **可観測性**：すべての思考・行動・観測・判断根拠を構造化ログ化（JSONL推奨）。コスト・レイテンシ・失敗モードも追跡

**設計のポイント**：ハーネスは「精密で混雑していない」状態を保つ。ツールをむやみに増やさない。

### 2. ループ層の設計（7要素）

良いループは以下の7要素で構成されます（円環構造）：

1. **Trigger**（何がサイクルを開始するか）
2. **Goal**（具体的な到達条件）
3. **State**（次のサイクルが知るべき情報）
4. **Action Policy**（何をしてよいか）
5. **Evidence**（成功をどう証明するか ← **最重要**）
6. **Feedback**（失敗時に何をどう返すか）
7. **Stop Rule**（いつ止めるか）

**最重要原則**：「エージェントが『完了した』と言った」では停止しない。**証拠**（テスト通過、スキーマ検証、差分承認、人間レビューなど）で停止する。

### 3. グラフ層の設計

- 明確な分岐・並列・人間ゲート・リトライ経路が必要になった段階で導入
- LangGraph（または同等の状態機械）が2026年現在も最も実用的
- 早すぎるグラフ化はシステムを硬直化させるので注意（まずはハーネス＋シンプルループでトレースを溜めてから）

### 実装技術スタック例（2026年推奨）

- **コアオーケストレーション**：LangGraph（最強クラス）
- **状態管理・永続化**：PostgreSQL + Redis + Vector DB（Qdrant/PGVector）
- **トレーシング**：OpenTelemetry + ClickHouse または LangSmith/Phoenix系
- **Sandbox**：Docker + Playwright（ブラウザ） + Firecracker（重いコード実行）
- **評価**：LLM-as-Judge + ルールベース + 人間フィードバックループ
- **フロント**：Streamlit / Next.js で実験管理ダッシュボード
- **モデルルーティング**：複数のプロバイダ（Claude, Grok, Gemini, ローカルvLLM）を状況に応じて切り替え

### 運用で特に重要なこと

- **Replay & Time Travel**：任意の過去状態から分岐して再実行できるようにする（デバッグ最強）
- **評価投資**：エージェント開発と同じくらい評価（Evals）に投資する（Kavakの事例ではほぼ同額）
- **バージョン管理**：ハーネス、プロンプト、評価基準、ツール定義すべてをバージョン管理
- **コスト・安全監視**：予算超過アラート、危険行動率、介入率を常に可視化

### 始め方（実践的アドバイス）

1. まずは**最小ハーネス**を作る（ツール2〜3個 + 状態永続化 + 基本トレース）
2. 実トレースを大量に集めて失敗パターンを分析
3. 失敗パターンが「不安定」ならループを強化
4. 業務が複雑化したらグラフを導入
5. 常に「この失敗はどの層の責任か？」と問う

この設計思想を取り入れると、同じモデルを使っていても**成果が劇的に変わります**。実際、1行も人間がコードを書かずに100万行規模のプロダクトを構築した事例や、ベンチマークで大幅ジャンプした事例が複数出ています。

具体的なユースケース（コーディングエージェント、調査エージェント、業務自動化エージェントなど）でさらに深掘りした設計図やコードスケルトンが必要でしたら、教えてください。