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

### 1. AIエージェントハーネスとは

**AI Agent Harness**とは、LLMを核とした自律エージェントを**信頼性高く・観測可能に・安全に・長時間実行**するための実行基盤（Runtime Framework）です。

単なる「LangChainのAgentExecutor」ではなく、以下の要件を満たす生産レベルのレイヤーです：

- 中断・復旧が可能（Checkpointing / Time Travel）
- 全ての思考・行動を構造化ログ・トレース
- ツール実行のきめ細かい権限管理とサンドボックス
- 評価（Evaluation）と最適化ループの組み込み
- Multi-Agent / Hierarchical / Human-in-the-Loopのネイティブサポート

### 2. 非機能要求（NFR）

| 項目 | 要求内容 | 重要度 |
|-------------------|---------------------------------------|--------|
| 信頼性 | 任意の時点から復旧可能、Exactly-Once風実行 | ★★★★★ |
| 観測可能性 | OpenTelemetryネイティブ、トレース全取得 | ★★★★★ |
| セキュリティ | ツールごとの権限・承認フロー、サンドボックス | ★★★★★ |
| コスト制御 | ステップ上限・予算上限・自動停止 | ★★★★☆ |
| 評価可能性 | Trajectory評価・LLM-as-Judge内蔵 | ★★★★★ |
| スケーラビリティ | 同時数十〜数百エージェント実行 | ★★★★☆ |

### 3. 全体アーキテクチャ（Layered Architecture）

```
[User / Application Layer]
↓
[Orchestration & Graph Layer] ← LangGraph (推奨) or Custom State Machine
↓
[Core Runtime]
├── Agent Node (LLM + Structured Output)
├── Tool Executor (権限チェック → Sandbox)
├── Memory & Knowledge Manager
├── Guardrails & Safety Layer
├── Evaluator Node
↓
[Persistence Layer] (Postgres + Checkpointer + Redis)
↓
[Execution Sandbox Layer]
├── Code Interpreter (E2B / Secure Docker / Modal)
├── Browser (Playwright + remote isolation)
├── Filesystem / API Gateway (権限分離)
↓
[Observability & Evaluation Platform]
├── LangSmith / Phoenix / Helicone / OpenTelemetry
├── Built-in Evaluation Harness
```

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

#### 4.1 State Model（最も重要）
```python
class AgentState(TypedDict):
messages: Annotated[list[BaseMessage], add_messages]
next: str | None # graph routing用
goal: str
plan: list[str] | None
tool_results: dict[str, Any]
metadata: dict[str, Any] # cost, steps, confidence, error_count...
evaluation: dict | None
checkpoint_id: str | None
```

#### 4.2 主要ノード（LangGraph推奨）
- **Planner Node**：高レベル計画立案（オプション）
- **Agent Node**：メインLLMコール（ツール呼び出し判断）。`instructor` / `pydantic` + `structured output` 必須
- **Tool Node**：ツール実行前に`PermissionGuard`を通す
- **Reflection / Evaluator Node**：自己評価・軌道修正（Reflectionパターン）
- **HumanApproval Node**：危険ツール使用時の中断
- **Summarizer Node**：長期実行時の記憶圧縮

#### 4.3 Tool Registry & Executor
ツールには以下のメタデータを必須とする：

- `category`: `safe` | `write` | `code` | `browser` | `external_api`
- `required_approval`: bool
- `rate_limit`: dict
- `timeout_seconds`: int
- `output_schema`: Pydantic model（構造化検証用）

実行フローは必ず **Pre-tool Guard → Execute in Sandbox → Post-tool Guard → Record** とする。

### 5. 推奨技術スタック（2026年現在）

- **Core Framework**: **LangGraph**（LangGraph Cloudも選択肢）※最も成熟
- **LLM Abstraction**: LiteLLM + OpenRouter / Azure AI / Anthropic Bedrock
- **Structured Output**: Instructor + Pydantic v2 または Outlines / Guidance
- **Memory**: PGVector（短期＋長期兼用）+ Redis（会話状態）
- **Checkpointer**: PostgresSaver（本番）または RedisSaver
- **Sandbox**:
- Code: E2B または 自前セキュアコンテナ（gVisor / Kata Containers）
- Browser: Browserbase / Hyperbrowser / 自前Playwright Worker
- **Observability**: LangSmith（最強）＋ OpenTelemetry Collector
- **Evaluation Harness**:
- RAGAS拡張版
- 独自の `AgentTrajectoryEvaluator`（Goal Achievement Rate, Tool Efficiency, Safety Violation Rate, Cost per Task）

### 6. サンプル実装の骨子（LangGraph v0.2+）

```python
graph = StateGraph(AgentState)

graph.add_node("agent", agent_node) # LLM + tool calling
graph.add_node("tools", tool_node)
graph.add_node("evaluator", evaluator_node)
graph.add_node("human_approval", human_node)

graph.add_conditional_edges(
"agent",
route_after_agent, # tool_callsがあるか、finishか、reflectか
{"tools": "tools", "evaluator": "evaluator", "end": END}
)

# Checkpointer必須
memory = PostgresSaver.from_conn_string(...)
app = graph.compile(checkpointer=memory, interrupt_before=["human_approval", "tools"])
```

中断・再開・編集・リプレイがすべてネイティブにできるのが最大の強みです。

### 7. 評価ハーネス設計（内蔵推奨）

評価指標例：
- **Task Success Rate**（最終目標達成率）
- **Tool Efficiency**（不要ツール呼び出し回数）
- **Safety Compliance Rate**
- **Cost Efficiency**（1タスクあたりの費用）
- **Trajectory Quality**（LLM-as-Judgeによる5段階評価）

定期的に合成タスクセットで回してリーダーボード化すると、バージョン改善が加速します。

### 8. セキュリティ・安全設計のポイント

1. **Tool Permission Matrix**（ユーザー/組織/プロジェクトごとに定義）
2. **Pre-execution Approval Flow**（危険操作は必ず人間承認）
3. **Output Guardrails**（Llama-Guard3 / Nvidia NeMo / 自前分類器）
4. **Sandbox Isolation**（ネットワーク隔離、ファイルシステム仮想化）
5. **Rate Limiting & Budget Guard**（トークン/金額で強制停止）

---

### 追加で欲しいもの

この設計をベースに、以下のいずれかを深掘りできます：

- **詳細なLangGraph実装コード一式**
- **Multi-Agent版ハーネス設計**（Supervisor + Specialistパターン）
- **大規模ソフトウェアエンジニアリングエージェント向けハーネス**（OpenDevin風）
- **評価ハーネスの具体的な実装例**
- **コスト最適化・キャッシュ戦略**

必要に応じて「**詳細版**」または「**特定ユースケース版**」とコメントしてください。すぐに設計書・コード・図を追加で出します。