Blog

アーキテクチャドキュメント

プロジェクト: Resume Review マルチエージェントシステム
バージョン: 1.0
最終更新: 2026-01-11

概要

Resume Review マルチエージェントシステムは、LangGraph を活用して複数の専門AIエージェントを調整し、職務経歴書を自動的にレビュー・改善するPythonベースのCLIツールです。ハイブリッドマルチモデルアーキテクチャにより、単一モデル構成と比較して 大幅なコスト削減 と 高速な実行 を実現しています。

主要技術

システムアーキテクチャ

ハイレベルフロー

Resume Review Agent System Architecture

アーキテクチャ原則

  1. ファンアウト/ファンインパターン: エージェントは効率化のため並列実行
  2. 型安全な状態: Pydanticモデルがノード間の契約を強制
  3. ステートレスエージェント: 各エージェントはReviewStateの純粋関数
  4. コスト最適化: 認知タスクに応じて異なるモデルを使用
  5. グレースフルデグラデーション: オプション機能（デザインレビュー）がワークフローをブロックしない

状態管理

ReviewStateスキーマ

ワークフロー全体の状態は、すべてのノードを流れる単一のPydanticモデルで管理されます：

class ReviewState(TypedDict):
    # 入力
    qmd_content: str
    target_role: str
    screenshot_path: Optional[str]
    job_posting_content: Optional[str]
    
    # エージェントフィードバック（個々のノードがこれらに書き込み）
    recruiter_feedback: Optional[Feedback]
    tech_writer_feedback: Optional[Feedback]
    copywriter_feedback: Optional[Feedback]
    
    # 集約結果
    current_feedback: List[Feedback]
    current_score: float
    
    # イテレーション追跡
    iteration: int
    max_iterations: int
    threshold: float
    
    # リビジョン
    revised_content: Optional[str]
    
    # ポートフォリオ & デザイン
    portfolio_items: List[PortfolioItem]
    design_feedback: Optional[DesignFeedback]

状態遷移フロー

State Transition Flow

主要な不変条件:

マルチエージェントオーケストレーション

ファンアウト/ファンインパターン

システムはLangGraphのネイティブなファンアウト/ファンインを使用して並列エージェント実行を行います：

ファンアウト（Routerノード）:

# Routerノードが並列実行をトリガー
workflow.add_edge("router", "recruiter")
workflow.add_edge("router", "tech_writer")
workflow.add_edge("router", "copywriter")

ファンイン（Aggregatorノード）:

# Aggregatorは3つすべての完了を待機
workflow.add_edge("recruiter", "aggregator")
workflow.add_edge("tech_writer", "aggregator")
workflow.add_edge("copywriter", "aggregator")

LangGraphが自動的に処理するもの：

エージェントの責務

エージェントモデル視点重み
リクルーターGemini 3.0 Flash契約獲得、市場性30%
テクニカルライターOpenAI o3-mini技術的深さ、明瞭性20%
コピーライターClaude Sonnet 4.5マーケティング効果、インパクト25%
UXデザイナーGemini 3.0 Flash情報階層、スキャナビリティ15%
ビジュアルデザイナーGemini 3.0 Flash視覚的プレゼンテーション（スクリーンショットから）10%

設計根拠:

コスト最適化

ハイブリッドマルチモデル戦略

ベースライン（すべてのエージェントにClaude Opus 4.5）:

最適化済み（ハイブリッド構成）:

モデル選択ロジック

# config/model_config.pyで定義
DEFAULT_MODEL_ASSIGNMENTS = {
    "recruiter": "gemini-3.0-flash",      # 大量処理、低コスト
    "tech_writer": "o3-mini",             # 高度な推論
    "copywriter": "claude-sonnet-4-5-20250929",  # クリエイティブ品質
    "ux_designer": "gemini-3.0-flash",    # 高速ビジョン
    "visual_designer": "gemini-3.0-flash", # 高速ビジョン
    "revisor": "gemini-3.0-flash",        # 全文書き換え、大量処理
}

コスト内訳（イテレーションあたり）：

コンポーネントモデル入力トークン出力トークンコスト
リクルーターGemini 3.0 Flash約2K約500$0.003
テクニカルライターo3-mini約2K約500$0.15
コピーライターClaude Sonnet 4.5約2K約500$0.20
UXデザイナーGemini 3.0 Flash約2K約300$0.002
ビジュアルデザイナーGemini 3.0 Flash約1K（画像）約300$0.002
リバイザーGemini 3.0 Flash約3K約2K$0.008
合計---約$0.37/イテレーション

通常のワークフロー: 1-2イテレーション → 合計$0.37-$0.74

ツール統合

LLMクライアントファクトリ

プロバイダーの違いを統一インターフェースで抽象化：

class LLMClient:
    def invoke(self, messages: List[dict], model: str) -> str:
        """同期呼び出し"""
        
    def invoke_with_vision(self, prompt: str, image_path: str, model: str) -> str:
        """ビジョンモデル呼び出し（現在Geminiのみ）"""

プロバイダー:

スクリーンショット取得（Playwright）

ビジュアルデザインレビューに使用：

def capture_screenshot(url: str, output_path: str) -> str:
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page(viewport={"width": 1920, "height": 1080})
        page.goto(url)
        page.screenshot(path=output_path, full_page=True)
        browser.close()
    return output_path

統合フロー:

  1. CLIフラグ: --screenshot-url http://localhost:3000/ja
  2. ワークフロー開始前にスクリーンショットを取得
  3. ReviewStateにscreenshot_pathを渡す
  4. ビジュアルデザイナーエージェントがビジョンモデルで分析

Quarto検証

生成されたQMDファイルが構文的に有効であることを確認：

def validate_quarto(content: str) -> ValidationResult:
    # 一時ファイルに書き込み
    # 実行: quarto check {temp_file}
    # エラーをパースして構造化フィードバックを返す

自動リトライループ（Feature 009）:

主要な設計判断

1. なぜLangGraph？

検討した代替案: LangChain LLMChain、カスタムオーケストレーション

LangGraphの利点:

2. なぜ状態にPydantic？

検討した代替案: プレーン辞書、dataclasses

Pydanticの利点:

3. なぜマルチモデルハイブリッド？

検討した代替案: Claudeのみ、Geminiのみ

ハイブリッドの利点:

4. なぜファンアウト/ファンイン？

検討した代替案: 順次エージェント実行

ファンアウト/ファンインの利点:

パフォーマンス指標

実行時間

トークン使用量

品質指標

今後の拡張

計画中の機能

研究方向

参考資料

💡 コントリビューション

このシステムはClaude Opus 4.5とGemini Flashをペアプログラミングパートナーとして反復的に構築されました。すべての設計判断は将来の参照のためにspecs/に文書化されています。

質問や改善については、メインリポジトリをご覧ください。