# 機能設計書 22-Lead Agent

## 概要

本ドキュメントは、Liam DBシステムにおけるLead Agent（リードエージェント）の機能設計を記述するものである。Lead Agentは、Deep Modelingワークフローにおいて複数のエージェント（PM Agent、DB Agent、QA Agent）の調整と制御を担当する中心的なエージェントである。

### 本機能の処理概要

Lead Agentは、LangGraphフレームワークを使用したマルチエージェントシステムのオーケストレーターとして機能し、ワークフロー全体の進行状況を監視し、適切なエージェントへのルーティングを行う。

**業務上の目的・背景**：データベース設計のワークフローは複数のフェーズ（要件分析、スキーマ設計、品質検証）から構成される。Lead Agentは、これらのフェーズを適切に連携させ、ユーザーの要求に応じた効率的なワークフロー実行を実現する。各専門エージェントの作業を調整し、全体最適なワークフロー進行を保証する。

**機能の利用シーン**：デザインセッション詳細画面でユーザーがメッセージを入力すると、Lead Agentがまずメッセージを分類し、適切なエージェント（PM Agent、DB Agent）にルーティングする。また、QAが完了した後はワークフローのサマリーを生成して終了処理を行う。

**主要な処理内容**：
1. ユーザーメッセージを分類し、次に実行すべきエージェントを決定
2. スキーマ問題の有無を確認し、DB Agentへのルーティングを判断
3. QA完了状態を確認し、ワークフローサマリーを生成
4. 複数エージェント間の状態を調整・管理

**関連システム・外部連携**：OpenAI API（gpt-5-nano）を使用してワークフローサマリーを生成する。LangGraphのCommand APIを使用してグラフ内のルーティングを制御する。

**権限による制御**：Lead Agentの実行には認証済みユーザーであることが必要であり、組織に紐づくデザインセッション内でのみ実行可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | デザインセッション詳細画面 | 主画面 | Deep Modelingワークフローの制御とエージェント間調整 |

## 機能種別

計算処理 / データ連携 / 制御処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| messages | BaseMessage[] | Yes | ワークフローの会話履歴 | - |
| schemaData | Schema | Yes | 現在のデータベーススキーマ | - |
| analyzedRequirements | AnalyzedRequirements | Yes | PM Agentが分析した要件 | - |
| schemaIssues | SchemaIssue[] | No | QA Agentが検出したスキーマ問題 | - |
| designSessionId | string | Yes | デザインセッションの識別子 | UUID形式 |

### 入力データソース

- 親グラフ（createGraph.ts）から渡されるWorkflowState
- 各サブエージェント（PM Agent, DB Agent, QA Agent）から更新される状態

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| messages | BaseMessage[] | Lead Agentの応答メッセージ（サマリー等） |
| next | string | 次に実行するエージェント識別子（'pmAgent', 'dbAgent', END） |

### 出力先

- ワークフロー状態の更新
- 親グラフへのルーティング指示
- ストリーミング応答によるUI更新

## 処理フロー

### 処理シーケンス

```
1. classifyMessage（分類ノード）
   └─ ワークフロー状態を分析し、次のアクションを決定
   └─ Commandオブジェクトでルーティングを指示
2. [条件分岐] shouldRouteDBAgent
   └─ true: dbAgentへルーティング
   └─ false: 次の条件へ
3. [条件分岐] isQACompleted
   └─ true: summarizeWorkflowへ
   └─ false: pmAgentへルーティング
4. summarizeWorkflow（サマリーノード）
   └─ LLMでワークフローサマリーを生成
   └─ ENDへ遷移
```

### フローチャート

```mermaid
flowchart TD
    START[開始] --> A[classifyMessage]
    A --> B{スキーマ問題あり?}
    B -->|Yes| C[dbAgentへルーティング]
    B -->|No| D{QA完了?}
    D -->|Yes| E[summarizeWorkflow]
    D -->|No| F[pmAgentへルーティング]
    C --> END1[終了]
    E --> END2[終了]
    F --> END3[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-22-01 | スキーマ問題優先 | スキーマ問題がある場合は最優先でDB Agentにルーティング | schemaIssues.length > 0 |
| BR-22-02 | QA完了判定 | テストケースにSQLが設定されていればQA完了と判定 | testcase.sql !== '' |
| BR-22-03 | デフォルトルーティング | 上記条件に該当しない場合はPM Agentにルーティング | 常時 |

### 計算ロジック

- QA完了判定: テストケース配列を走査し、sqlフィールドが空でないものが存在するかチェック

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 状態読み取り | checkpoints | SELECT | チェックポイントからワークフロー状態を復元 |
| 状態保存 | checkpoints | INSERT/UPDATE | 更新された状態をチェックポイントに保存 |

### テーブル別操作詳細

#### checkpoints

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | channel_values | Lead Agentの出力状態 | LangGraphチェックポイントサーバー経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| LLM_ERROR | LLM呼び出しエラー | サマリー生成時のLLM応答エラー | リトライポリシーに従い再試行 |
| STATE_ERROR | 状態エラー | ワークフロー状態が不正 | エラーをthrowしワークフロー停止 |

### リトライ仕様

RETRY_POLICYに従い、以下のノードでリトライを実施：
- classifyMessage
- summarizeWorkflow

## トランザクション仕様

Lead Agentの各ノード処理はLangGraphのチェックポイント機能により状態が永続化される。Commandオブジェクトによるルーティング指示は親グラフの遷移制御として機能し、アトミックに処理される。

## パフォーマンス要件

- classifyMessage: ルーティング判定は同期処理で即時完了
- summarizeWorkflow: LLMストリーミング応答でリアルタイムフィードバック

## セキュリティ考慮事項

- OpenAI APIキーは環境変数で管理
- ワークフロー状態には機密情報が含まれる可能性があるため、組織単位でアクセス制御

## 備考

Lead AgentはDeep Modelingワークフローのオーケストレーターとして、PM Agent、DB Agent、QA Agentの実行順序と状態遷移を制御する中心的な役割を担う。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Lead Agentはワークフロー全体の状態を扱うため、workflowAnnotationの理解が必須。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | workflowAnnotation.ts | `frontend/internal-packages/agent/src/workflowAnnotation.ts` | ワークフロー全体の状態定義（messages, schemaData, analyzedRequirements, schemaIssues, next等） |
| 1-2 | types.ts | `frontend/internal-packages/agent/src/types.ts` | WorkflowState型定義 |

**読解のコツ**: `next`フィールドがルーティング先を示す重要なフィールド。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | createLeadAgentGraph.ts | `frontend/internal-packages/agent/src/lead-agent/createLeadAgentGraph.ts` | Lead Agentのグラフ構築 |

**主要処理フロー**:
1. **7-8行目**: StateGraphの初期化とworkflowAnnotation使用
2. **11-18行目**: classifyノードの追加（ends指定でCommand対応）
3. **19行目**: START→classifyエッジ
4. **21行目**: summarizeWorkflow→ENDエッジ

#### Step 3: ルーティングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | classifyMessage/index.ts | `frontend/internal-packages/agent/src/lead-agent/classifyMessage/index.ts` | ルーティング判定ロジック |
| 3-2 | workflowStatus.ts | `frontend/internal-packages/agent/src/lead-agent/utils/workflowStatus.ts` | 状態判定ユーティリティ |

**主要処理フロー**:
- **6-11行目（classifyMessage）**: shouldRouteDBAgent判定→dbAgentへ
- **14-16行目**: isQACompleted判定→summarizeWorkflowへ
- **19-22行目**: デフォルト→pmAgentへ

#### Step 4: サマリー生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | summarizeWorkflow/index.ts | `frontend/internal-packages/agent/src/lead-agent/summarizeWorkflow/index.ts` | ワークフローサマリー生成 |

**主要処理フロー**:
- **43-46行目**: gpt-5-nanoモデル初期化
- **48-56行目**: サマリー生成プロンプト
- **58-69行目**: ストリーミングLLM呼び出し

### プログラム呼び出し階層図

```
createGraph (createGraph.ts)
    │
    └─ leadAgentSubgraph (createLeadAgentGraph.ts)
           │
           ├─ classifyMessage
           │      ├─ shouldRouteDBAgent (workflowStatus.ts)
           │      └─ isQACompleted (workflowStatus.ts)
           │
           └─ summarizeWorkflow
                  └─ generateWorkflowSummary
                         └─ ChatOpenAI.stream()
```

### データフロー図

```
[入力]                    [処理]                         [出力]

WorkflowState ─────────▶ classifyMessage ──────────────▶ Command
       │                        │
       │                        ├─ next: 'dbAgent' (スキーマ問題あり)
       │                        ├─ next: 'pmAgent' (デフォルト)
       │                        └─ goto: 'summarizeWorkflow' (QA完了)
       │
       └───────────────▶ summarizeWorkflow ────────────▶ messages (サマリー)
                                │                            │
                                └─ LLM呼び出し               └─ next: END
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| createLeadAgentGraph.ts | `frontend/internal-packages/agent/src/lead-agent/createLeadAgentGraph.ts` | ソース | Lead Agentグラフのエントリーポイント |
| classifyMessage/index.ts | `frontend/internal-packages/agent/src/lead-agent/classifyMessage/index.ts` | ソース | メッセージ分類とルーティング判定 |
| summarizeWorkflow/index.ts | `frontend/internal-packages/agent/src/lead-agent/summarizeWorkflow/index.ts` | ソース | ワークフローサマリー生成 |
| workflowStatus.ts | `frontend/internal-packages/agent/src/lead-agent/utils/workflowStatus.ts` | ソース | 状態判定ユーティリティ |
| workflowAnnotation.ts | `frontend/internal-packages/agent/src/workflowAnnotation.ts` | ソース | ワークフロー状態定義 |
| types.ts | `frontend/internal-packages/agent/src/types.ts` | ソース | 型定義 |
| createGraph.ts | `frontend/internal-packages/agent/src/createGraph.ts` | ソース | 親グラフでのLead Agent呼び出し |
| errorHandling.ts | `frontend/internal-packages/agent/src/utils/errorHandling.ts` | ソース | リトライポリシー定義 |
| streamingLlmUtils.ts | `frontend/internal-packages/agent/src/utils/streamingLlmUtils.ts` | ソース | LLMストリーミング処理 |
| constants.ts | `frontend/internal-packages/agent/src/streaming/constants.ts` | 設定 | SSE_EVENTSイベント定義 |
