**AIエージェントのハーネス設計**（Harness Engineering）について、2026年現在の実務的なベストプラクティスをまとめます。

「ハーネス」とは、**モデル（LLM）以外のすべて**を指します。プロンプト体系、ツール制約、状態管理、ガードレール、Observability、評価機構、自己改善ループまで含めた「制御と運用基盤」の総称です。多くの現場で「モデルを賢くするより、ハーネスを強くした方が成果が出る」という認識が定着しています。

### 1. ハーネスのレイヤー分解（これが一番大事）

実装が迷子になる最大の原因は、すべてを1つのモジュールに詰め込むことです。以下の**3レイヤー**に明確に分離してください。

- **Execution Harness（実行基盤）**
状態機械、ツール呼び出し、Runtime（サンドボックス）。LangGraphのGraphがここに該当。

- **Context & Governance Harness（文脈・統制基盤）**
Memory（短期・長期・ベクトル）、Prompt管理、権限制御、Human-in-the-Loop、コストガードレール、安全ポリシー。

- **Evaluation & Improvement Harness（評価・改善基盤）**
自動評価（LLM-as-Judge）、Golden Dataset、回帰テスト、自己改善ループ（Harness of Harness）。これを独立させるのが最近のトレンド。

この分離を徹底すると、ハーネスが肥大化しても変更容易性が保てます。

### 2. 推奨アーキテクチャ（2026年現在）

**中核はLangGraph**（StateGraph）です。これ以外の選択肢（純粋なCrewAIや古いAutoGen）はデモ向きで、本番運用にはLangGraphベースの独自ハーネスを組む企業が多数です。

**基本構造のイメージ**：
- Supervisor（Planner） → Actor（Tool User） → Critic/Evaluator → 次のアクション決定
- すべてのステップで**明示的なState**を更新（immutableに近い形）
- すべての思考・ツールコール・判断をトレース可能にする（LangSmith最強）

**必須のState設計例**（これをしっかり設計すると後が楽）：
```python
class AgentState(TypedDict, total=False):
messages: Annotated[list[BaseMessage], add_messages]
next: str # "tool", "critic", "finish", "human"
findings: list[str] # 検証済みの事実
open_issues: list[str] # 未解決・回帰した問題（HoHで超重要）
plan: str
cost: float
steps: int
metadata: dict
```

### 3. 変更容易性を高める設計原則

ハーネスが肥大化すると死ぬので、以下の優先順位で設計してください（実務で有効な順）：

1. **責務の徹底分離**（Planner / Actor / Critic / MemoryManager / Evaluator）
2. **Stateの明示化**（何が入力で何が副作用かは常に明確に）
3. **設定の外部化**（AgentConfigをPydantic + YAMLで管理）
4. **Observability First**（何も考えなくても全思考が記録される）
5. **自己改善ループの組み込み**（後述）

その他実践パターン：
- リポジトリルートに `AGENTS.md` / `HARNESS.md` / `SKILLS.md` を置き、エージェント自身に定期更新させる（Ambient Agent）
- ツールは「何を許すか」より「何を禁止するか」を先に定義
- 危険操作は必ずinterrupt_beforeで人間承認

### 4. Evaluation Harnessの設計

エージェントハーネスと混同されやすい部分です。独立したモジュールとして設計してください。

- Golden Dataset + 複数回の実行で統計を取る
- LLM-as-Judgeは**構造化出力**（Pydantic）必須（スコア＋根拠＋改善提案）
- 回帰検知（前回より悪化したケースを自動アラート）
- Human Preferenceデータの蓄積ルートも用意

長期自律を目指すなら**Harness of Harness (HoH)** パターンが有効です（Planner → Developer → QA Testerの3層でメタ評価を行う）。1回の長いコンテキストに頼るより、「未解決issue」と「検証済み証拠」を明示的に持ち回す方が安定します。

### 5. 推奨技術スタック（2026年実務寄り）

- **Core**: LangGraph + LangChain / LiteLLM
- **Observability**: LangSmith（本命） + OpenTelemetry + Prometheus/Grafana
- **Evaluation**: DeepEval + 自作LLM Judge + RAGAS
- **Experiment管理**: Weights & Biases（Agent ConfigのA/Bテストに強い）
- **Sandbox**: E2B または制限付きDocker + restricted-python

### まとめ：最初にやるべきこと

1. Stateのスキーマを徹底的に設計する（これがハーネスの骨格）
2. LangGraphで最小動作するGraphを作る
3. 全思考をLangSmithに流す仕組みを最初に入れる
4. Evaluation Harnessを並行して作る（後回しにすると絶対に辛い）
5. `AGENTS.md`と自己更新ループを入れる

これで「PoCで終わるエージェント」から「運用可能なシステム」へと移行できます。

具体的に深掘りしたい部分があれば教えてください：
- 詳細なLangGraph実装例（Supervisor + 複数ツール + Reflection）
- Evaluationプロンプトのテンプレート集
- 自己改善ループ（Ambient Agent）の実装パターン
- 企業導入時のガバナンス設計
- リポジトリ構成例

必要に応じてコード例や資料構成も出せます。