Local AI Foundry

1. エグゼクティブサマリー

本システムは、Dify上の複数AIエージェント、n8n、ComfyUIを連携させ、記事・X投稿・タグ・画像を一体の成果物パッケージとして生成するローカルAI基盤である。

従来は「Workflowが正常終了したか」が成功判定の中心だった。しかし、Planning / Researchが部分スキーマしか返さなくてもWritingが偶然本文を作り、空のX投稿や無関係な固定タグを含む成果物が成功扱いされる事象が発生した。これを契機に、工程成功・契約成功・成果物成功を分離して扱う設計へ移行している。

2. 目的・スコープ

目的

ローカル環境で、複数のAIエージェントが担当工程を分担し、再現性・監査性・拡張性を備えたコンテンツ生産ラインを構築する。

現在の主な成果物

3. 設計原則

4. 全体アーキテクチャ

5. 役割・責務

6. 入力正規化設計

UI入力は任意欄を含むが、Workflow内部ではStart直後の入力正規化ノードで確定値にする。後続はStart Nodeを直接読まず、正規化済み値を参照する。

{
  "original": {"target_reader": "", "tone": "", "article_length": ""},
  "normalized": {
    "target_reader": "一般層",
    "tone": "標準",
    "article_length": "2000字前後"
  },
  "defaults_applied": ["target_reader", "tone", "article_length"]
}

7. DTO / IF設計

DTO（Data Transfer Object）は、Agent間の受け渡し専用データ構造であり、内部API仕様に相当する。

整形ノードの論理出力

{
  "raw": { "...": "LLMが実際に返した内容" },
  "normalized": { "...": "規格化されたDTO" },
  "contract": {
    "status": "ok | normalized | failed",
    "schema_valid_before_normalization": false,
    "missing_required": [],
    "defaulted_optional": [],
    "fallback_from_start": [],
    "moved_fields": [],
    "invalid_types": [],
    "notes": []
  }
}

8. Planning DTO契約

9. Research DTO契約

10. 契約整形・契約ゲート

契約状態

ゲート配置

Planning Agent
  → Planning Normalize
  → Planning Contract Gate
  → Research Agent
  → Research Normalize
  → Research Contract Gate
  → Writing Agent

Planning failed時にResearchを走らせない。Research failed時にWritingを走らせない。これにより、壊れた部分情報を後続が「それっぽく」利用して成果物を作るサイレントフェイルを防ぐ。

11. Writing / Package Output

Planning / Research契約が正常でも、Writingが空成果物を返すケースが確認された。Package Outputに最低限チェックを置き、空の正常成果物を禁止する。

Writingで確認された問題

• 長い記事本文を先に出すJSONでは、後半のX投稿・タグが崩れやすい。
• 救済パースが配列の値ではなく、"x_posts" / "tags"というキー名を拾った。
• Package Outputの固定レトロゲームタグが、欠落を隠して正常に見せた。

採用した暫定対策

• Writing出力順を短い配列（X投稿・タグ）先、長文記事最後へ変更。
• 救済配列抽出のキー名混入バグを修正。
• 固定タグフォールバックを削除。
• 記事・X投稿・タグが空ならPackageでfailed。

12. 証跡・監査

契約整形により、元のAgent出力と後続が参照したデータを区別して残す。

証跡はhandoff_trace / artifact / logs / Audit DTO / Package Outputへ渡し、後から「Agentが自力で契約を守ったか、構造整形が発動したか」を確認可能にする。

13. サイレントフェイル

今回の代表例

Planning：handoffだけ返却（外側スキーマ欠落）
Research：handoffだけ返却（外側スキーマ欠落）
Writing：部分情報だけで本文を生成
Review / Audit：通過
Package：成功
結果：本文は良いが、X投稿は ["x_posts"]、タグは別テーマ固定値

構文上正しいJSONや自然な本文が生成されるため、クラッシュより発見が難しい。契約ゲートと成果物最低条件の両方が必要である。

14. テスト戦略

固定回帰ケース

構造テスト

• YAML構文、ノード数、エッジ数、接続経路。
• Start直読みの残存検索。
• raw Agent textを読むノードの限定。
• 固定意味フォールバックの残存検索。

実行テストの合格条件

• Planning / Research contractが期待値。
• metadata.topicがStartのtopic原文。
• article / x_posts / tagsが非空かつ型正常。
• ["x_posts"]、["tags"]を拒否。
• 別テーマの固定タグが存在しない。
• failedを正常パッケージとして送信しない。

15. 2026年7月15日時点の現在地

16. 推奨ロードマップ

17. 主要設計判断と理由