メインコンテンツへスキップ
見出し画像

Agent-Controller完成――AI開発の司令塔を「状態遷移図」で作り直した

  • 割引あり

以前、私はAIにソフトウェア開発を続けてもらうための仕組みとして「AI-director」を作りました。

人間が毎回細かな指示を出さなくても、AIが設計し、実装し、テストし、問題があれば修正する。そんな開発の司令塔を目指したものです。

ただ、実際に動かしてみると課題も見えてきました。

AIは文章を読み、考え、コードを書くことは得意です。しかし、長い仕事の中で「今はどの段階か」「次にどこへ進むか」「失敗したらどこへ戻るか」を厳密に管理するのは、必ずしも得意ではありません。

そこで今回、以前の仕組みを土台から作り直しました。

新しい名前は「Agent-Controller」です。

作り直すときに採用した考え方が、グラフエンジニアリングでした。

そして実際に作ってみて、私はこう思いました。

グラフエンジニアリングとは、AIの仕事を状態遷移図として設計することではないか。

この記事では、Agent-Controllerをどのように作り直したのかを、プログラムを知らない人にも分かるように説明します。

この記事が解決する悩み

この記事は、AIコーディングを使い始めたものの、次のような壁にぶつかっている人のために書きました。

  • AIへ毎回細かな指示を出すことに疲れている

  • 実装、テスト、修正を自動で回したいが、途中でAIが迷子になる

  • AIが「完成しました」と言っても、本当に完成したのか信用できない

  • ワークフローを作ったら複雑になりすぎて、自分でも追えなくなった

  • LangGraphやグラフエンジニアリングに興味はあるが、何から考えればよいか分からない

  • 自律型AI開発と呼びながら、人間への質問ばかりで結局楽にならない

私自身が欲しかったのは、立派な研究用システムではありません。

私は、楽がしたかったのです。

AIへ同じ説明を繰り返さず、必要なところだけ人間が判断し、それ以外は工程に沿って先へ進んでほしい。そのためには、AIをさらに賢くするだけでは足りませんでした。

必要だったのは、AIが迷わず働ける「仕事の地図」でした。

この記事を読むことで、AI開発の自動化を単なるプロンプトの工夫ではなく、状態、遷移、停止条件、完了条件として整理する考え方が分かります。

無料部分では、グラフエンジニアリングと状態遷移の基本を説明します。

有料部分では、私が実際にAgent-Controllerを作り直したときの設計判断、サブステートマシンで巨大化を防いだ方法、AIの自己申告に頼らないCompleteGate、実行結果、公開リポジトリを紹介します。

AIに仕事を頼むだけでは「開発工程」にならない

普通に生成AIへプログラムを頼むと、だいたい次のようになります。

人間が指示する
↓
AIがコードを書く
↓
人間が結果を見る
↓
必要なら、また指示する

これは便利ですが、仕事の進行管理は人間が行っています。

AIは優秀な作業者ですが、現場監督はいません。

ソフトウェアを完成させるには、コードを書く以外にも多くの工程があります。

  • 何を作るのか確認する

  • 設計する

  • 実装する

  • テストする

  • レビューする

  • 説明書を更新する

  • 本当に完成したか確認する

しかも、一直線には進みません。

テストに失敗すれば実装へ戻ります。レビューで設計上の問題が見つかれば、設計まで戻ることもあります。判断材料が足りなければ、人間へ質問して回答を待たなければなりません。

つまり開発とは、単なる作業の列ではなく、行ったり来たりする道の集まりです。

この「道」を先に設計するのが、グラフエンジニアリングです。

グラフとは「丸と矢印」で表した仕事の地図

ここでいうグラフは、棒グラフや折れ線グラフではありません。

丸や箱を矢印でつないだ、仕事の流れの図です。

Agent-Controllerの大きな流れを単純化すると、次のようになります。

待機
↓
設計
↓
実装
↓
テスト
↓
レビュー
↓
文書更新
↓
完成

この「待機中」「設計中」「テスト中」などを、プログラムでは状態と呼びます。

そして、ある状態から別の状態へ移ることを状態遷移と呼びます。

電車にたとえると分かりやすいでしょう。

駅が状態、線路が遷移です。

電車は勝手に空を飛んで隣町へ行きません。決められた線路を通り、条件に合った駅へ進みます。

テストに合格すればレビュー駅へ進む。失敗すれば実装駅へ戻る。人間の判断が必要なら質問駅で止まる。

Agent-Controllerは、AIという電車を目的地まで走らせる路線管理システムです。



Agent-Controllerで使用した主な技術

ここから先を読みやすくするために、最初にAgent-Controllerで使用した技術をまとめておきます。

  • Python 3.12
    Controller本体と、状態管理や検証処理の実装に使用しました。

  • LangGraph
    設計、実装、テスト、レビュー、文書更新という工程を、グラフとして接続するために使用しました。

  • 状態遷移(ステートマシン)
    「現在どの工程にいるか」「成功したらどこへ進むか」「失敗したらどこへ戻るか」を管理します。

  • サブステートマシン/Subgraph
    巨大になった状態遷移図を、工程ごとの小さなグラフへ分割するために使用しました。

  • Pydantic v2
    AIとControllerの間で受け渡す状態や実行結果を、決められたデータ形式として検証します。

  • SQLite/Checkpoint
    実行途中の状態を保存し、質問への回答後や中断後に同じ場所から再開するために使用しました。

  • Typer/Rich
    コマンド操作と、状態や実行結果を読みやすく表示するCLI画面に使用しました。

  • pytest
    状態遷移、完了条件、停止と再開などが仕様どおり動くかを自動テストしました。

  • Git/GitHub
    コードと設計資料の変更履歴を管理し、保存や公開が完了したことを確認するために使用しました。

  • Codex CLI、Claude Code、AntigravityなどのAI Worker
    Controllerの指示を受け、設計、実装、テスト、レビューなど各状態の実作業を担当します。

ここから先は有料部分です

ここからは、Agent-Controllerで実際に採用した役割分担、ワークフローが巨大化した失敗、サブステートマシンによる分割、完成判定の仕組みまで踏み込みます。

 
 
猫好きプログラマ。半導体会社の技術者 Q&AサイトのQuoraでフォロワー数6000人の「ChatGPT情報交換所」を主宰する程生成AI好き ポートフォリオ https://hantani-portfolio.pages.dev/

あなたへのおすすめ