メインコンテンツまでスキップ

アーキテクチャ

1. プロダクトの考え方​

現在の A2E のプロダクト目標は、「AI による対話的リクエスト」を「統制可能なワークフロー実行プロセス」に変換し、その実行中も十分なエンジニアリング制御能力を保持することです。単発の結果だけを返すことは目的ではありません。

この目標のために、現在の実装は次の最小閉ループを採用しています。

  • 定義：workflow を実行ブループリントとして用い、ノード、接続、入出力制約を表現します。
  • 実行：run を1回の実行インスタンスとして用い、作成・キャンセル・再開などのライフサイクル操作を支えます。
  • 観測：event を実行事実の記録として用い、増分取得と状態追跡を可能にします。
  • 人的介入：review をレビュー機構として用い、重要ノードで一時停止し、判断を待ってから実行を継続します。

対話入口として、A2E は2本の並行パスを提供します。

  • Web 入口：可視的な編集、実行監視、レビュー処理向け
  • MCP 入口：Codex / CLI などの AI クライアントが、ツール呼び出しで同一エンジン能力にアクセスするための入口

つまり A2E は、「UI だけのフローツール」でも「CLI だけの自動化スクリプト集」でもありません。workflow / run / review / event という統一セマンティクスで Web と AI 協調エンドポイントを結ぶ実行カーネルです。現行バージョンは Experimental と位置づけられ、アーキテクチャの成立性とエンジニアリング閉ループの検証を重視しています。

2. 技術アーキテクチャ全体像​

現在の実装は、「コンポーネント関係」と「実行時フロー」の2つの視点から理解できます。

2.1 コンポーネント関係​

現在の実装に基づく主要コンポーネントの責務は次のとおりです。

  • Web
    • ワークフロー編集、実行監視、レビュー処理、設定、Codex との対話 UI を提供します。
    • HTTP と WebSocket を通じて、Server が公開する統一サービス能力にアクセスします。
  • MCP Server
    • STDIO を通じて、Codex / CLI などの MCP クライアントへツールインターフェースを公開します。
    • ワークフロー状態を直接扱わず、loopback HTTP により A2E Server を呼び出します。
  • A2E Server
    • ワークフロー、ノード、実行、レビュー、イベント、AI ノード関連サービスを担います。
    • 併せて Codex ログイン、モデル照会、PTY セッション、実行ディレクトリ管理も担います。
  • Codex CLI
    • AI ノードの実行ランタイムとして機能し、Server によって制御ディレクトリ内で起動されます。
    • 構造化出力、ログ、成果物ファイルを実行ディレクトリへ書き戻します。
  • SQLite + ファイルシステム
    • SQLite は workflow / run / node_run / review / event などの構造化状態を保存します。
    • ファイルシステムは AI ノード定義、実行入出力、ログ、成果物、異常手がかりを保存します。

現行バージョンでは独立したキューや Worker は導入していません。ワークフロー調整、状態遷移、レビュー協調、AI ノード制御はすべて Server プロセスが直接担います。

2.2 実行時フロー​

このフローは現行バージョンの最小閉ループを示しています。agent.codex が自動実行を担い、human.review が人的チェックを担い、run / review / event の統一セマンティクスで Web と MCP を同一実行カーネルへ収束させています。

全体として、この構成は《技術選定ガイド》における「最小の有効閉ループ、復旧可能、可観測、単一マシンで動作可能」という方向性と整合しており、今後の方針制御や観測強化のための安定した境界も確保しています。

3. Workflow​

3.1 ライフサイクル​

ワークフロー実行のライフサイクルは、次の5段階で理解できます。

  1. 作成：実行要求を受け取ると、独立した1回の実行を作成します。
  2. 開始：エンジンがタスクを引き継ぎ、ノード依存順に進行させます。
  3. 実行：ノードを順次処理し、必要に応じて中間成果物とイベント記録を生成します。
  4. 一時停止：人間の判断が必要な場面では、フローを停止して判断待ちにします。
  5. 終了：実行結果に応じて完了、失敗、キャンセルのいずれかに入り、まとめ情報を生成します。

このライフサイクルの核心は、「AI の自動実行」を制御可能・説明可能・再生可能なエンジニアリングプロセスへ変えることにあります。

3.2 状態機械​

状態機械は統一セマンティクスを採用し、主な状態は次のとおりです。

  • 待機中
  • 実行中
  • 一時停止中
  • 完了
  • 失敗
  • キャンセル

代表的な遷移は次のとおりです。

  • 待機中 -> 実行中：エンジンが処理を開始
  • 実行中 -> 一時停止中：レビューまたは人的引き継ぎが発生
  • 一時停止中 -> 実行中：レビュー承認後に継続
  • 実行中 -> 完了：期待どおりに終了
  • 実行中 -> 失敗：重要ノードが失敗し、引き継ぎ復旧も行われない
  • すべての活性状態 -> キャンセル：ユーザーまたはシステムが能動的に終了

状態変化はイベントとして記録され、観測、監査、障害調査に利用されます。

3.3 入出力契約​

入出力契約は、「フローがつながること」と「結果が再利用できること」を保証するための仕組みで、2つの層に分かれます。

  • 実行前検証：フロー入力とノード出力宣言が完全かを確認し、明らかな誤りを事前に遮断します。
  • 実行時検証：ノード実行後に出力構造が契約に適合するか確認し、不正データが下流へ流れることを防ぎます。

各ノードの入力は2つのソースから来ます。

  • フロー入口入力
  • 上流ノードの出力

結果は構造化データとファイル成果物の両方として保存され、後から確認・再生・監査できるようになります。

4. AIノード​

4.1 実行モデル​

AI ノードは、自動的なコンテンツ生成と実行判断を担う、フロー内の主要な「生産ノード」です。

現在の実行モデルには次の特徴があります。

  • 非同期実行：ノードはバックグラウンドタスクで駆動され、フロー全体のブロッキングを避けます。
  • 設定駆動：実行戦略はノードテンプレートで一元管理され、モデル、タイムアウト、権限範囲などを含みます。
  • 結果回収：実行終了後、システムが状態、出力、成果物を回収し、統一記録へ格納します。

4.2 入出力と成果物​

AI ノードのデータ表現は3種類です。

  • 入力：フローコンテキストと上流ノード結果から来るもの
  • 出力：下流ノードで消費される構造化結果と利用可能コンテンツ
  • 成果物：実行ログ、生成ファイル、異常手がかりなどの実行証跡

主出力が利用できない場合でも、システムは互換的なフォールバック機構を持ち、可能な限り観測と処理を継続できるようにします。 これらの情報は統一的に蓄積され、Web ページと MCP ツールの両方で利用されます。

4.3 失敗と復旧​

AI ノード失敗時の処理方針は、「まず収束させ、次に復旧する」です。

  • 収束：失敗理由と文脈証跡を記録し、問題が黙って飲み込まれないようにします。
  • 引き継ぎ：高不確実性の場面では自動的にレビューへ入り、誤りの拡散を防ぎます。
  • 復旧：レビュー承認後はフローを継続でき、ワークフロー全体を最初からやり直す必要はありません。

また、主フローを壊さずに問題を再現し、修正を検証できるようにデバッグ能力も保持しています。

5. レビューノード​

5.1 能動レビュー​

能動レビューは、設計時点で明示的に構成される人的チェックポイントです。

フローがそのノードに到達すると、システムは自動的に一時停止し、レビュータスクを生成します。レビュアーは現在の文脈に基づいて判断し、実行継続の可否を決定します。

5.2 受動レビュー​

受動レビューは、実行時に動的に発火するフォールバック機構です。

システムが異常結果、リスク信号、または実行の不確実性を検知すると、フローを人間判断モードへ切り替え、安全性と制御可能性を優先します。

5.3 中断と再開​

レビューノードは、「中断 -> 判断 -> 再開」の閉ループを支えます。

  • 承認：フローは再開し、下流へ進みます。
  • 却下：フローは失敗として収束します。
  • 取消：フローを終了し、未完了レビューも閉じて宙づり状態を防ぎます。

この機構により、自動実行と人間判断は分断されず、滑らかに切り替えられます。

6. モジュール関係とデータフロー​

モジュール関係は、「2つの入口」と「1つのカーネル」に単純化できます。

  1. Web 入口
    • 人間ユーザー向けで、フロー設定、実行観測、レビュー処理に使います。
  2. MCP 入口
    • AI クライアント向けで、ツール経由で同じ能力を呼び出します。
  3. 統一カーネル
    • 2つの入口は最終的に同一の実行カーネルへ入り、そこで状態遷移、イベント記録、レビュー協調、結果永続化を担います。
    • 現在のカーネル能力は主に、ワークフロー管理、実行調整、レビュー協調、AI ノード実行です。

最終的に、フロー定義、実行インスタンス、ノード状態、レビュー記録、イベント軌跡という統一データセマンティクスが形成されます。
これこそが、A2E が人間と AI の協調、そして複数入口の一貫性を同時に支えられる鍵です。