**AIエージェント ハーネス設計（ハーネスエンジニアリング）** — 2026年現在の実践的かつ先進的な設計ガイド

### 1. ハーネスとは何か

**ハーネス（Harness）**とは、AIエージェントに「良いプロンプトやコンテキストを与える」以上のこと、つまり**エージェントが働く環境全体を設計する**ことです。

- ツールの範囲
- 権限・承認フロー
- 検証・評価機構
- 停止・介入条件
- 監視・記憶・サンドボックス
- 失敗から学習してルールを進化させる仕組み

これらを**事前に設計し、運用しながら進化させる**考え方です。2026年現在、日本の実務コミュニティでは「ハーネスエンジニアリング」、海外研究では「Agent Harness」「Code as Harness」として急速に重要視されています。

**核心の思想**
- 良いプロンプトだけでは不十分。実行権限を持たせた瞬間に「環境」が挙動を支配する。
- モデルは薄く（Thin LLM）、ハーネスを厚く（Thick Harness）設計する。
- 完璧を目指さず、「失敗するたびにルールを1つ追記して環境を育てる」進化型設計。

### 2. 実践的最小ハーネス設計（最初に決める4要素）

多くの事故はこれを決めずに動かした結果起きています。最初に明確に定義してください。

| 要素 | 内容 | 具体例（マーケティングエージェントの場合） | 設計時のチェックポイント |
|----------------|----------------------------------------|----------------------------------------------------------|-------------------------|
| **ツールの範囲** | どのツール・APIを使わせるか | Google Analytics, Meta Ads API, Notion, Slack, Canva API | 「本当に必要か？」を厳選。危険ツールは別階層に |
| **権限の範囲** | 人間確認なしでどこまで実行可能か | レポート作成・分析OK、予算10万円未満の広告出稿は承認必須 | 3段階（Read / Low-risk Write / High-risk）で分ける |
| **検証の仕組み** | 結果を誰が・何でチェックするか | Supervisor Agent（LLM-as-Judge）＋人間最終確認＋自動ルールチェック | 自動評価基準を明確化（成功率、品質スコア、ブランド整合性） |
| **停止の条件** | どんな時に人間にエスカレーションするか | コスト閾値超過、確信度<70%、矛盾検知、時間超過、異常ツール呼び出し | 複数のシグナルをOR条件で監視 |

この4つを**ドキュメント化**し、エージェント起動前に必ず見返す運用にすると事故率が劇的に下がります。

### 3. 先進的アーキテクチャ設計（Production / Research Grade）

#### 全体像（Mermaid）

```mermaid
graph TD
subgraph "Thin LLM Layer"
LLM[LLM
Claude 4 / Grok 4 / o4 / Local]
end

subgraph "Thick Harness Core"
Orchestrator[Orchestration Core
State Machine + Loop]
Memory[Memory Systems
Working / Semantic / Episodic / Procedural]
Skills[Skills & Protocols]
Tools[Tool Registry + Permission Matrix]
end

subgraph "Mediator Layer（最も重要）"
Observer[Observability
OpenTelemetry + Trace Store]
Evaluator[Evaluator
LLM-as-Judge + Rule-based + Human]
Supervisor[Supervisor Agent
監視・介入・停止判断]
Sandbox[Sandbox & Approval Loop]
Evolution[Evolution Loop
失敗→ルール抽出→ハーネス更新]
end

LLM <--> Orchestrator
Orchestrator <--> Memory & Skills & Tools
Orchestrator --> Mediator
Mediator --> Evolution
Evolution --> Orchestrator
```

**主要設計ポイント**:

1. **Orchestration Core**
- 単一のState Machineで複数のパターン（ReAct, Plan-and-Execute, Reflection, Multi-Agent）を抽象化
- LangGraphのようなグラフベースが有力

2. **Mediator Layer（ここに知能を押し出す）**
- **Supervisor Agent**: 常時監視。メタ評価を行い、異常時は停止or修正指示
- **Evaluator**: 単一指標ではなく多軸評価（Task Success, Process Quality, Safety, Efficiency, Cost, Alignment）
- **Evolution Loop**: 各失敗トレースから「新しいルール」を抽出し、ハーネスに追加（これが2026年の最先端）

3. **Tool Design**
- すべてのツールに**Permission Level**と**Mock**を実装
- 危険操作は必ずHuman-in-the-LoopまたはSupervisor承認を挟む

### 4. 実践テンプレート例

**Permission Matrix例**

- Level 0 (Read): 検索、分析、データ取得
- Level 1 (Low-risk Write): ドラフト作成、内部ドキュメント更新
- Level 2 (High-risk): 外部公開、支払い、コード本番デプロイ → 必ず承認

**Supervisor Agentの基本プロンプトの方向性**
「あなたは厳格なハーネス監視者です。現在のトレースを多角的に評価し、停止条件に該当するか判断してください。判断根拠を必ず構造化して出力。」

### 5. 実装推奨技術（2026年現在）

- **フレームワーク基盤**: LangGraph または 自前State Machine（柔軟性を求めるなら自前が強い）
- **観測性**: OpenTelemetry + ClickHouse（トレース保存）
- **評価**: LLM-as-Judge + ルールエンジン + 人間フィードバックループ
- **サンドボックス**: E2B, Firecracker, または限定されたBrowserGym
- **記憶**: Vector + Graph + Procedural Memory（スキルとしてコード化）

### 6. ベストプラクティスと落とし穴

**やるべきこと**
- 最初は**小さく制限厳しく**始める（失敗を安く集める）
- すべての実行をトレース保存し、週次でハーネスを更新
- Supervisor Agentを最強モデル（Claude 4 Opusなど）で動かす
- 「ハーネス自体をエージェントで改善する」Meta-Harness的な発想を取り入れる

**危険な勘違い**
- 「プロンプトを頑張れば大丈夫」と思ってしまう
- 最初から権限を広げすぎる
- 検証を全部LLMに任せる（幻覚で事故る）
- ハーネスを一度作って放置する

---

この設計思想を取り入れると、エージェントは「賢いけど危ない子」から「信頼できる同僚」に変わります。

具体的なユースケース（営業エージェント、コーディングエージェント、個人タスクエージェントなど）でさらに深掘りした設計図や、実際のPermission Matrixテンプレート、Supervisorプロンプト例が必要でしたら、用途を教えてください。すぐにカスタマイズ版を作成します。