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

「AIエージェント ハーネス設計」とは、**Model（LLM本体）＋ Harness（周辺環境・制御機構）**という考え方の下で、信頼性・再現性・安全性を担保したエージェント実行環境を体系的に設計することです。[[1]](https://x.com/CobusGreylingZA/status/2043638576848707662)

単なるプロンプトやツール呼び出しではなく、「馬の手綱（harness）」のようにエージェントの能力を制御・増幅する全レイヤーを指します。OpenAIやAnthropicの実例では、同じモデルでもハーネスの質で成果が劇的に変わります（例: 無ハーネス vs 完全ハーネスで出力品質・完了率が別物）。[[2]](https://x.com/_vmlops/status/2057707195933110432)

### 1. ハーネスの核心原則（Agent = Model + Harness）

ハーネスが担う主な役割：
- **Instructions**：実行前に必ず読むシステムプロンプト・原則（会社基準、制約、思考様式）
- **Persistent State & Memory**：ゼロから始めないための状態管理
- **Verification Gates**：完了宣言前に「証明」を強制（自己評価＋ルールベース＋人間承認）
- **Scope Locking**：1機能/1タスクに厳格に限定（スコープクリープ防止）
- **Session Lifecycle**：クリーンスタート・クリーンエンドの明確なライフサイクル管理

これらを欠くと、エージェントは「コードを書いてDoneと言って壊す」状態になります。[[3]](https://x.com/i/status/2057707195933110432)

さらに先進的な外部化次元（2026年論文・議論で共通）：
- **Memory**：Working Context + Semantic + Episodic + Personalized
- **Skills**：運用手順、意思決定ヒューリスティック、規範的制約（プロシージャル知識）
- **Protocols**：Agent-Human、Agent-Agent、Agent-Toolの契約
- **Operational Mediators**：Sandbox、Observability、Compression、Evaluation、Approval Loops、Sub-agent Orchestration

モデルを中心ではなく、これらの「軌道」をハーネスが管理するアーキテクチャが主流です。[[4]](https://x.com/i/status/2043638576848707662)

### 2. 推奨アーキテクチャ：Graph-based Harness（LangGraph中心）

**Loop-only**（単純ReAct）はシンプルタスク向きだが、長期実行で暴走しやすい。
**Graph-based**（明示的な状態遷移）を推奨。LangGraph（または類似の状態機械）で実装するとデバッグ・再現性が段違いです。

#### 高レベル構成（テキストMermaid風）
```mermaid
graph TD
Start[Goal Input + Principles] --> Planner[Planner Node
Task Breakdown + Scope Lock]
Planner --> Context[Context Manager
Memory Retrieval + Compression]
Context --> LLM[LLM Reasoning Node
Tools + Skills]
LLM --> ToolExec[Tool Executor
Sandbox + Permission Check]
ToolExec --> Verifier[Verifier Node
LLM-as-Judge + Rule Check + Test]
Verifier --> Reflection[Reflection / Self-Correction]
Reflection -->|Not Good| Planner
Reflection -->|Approved| Orchestrator[Orchestrator
Sub-agent / Human Gate]
Orchestrator --> End[Session Close + Episodic Memory Save + Trace]

Observability[Observability Layer
LangSmith/LangFuse] -.-> AllNodes
Principles[Hardcoded Principles] -.-> Planner & LLM
```

**状態（State）の設計例**（Pydantic推奨）：
- `current_goal`, `scope_definition`, `working_memory`
- `episodic_trace_ids`, `verification_results`
- `approved_actions`（人間承認済みアクションのみ実行）
- `cost_so_far`, `iteration_count`（暴走防止）

### 3. 各レイヤーの詳細設計

**Context & Memory Layer**
- 階層管理：短期（プロンプト内）、中長期（Vector DB + Graph RAG）、エピソード（過去実行トレース）
- 圧縮機構必須（長い履歴を要約して注入）
- スキルは「コンテキスト管理層」に配置：発見型ロード、実行後結果のみ残す、未使用は退避

**Tool & Permission Layer**
- ツールレジストリ + 細かい権限（Read-only / Write / Destructiveに分類）
- Sandbox必須（コード実行ならDocker / E2B / 専用セキュア環境）
- コマンドガードレール（危険コマンド事前ブロック）

**Verification & Evaluation Layer**（最も重要）
- 多段ゲート：「LLM-as-Judge + 単体テスト/リント + 人間承認（クリティカル時）」
- 「Prove it before done」ルール（スクリーンショット、テスト結果、diff必須）
- 後検証（post-hook）でgeneratorとevaluatorを分離（GAN的アプローチ）

**Orchestration & Human-in-the-Loop**
- Supervisorパターンまたは階層型マルチエージェント
- 明確な停止許可（「これ以上進まない方が良い」と判断したら止まる権限を与える）
- 原則ベース開発（会社独自のエンジニアリング原則をハーネスにハードコード）

**Observability & LLM Ops（横断的）**
- 全実行をトレース（LangSmith / LangFuse / Helicone）
- コスト・レイテンシ・成功率・トークン使用量を自動計測
- Eval Engineering：自動評価パイプライン（50+の評価セット + LLM Judge）

### 4. 実装の推奨アプローチ

1. **最小ハーネスから構築**（理解を深めるため）
- Python + LangGraphで状態機械を実装
- 最初は単一タスク（例：GitHub Issue → PR生成）のハーネスを作る
- SWE-agent風のAgent-Computer Interface（ACI）を参考に

2. **プロダクション向け**
- LangGraph + LangSmithをベースにカスタムHarnessレイヤーを追加
- HarnessXのような「コンパイル可能なハーネス」（トレースから自己改善）を目指す
- セキュリティ・コスト制御・レート制限を最初から組み込む

3. **日本企業・開発チーム向けTips**
- 品質 vs 速度のトレードオフをセッション開始時にヒアリングシートで決定
- 確定事項はコード/ルールで固定、判断が必要な部分だけAIに委譲
- ピアノ楽譜解析などの非コードタスクでも「生成＋評価」の組み合わせが有効

### 5. 次のアクション（すぐに始められること）

- Anthropicの「Effective Harnesses for Long-Running Agents」やOpenAIのHarness Engineering関連資料を読む
- 小さなプロジェクトで「Verification Gates + Scope Locking + Persistent State」だけ実装してみる
- LangGraphチュートリアルで状態機械ベースのエージェントを1つ作る

ハーネス設計は「一度作ったら終わり」ではなく、**実行トレースから継続的に進化させる**もの（trace-driven improvement）です。これが2026年現在のAgenticシステムの競争力の源泉になっています。

具体的なユースケース（例：コード生成エージェント、業務自動化エージェント、研究エージェントなど）があれば、もっと詳細な状態定義・ノード設計・コード例をお出しします。どのような場面でのハーネス設計をお考えですか？