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

2026年現在、「**Harness is the Product**」という認識が完全に主流になっています。モデルは交換可能で薄く（thin）、本当の知能・信頼性・差別化は**ハーネス（実行環境・制御層）**にあります。特にコーディングエージェントや業務エージェントでは、これが最も重要なレイヤーです。[[1]](https://x.com/Flextor97/status/2098738935270912350)

### 1. Agent Harnessとは何か

ハーネスとは、LLMを単なる「次のトークン予測機」から**自律的に長時間タスクを実行できるエージェント**に変える**実行ランタイム**です。主な役割は以下の4つです：

- **Loopの管理**：ReAct/Plan-and-Execute/Graphを繰り返し回す
- **Hands（手）の提供**：ツール・API・ファイルシステム・ブラウザなどを安全に提供
- **Memoryの管理**：長期記憶・作業記憶・エピソード記憶を適切に注入
- **Guardrails（制約）の強制**：許可リスト、人間承認ゲート、コスト制限、安全ポリシー

これをしっかり設計すると、モデルをほとんど変えなくても性能が劇的に向上します（論文では同一モデルで88%以上の相対改善例も報告されています）。[[2]](https://x.com/omarsar0/status/2058208914148389083)

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

**5層構造**で設計することをおすすめします：

#### Layer 1: Core Execution Loop（中核）
- **LangGraph**（State Machineとして厳密に定義）が現時点で最強
- 状態を明確なPydanticモデルで定義（`AgentState`）
- ノードは「Think」「Act」「Observe」「Evaluate」「HumanInLoop」など明確に分離

#### Layer 2: Tool Interface Layer（最も重要）
- すべてのツールに**厳格な契約**を定義（これがプロンプトより遥かに効く）
- Input/Output Schema（Pydantic）
- Pre-condition / Post-condition
- Permission Level（read / write / execute / external）
- Human Confirmationが必要か（`requires_approval=True`）
- **Allowlist**ベースで絶対にブラックリストは避ける

#### Layer 3: Memory & Knowledge Layer
- **Working Memory**：現在のタスクの構造化状態
- **Semantic Memory**：ベクトル + Graph RAG
- **Episodic Memory**：過去の成功/失敗トレース（スコア付き）
- **Procedural Memory**（Skills）：再利用可能なワークフロー（LangGraphのSubgraphとして保存）

#### Layer 4: Observability & Evaluation Layer
- **Behavioral Evals**を最優先（Googleが強く推奨）
- 「最終回答が正しいか」ではなく、「正しいツールを正しい順序で呼び出したか」をassert
- 回帰テストとして活用（プロンプト変更やモデル変更時の破壊を検知）
- 構造化トレース（LangSmith, Phoenix, OpenTelemetry）
- 評価は **Rule-based + LLM-as-Judge** のハイブリッド

#### Layer 5: Mediation & Safety Layer
- Sandbox（Docker, gVisor, Firecracker推奨）
- Cost Guardrail（トークン予算・時間制限）
- Approval Workflow
- Multi-agent Orchestration（必要時のみ）

### 3. 設計原則（これを守るだけで品質が段違い）

1. **Observability First** — 見えないものは改善できない
2. **Contracts over Prompts** — ツールの振る舞いはコードで定義（プロンプトに頼らない）
3. **Behavioral Testing > Outcome Testing** — 中間行動をテスト
4. **Minimalism** — ツールは少ない方が強い（コンテキスト汚染を防ぐ）。Bash + 最小限の専用ツールが意外と最強の場合が多い
5. **Model Agnostic** — OpenAI, Claude, DeepSeek, Llamaなどでスイッチ可能に
6. **Reproducibility** — 同じシード・同じトレースを完全に再現可能に
7. **Harness as Code** — 状態管理や検証ロジックはプロンプトではなくコードで書く
8. **Failure is Data** — すべての失敗トレースをエピソード記憶に蓄積して自己改善に使う

### 4. 実装の推奨パターン

**最も現実的な選択（2026年）**：
- **LangGraph + LangSmith**（ observabilityとstate managementが最強）
- Toolは**Pydantic AI Function Calling**を徹底
- 評価ハーネスは別リポジトリで管理（regression test suiteとして）

**ゼロからミニマルハーネスを作りたい場合**の基本スケルトン：
```python
class AgentState(BaseModel):
messages: list
working_memory: dict
next_action: str
approval_required: bool = False
trajectory: list[Trace] = []

class ToolContract(BaseModel):
name: str
schema: type[BaseModel]
pre_condition: Callable
post_condition: Callable
permission: PermissionLevel
requires_approval: bool
```

### 5. 特に注意すべきポイント

- **コーディングエージェント**の場合：ファイル状態のモデル化と「コードとしてのハーネス」（AST解析、自動lint、テスト実行の自動化）が鍵
- **業務エージェント**の場合：暗黙知をどれだけ形式知（契約・ワークフロー・承認フロー）としてハーネスに落とし込めるかが勝負
- セキュリティ：**Muse**のような厳格なレイヤードセキュリティ設計を参考に（隔離・最小権限・監査）

---

**さらに深掘りしたい方向性を教えてください：**

- コーディングエージェント特化のハーネス設計
- 業務プロセス（バックオフィス/コンサル）を対象にしたハーネス
- マルチエージェント・チーム編成の設計
- 具体的なLangGraph実装例
- Behavioral Evalの作り方
- ゼロからミニマルハーネスをスクラッチで作る場合の設計

用途（個人プロジェクト / 企業内業務 / プロダクト開発）を教えていただければ、それに最適化した設計テンプレートをお渡しします。