AIコーディングエージェントにタスクを投げて、待つ。10秒、20秒、40秒。終わってみれば変更は数行。で、思うわけです。あの40秒、何に使ったんだろう、と。
ブラックボックスなんですよね、だいたいのエージェントは。入力と出力は見える。途中は見えない。遅いとき、その理由が分からない。プロンプトが悪かったのか、ツールが詰まったのか、モデルが考え込んでいたのか。手がかりゼロで、次も同じように投げて、同じように待つ。
私は Andromity というオープンソース（MIT）のAIコーディングエージェントを作っている開発者です。この「途中が見えない」問題が我慢できなくて、実行の様子をそのままタイムラインで見られる機能を付けました。それが /waterfall です。この記事では、実際に遅かった実行を1件取り上げて、ウォーターフォールで原因を追う手順をそのまま書きます。
前提: Andromity v0.2.11（VS Code 拡張または CLI）が手元にあること。モデルの接続は BYOK の APIキー、またはローカルの Ollama で済ませておきます。
まず試したい人へ
VS Code 拡張が手軽です。
code --install-extension agenticmarket.andromity-agent
ターミナル派なら CLI もあります。
curl -fsSL https://raw.githubusercontent.com/agenticmarket/andromity/main/install.sh | bash
# または
pipx install andromity
BYOK（自分のAPIキーを持ち込む方式）で、Claude / GPT / Gemini / DeepSeek / Groq / OpenRouter など396以上のモデルが使えます。お金をかけたくない場合は Ollama でローカルモデルを無料で動かすこともできます。詳しくは 公式サイト と GitHub に置いてあります。
ウォーターフォールって何を見せてくれるのか
ブラウザの開発者ツールにあるパフォーマンスタイミングの表示、あれを思い浮かべてください。ネットワークタブのウォーターフォールチャートです。Andromity の /waterfall は、その「AIエージェント版」だと思ってもらえればだいたい合っています。
実行が始まると、リアルタイムでバーが伸びていきます。
- 推論のターン（モデルが考えている区間）
- ツール呼び出し（ファイル読み取り、検索、コマンド実行など）と、その1件ごとの所要時間
- サブエージェントへのフォーク（分岐した箇所）
つまり「全体で40秒かかった」という事実だけじゃなくて、40秒の内訳が目で見える。これがあると、遅さへの対処が「なんとなく」から「ここ」になります。
実例：40秒の実行を分解する
あるとき、テストの失敗を直すタスクを投げたら、完了まで約40秒かかりました。変更自体は小さい。おかしいなと思ってウォーターフォールを開きました。
上から眺めると、こんな構造でした。
- 最初の推論ターン — 数秒。通常運転。
- ファイル読み取りが数件 — どれも一瞬。
- リポジトリ全体への検索が1件、やたら長いバーを引いている。
- そのあとの推論と編集は、また数秒ずつ。
タイムラインの読み出しをテキストに起こすと、だいたいこんな内訳でした。
# /waterfall の読み出し（約40秒の実行）
turn 1 推論 3.1s
turn 2 read_file src/api/handler.ts 0.3s
read_file src/api/handler.test.ts 0.2s
grep "handleRequest"（範囲指定なし・リポジトリ全体） 24.6s ← 犯人
turn 3 推論 4.8s
turn 4 edit src/api/handler.ts 1.1s
run npm test 5.9s
──────────────────────────────────────────
合計 約40.0s
犯人は3でした。範囲を指定し忘れた検索が、巨大なディレクトリを舐めていて、全体の半分以上の時間を持っていっていた。モデルが遅かったわけでも、考え込んでいたわけでもない。ツールの1件がボトルネックだった、ただそれだけ。
ここがポイントで、内訳が見えない状態だと、この40秒は「エージェントって遅いな」で終わります。でも内訳が見えると、次の一手が具体的になる。
- 検索範囲をプロンプトで絞る（「src 配下だけ見て」）
- 大きな走査が要るなら、サブエージェントに切り出して並行させる
- フォルダの信頼モードを見直す（後述）
実際、範囲を絞って投げ直したら同じタスクは一桁秒で終わりました。劇的な話ではないです。でも、こういう小さい「なぜ」が毎回分かるかどうかで、エージェントへの信頼感はだいぶ変わります。
ついでに触れておきたい、周辺の仕組み
ウォーターフォールが主役ですが、実行を眺める文化と相性のいい機能が2つあります。
信頼モード（SAFE → TRUST → FULL → YOLO）。 フォルダを信頼するまでは何も実行されません。段階を上げるほど自動で進む範囲が広がる。いきなり全部任せるか、全部止めるか、の二択じゃないのが気に入っています。
/undo。 1ターンまるごと巻き戻せます。git の履歴は汚しません。「さっきの変更、やっぱり無しで」が怖くないと、エージェントに大きめのタスクを投げやすくなるんですよね。
あと、計画の進み具合はプランナー側でも追えます。
正直な限界の話
良いことばかり書くと宣伝っぽくなるので、限界も書いておきます。
ウォーターフォールは「どこで時間を使ったか」は教えてくれます。でも「なぜモデルがその判断をしたか」までは分かりません。推論ターンのバーは見えても、中の思考そのものが全部読めるわけではない。あくまでタイミングと実行の可視化です。遅い箇所の特定と再現には強いけれど、判断の質の監査まではしてくれない、というのが正直なところです。
もうひとつ。個人開発のプロジェクトなので、対応モデルや機能は大きな商用ツールと比べれば荒い部分もあります。
個人的な意見をひとつ
長い実行を「祈りながら待つ」のが、私は一番のストレスでした。タイムラインが見えるようになってから、エージェントの遅さは「イライラ」じゃなくて「直せるもの」に変わった。個人的には、可視化は速さそのものより大事だと思っています。速くなくても、理由が見えれば付き合える。
よくある質問
Q. /waterfall は、結局何を見せてくれるんですか？
実行中のエージェントをライブで表示するタイムラインです。推論のターン、ツール呼び出し1件ごとの所要時間、サブエージェントへのフォーク。この3つが1本の流れで見えます。
Q. エージェントが遅いとき、どこを見ればいいですか？
/waterfall を開いて、いちばん長いバーを探してください。私の経験では、犯人はたいていモデルではなく、範囲の広すぎる検索か、1件だけ長いツール呼び出しです。この記事の40秒もそうでした。
Q. Andromity は無料ですか？
本体は MIT ライセンスのオープンソースで、無料です。BYOK 方式なので、API の料金は自分の選んだプロバイダに直接払う形になります。お金をかけたくない場合は、Ollama でローカルモデルを動かせば API 料金はゼロです。
Q. コードのプライバシーはどうなっていますか？
コードが送られるのは、自分で選んだプロバイダだけです。Ollama でローカル実行する場合は、コードがマシンの外に出ることはありません。APIキーはローカルに暗号化して保存されます。
まとめ代わりに
- エージェントの遅さは、内訳を見れば大抵「どこか1件」に寄っている
- 見えると、プロンプトの絞り方も任せ方も変わる
もし同じような「待ち時間の正体不明」に心当たりがあれば、一度試してみてください。気に入ったら GitHub でスターをもらえると、個人開発の励みになります。