**AIエージェントハーネス設計（Harness Engineering）**

「AIエージェント ハーネス 設計」は、2025〜2026年に急速に重要視されている概念です。プロンプトエンジニアリングやコンテキストエンジニアリングの次のレイヤーとして位置づけられ、「モデルはCPU、ハーネスはOS」という比喩がよく使われます。[[1]](https://x.com/tetumemo/status/2037876018745385083)

ハーネス（Harness）とは、馬具の手綱のように**エージェントの強大な能力を人間が制御・誘導し、信頼性・効率性・安全性を確保するための「足場・環境・仕組み全体」**を指します。人間はゴール・制約・品質基準を設定し、エージェントに実行させる「Humans steer, agents execute」の世界を実現します。[[2]](https://x.com/taimuhanashiro/status/2023008135464788127)

### なぜ今、ハーネス設計が重要か
- **経済効果が非常に大きい**：同じモデル・同じタスクでも、ハーネス（オーケストレーション設計）を変えるだけでトークン使用量・コストを40%前後削減できるという報告が複数出ています（「The Harness Effect」）。[[3]](https://x.com/_stakaya/status/2078829410866888952)[[4]](https://x.com/vericence/status/2079555479005446278)
- OpenAI社内事例では、Codexエージェントだけで約100万行のコード（1,500 PR）を5ヶ月で生成した事例が共有され、ハーネス設計の重要性が強調されました。[[2]](https://x.com/taimuhanashiro/status/2023008135464788127)
- ハーネスが肥大化すると変更容易性が急落するため、**メンテナビリティを意識した設計優先順位**が求められます。[[5]](https://x.com/gota_bara/status/2046794926604931447)

### 推奨アーキテクチャ（2026年時点のベストプラクティス）

#### 1. 全体レイヤー構成
```
[Human / Application Layer]
↓ (Goal, Constraints, Quality Gate)
[Harness Orchestration Core] ←→ [Observability & Eval Layer]
├── State & Memory Manager (Smart Compression + Cache)
├── LLM Router (model-agnostic, LiteLLMなど)
├── Tool & Action Executor (Sandbox + Permission + Schema)
├── Guardrails & Safety Gates (Pre/Post + Human-in-the-Loop)
└── Reflection / Feedback Loop Engine
↓
[Persistence Layer] (Postgres + Redis + Vector DB)
```

#### 2. 主要コンポーネント詳細設計

**A. Orchestration Core（心臓部）**
- LangGraph（または類似のグラフ型状態機械）を強く推奨。ノード（LLM Call, Tool Call, Router, Summarizer, Judge）とエッジで制御フローを明示的に定義。
- 状態は厳密に型付け（Pydantic + TypedDict）。`messages`, `summary`, `artifacts`, `next_action`, `cost_so_far` などを保持。
- **チェックポイント機能**必須：任意の時点で状態を永続化し、time-travel debugging（過去の分岐から再実行）を実現。

**B. Memory & Context Management（最大のコスト削減ポイント）**
- 毎ターン全履歴を再送するのは最悪のアンチパターン。
- **推奨テクニック**：
- 不変部分（システムプロンプト、ツール定義、確定済み事実）を先頭に固定し、キャッシュヒット率を99%以上にする。
- Contextが閾値（例: 8割）を超えたら、古い部分を「決定事項・作業要約・未解決質問」に構造化圧縮。
- 大きなツール出力・ファイル・子エージェント結果は本文をコンテキストに入れず、**ポインタ（参照）だけ残す**。
- 長期記憶はVector DB + Entity Memoryで管理。

**C. Tool & Action System**
- すべてのツールに厳格なJSON Schema（Pydantic）定義。
- Sandbox実行（特にコードインタープリタ）。
- 権限モデル（read-onlyツール、writeツール、human-approvalが必要な高リスクアクション）。
- 並列実行上限・タイムアウト・リトライポリシーをハーネス側で一元管理。

**D. Guardrails & Safety**
- Pre-call：入力フィルタリング（Llama-Guard系 or LLM-as-Judge）。
- Post-call：出力検証、PII検出、有害性チェック。
- 重要なアクションは必ずHuman-in-the-Loop中断。
- 失敗モードごとに明確な境界を設定（無限ループ防止、同一失敗10回でエスカレーションなど）。

**E. Observability & Evaluation Harness**
- トレーシング必須（LangSmith / Phoenix / OpenTelemetry）。
- メトリクス：トークンコスト（コンポーネント別）、成功率、ステップ数、Safety Violation率、Latency。
- 評価スイートを内包：固定ベンチマーク（WebArena, GAIA類似）＋ LLM-as-Judge＋人間評価の組み合わせ。
- ハーネスの質を「同じモデルでどれだけコスト・品質を改善できるか」で測る。

### 設計時の優先順位（ハーネスが肥大化した時の指針）
（@gota_bara氏の資料を参考にした優先思想）[[5]](https://x.com/gota_bara/status/2046794926604931447)

1. **境界の明確化**：各サブエージェント・ツールの責任範囲を小さく保つ。
2. **不変部分の抽出**：システムプロンプト・ツール定義・共通ロジックをハーネス本体に持ち、個別エージェントは最小限に。
3. **状態圧縮戦略の中央集権化**：要約ロジックを1箇所に。
4. **失敗処理の標準化**：リトライ・フォールバック・エスカレーションをハーネス共通機能に。
5. **構成駆動**：エージェントの性格・ツールセット・ガードレールはYAML/JSONで定義し、コード変更を最小化。

### おすすめ技術スタック（2026年現在）
- **Core**：LangGraph + Pydantic + asyncio
- **LLM抽象化**：LiteLLM（モデル切り替え容易）
- **Memory**：PGVector or Qdrant + Redisキャッシュ
- **Observability**：LangSmith + Prometheus + Grafana
- **Safety**：NVIDIA NeMo Guardrails or Llama-Guard + Outlines（構造化出力）
- **Persistence**：PostgreSQL（checkpointer）+ Redis
- **評価**：LangChain Eval + カスタムLLM Judge

### 実装のポイント
- ハーネスを「モデル非依存」に設計（どのモデルでも同じ実行経路を通す）。
- 待機状態（人間承認待ち、長時間ジョブ）は**イベント駆動**にし、ポーリングでトークンを無駄遣いしない。
- 最初からコスト計測を組み込み、「このハーネス変更でトークン何%減ったか」を可視化。

ハーネス設計はまだ発展途上ですが、「モデル性能を上げる」のではなく「ハーネスを磨く」方がROIが高い時代になっています。

具体的に：
- コーディングエージェント向けハーネス
- 社内業務自動化向けハーネス
- マルチエージェント swarm 向け設計

など、**用途を教えていただければ、より詳細な設計図・コードスケルトン・構成YAML例**を提供できます。

必要であれば、SpeakerDeckで公開されている資料のポイント解説や、LangGraphを使った具体的な状態定義例も展開します。どのような粒度・方向性で深掘りしますか？