ブラウザエージェントを本番で使い始めると、最初に壁になるのは「昨日は通ったのに今日は落ちる」という現象です。Antigravity 自体の賢さは上がっていますが、相手は生のウェブであり、相手のほうはこちらの都合を知りません。私も個人アプリの運用と、知人の業務自動化を手伝うなかで、このフレーキーさに何度も心を折られかけました。
Antigravity のブラウザエージェントを「落ちる前提」で設計し、落ちても被害が出ない状態に持っていくための具体的な工夫を実例とともに整理しました。やり方の細部はプロジェクトによりますが、考え方は他のエージェント基盤でも流用できます。
フレーキーの正体を切り分ける
まず押さえておきたいのは、フレーキー（flaky）なタスクには大きく分けて 3 種類の原因があるということです。これを区別しないまま「再試行回数を増やす」で対処すると、問題が隠れるだけで根本は残ります。
- DOM 構造の変化: 相手のサイトが A/B テストや細かいリデザインを回しています。昨日と今日で要素のセレクタが別物になっている
- 非同期ロードのタイミング: ページは表示されているが、エージェントが触りたい要素がまだ JavaScript で差し込まれていない
- ネットワーク・セッション由来の揺らぎ: 認証トークンの期限切れ、CDN のエッジキャッシュ、Bot 判定による難読化
私が運用するボットは、最初はこれらを一緒くたに「なんか落ちた」として扱っていました。ログを丁寧に残す癖をつけたところ、原因の割合は体感で DOM 変化が 4 割、非同期ロードが 4 割、ネットワーク揺らぎが 2 割くらいでした。対処の優先順位が変わるので、切り分けは最初に仕込むべき計測です。
具体的には、エージェントの失敗時に「失敗した直前の DOM スナップショット」「失敗ステップのプロンプト」「その時点のネットワーク往復時間」を必ず保存する設計にしておきます。Antigravity 側のログだけでなく、自分の運用ログにも残すのがコツで、あとで原因分布を棒グラフにしたときに「なるほど、まず DOM 変化を潰すべきだな」と判断できます。
セレクタをエージェントに任せすぎない
フレーキーの最大の発生源は、DOM 構造の変化です。Antigravity のブラウザエージェントはかなり柔軟で、クラス名が変わった程度なら周辺文脈から要素を再推定します。ただし、この「推定」が成功するかどうかは相手サイト次第です。私が実務で踏んだ事例で言えば、ECサイトの「カートに入れる」ボタンの近くに、期間限定キャンペーンのボタンが差し込まれた日から、エージェントが誤ってそちらを押すケースが多発しました。
ここで私が使っている安全策は、「意味論的アンカー」を文章で指定する というやり方です。セレクタを直接書くのではなく、ドメイン用語でボタンを指定します。
現在開いている商品詳細ページで、税込価格の下にある
「カートに入れる」という意図のボタンをクリックしてください。
期間限定キャンペーンやクーポン取得など、購入とは直接関係ないボタンは
押さないでください。
迷ったら、「カートに入れる」「ADD TO CART」「買い物かごに追加」
のいずれかのテキストに完全一致するボタンを優先してください。このプロンプトのポイントは 2 つあります。1 つは、候補になりうる文言を開発者側で列挙していること。もう 1 つは、押してはいけないものを明示していることです。禁止リストを入れるだけで、A/B テストで挿入される新ボタンへの誤クリックは目に見えて減ります。
さらに厳しめに運用するタスクでは、「クリック前に対象要素のスクリーンショットを撮って保存する」「要素の周囲 100 ピクセル四方を画像として残す」といった、事後レビュー用の痕跡をセットで取らせています。これは本番運用で何かおかしいと気付いたときに、後追いで原因を絞り込むための救命具です。
時間で待たありません。状態で待つ
次に大きな原因が、非同期ロードのタイミングです。私は初期、time.sleep(2) に相当する固定待機を多用していました。書いた瞬間は通っているので安心しますが、相手のネットワークが遅い日や、自分の回線が揺らいだ日にあっさり崩れます。
Antigravity のエージェントに対しては、「時間で待つ」のではなく「状態で待つ」命令を書きます。
ログインフォームを送信したあと、次の条件をすべて満たすまで待機してください。
- URL のパスが /dashboard または /home のいずれかに変化している
- 画面内に「ようこそ、」または「Welcome, 」を含むテキスト要素が存在する
- ローディング用のスピナー（aria-busy="true" の要素）が画面上にゼロ件である
最長 20 秒まで待ち、満たされなければエラーを投げて終了してください。
スピナーが消えない場合のスクリーンショットを必ず添付してください。固定の sleep を書かないことで、回線が速ければ高速に、遅ければ粘り強く待つ挙動になります。このとき大事なのは、待機条件を 1 つに絞らず、複数の条件の AND で待つことです。URL の変化だけで判定すると、SPA の部分遷移で誤検知します。文字列の存在だけだと、差分レンダリングで拾い損ねます。複数条件を重ねて初めて、「ちゃんと次の画面に遷移した」と言える状態になります。
この待機条件は、サイト改修の影響を受けるのでメンテナンスが必要です。私は待機条件だけを抜き出したファイル（waits.yaml のようなもの）を別に管理して、タスクのプロンプトから参照する構成にしています。こうしておくと、サイト改修時に直すべき場所がわかりやすく、レビューも楽になります。
リトライは「賢く」回す
どれだけ丁寧に書いても、ブラウザエージェントのタスクはゼロフレーキーにはなりません。ここで必要なのは、リトライを前提とした運用です。ただし、盲目的にリトライすると被害が広がるので、冪等性とセットで設計します。
私が運用しているルールは以下の通りです。
- リトライ対象は「副作用を伴わない、または冪等な」ステップだけに限定する
- 副作用を伴うステップ（決済・フォーム送信・メール送信）は、1 回の試行で失敗したら必ず人間に通知してから再試行する
- リトライの間隔は指数バックオフにする（1 秒 → 3 秒 → 10 秒）
- 連続 3 回の失敗で、その日のそのタスクは再試行をやめる
最後のルールは、見落とされがちですが重要です。相手サイトが一時的に壊れているとき、機械的にリトライを続けると IP を Bot 判定されてしまいます。3 回失敗したら撤退するルールは、運用側の健全さを守るためのものです。
プロンプトと再現性のスナップショット
フレーキーに向き合ううえで、もう 1 つ仕込んでおきたいのが「プロンプトと結果のスナップショット」です。Antigravity にブラウザエージェントを動かしてもらうとき、同じプロンプトでも日によって挙動が変わります。それ自体は生成モデルの性質なので避けられませんが、どのプロンプトで・どのモデルで・何を入力したかを毎回残すだけで、トラブル時の再現調査が劇的に楽になります。
私は次の 4 点をすべて、実行ごとに 1 レコードで保存しています。
- プロンプトの全文（テンプレートではなく、実際に送った最終版）
- 使ったモデルとバージョン
- 入力となった画面の URL と、主要要素のアウトライン（見出しタグや主要な button/input の text）
- 成功／失敗の判定と、失敗時のスクリーンショット・HTML ダンプ
これを残していると、1 週間後に「なぜ突然この処理が落ち始めたか」を調査するときに、仮説を 2 つか 3 つに素早く絞り込めるようになります。逆に、これを残していない状態で落ちると、同じプロンプトで再実行してもう一度失敗が出るのを祈るしかなく、時間が湯水のように消えていきます。
観測できないものは、壊れても気付けない
最後に、これはブラウザエージェントに限らない話ですが、観測をケチらないことを強く勧めたいです。具体的には以下のメトリクスを、タスクごとに日次の時系列で持っておきます。
- 成功率（成功 / 試行回数）
- 1 実行あたりの平均ステップ数
- 1 実行あたりの平均所要時間
- 失敗時の原因分布（セレクタ不一致・待機タイムアウト・HTTP エラー・その他）
これらをグラフにしておくと、「最近フレーキーが増えているな」と数値で気付けます。感覚だと、ユーザーから報告が来るまで気付かず、気付いたときには「実は 2 週間前から悪化していた」ということが起こります。個人開発でも、ログの自動集計と簡易ダッシュボードを 1 日だけかけて整備する価値は十分あります。
壊れない前提ではなく、壊れても痛くない前提で組む
Antigravity のブラウザエージェントは、使いこなすと生活の面倒ごとを静かに肩代わりしてくれる強力な相棒です。ただ、相手は自分の都合で変化し続けるウェブです。壊れない前提で組んだ瞬間に、こちらが消耗する運用になります。
私が個人でも業務の手伝いでも徹底しているのは、「壊れても痛くない」前提でタスクを設計するという一点に尽きます。DOM 変化は必ず来るものとして意味論的アンカーを書く、非同期ロードは状態で待つ、リトライは副作用と冪等性で分ける、そして何が起きたかを必ずスナップショットに残す。これらをセットで仕込んでおけば、フレーキーを「あるもの」として淡々と吸収できる運用に近づきます。
今ブラウザエージェントで痛い目を見ている方は、まず失敗時に何を残しているかを棚卸ししてみてください。原因分布が見えるだけで、次に手を入れるべき場所の優先順位は自然と決まります。