Google Antigravityで「Deadline exceeded: Agent execution terminated due to error.」が出た時の根本解決！単一ステップ巨大ファイル出力の罠とモジュール分割・非同期化の実測対策

Google Antigravityで複数のPythonスクリプトやHTMLを一気に生成させていると、突然「Deadline exceeded: Agent execution terminated due to error.」と出て止まることがあります。

原因は通信不調ではなく「1回のファイル出力に1,000行超を詰め込んだことによる制限時間超過」です。今回は、1ファイル450行以内のモジュール分割と一括実行用スクリプトで解決する手順を解説します。

この記事でできるようになること｜Antigravityの「Deadline exceeded」を根絶する3つのゴール

まずはエラーが発生する裏側のメカニズムと、それを突破するための全体像を1枚の図解と3つの基本用語で整理します。

 

そもそも「Deadline exceeded」や「モノリシック出力」とは？3つの重要用語を30秒で整理

原因分析と具体的な解決手順へ進む前に、本記事で登場する3つの技術キーワードが「一言でいうと何なのか」を平易な言葉で確認しておきます。

【1. 作業環境〜4. 原因分析】なぜ「3 files changed +991」の直後に強制終了したのか？

実際にエラーが発生したときの作業環境から、事象の検知、Web上の先行情報調査、そして真の原因を特定するまでのプロセスを順番に振り返ります。

1. 【項目1：今回の作業環境】Windows 11 ＋ Google Antigravity IDE（2026年10月時点）＋ 親AI・子AI・Python環境
   OSはWindows 11、開発環境はGoogle Antigravity IDEを使用。メインの設計・コード生成に親AI（司令塔となる上位推論モデル）、画像や補助調査に子AI（軽量なサブエージェント）、ローカル検証にPython 3.12の仮想環境（.venv）を組み合わせ、複数のHTMLレポートと一括検証バッチを構築。
2. 【項目2：事象の検知】「3 files changed +991 -35」まで進んだ直後に赤文字で強制停止
   3つ分の大型HTMLテンプレートと統合検証処理を1本のPythonスクリプトへ一気に書き出させていた最中、画面下部の変更行数が 3 files changed +991 -35 に達したところでピタッと停止。赤い三角アイコンとともに Error Deadline exceeded: Agent execution terminated due to error. が表示されてエージェントが強制終了。
3. 【項目3：調査】Google検索の「AIによる概要」や先行ブログ・note記事を調査
   エラー文面で検索しても、Googleの「AIによる概要」には「無限ループの解消」「外部APIの応答待ち」「クラウド環境のTimeout設定延長」といった一般的なクラウド開発の抽象回答のみ表示。既存の解説記事やnote記事も「しばらく時間を置く・キャッシュを消す」といった応急処置や「過去バージョンの画像添付リトライ不具合」の話題にとどまり、今回のケースに当てはめて再実行しても解決せず。
4. 【項目4：分析】真の原因は「1回の write_to_file ツールコールへの1,800行・120KB超の詰め込み」
   実行ログ（transcript.jsonl）のステップ時間を秒単位で解剖した結果、エラー箇所は無限ループではなく、1回の write_to_file ツール呼び出し引数（CodeContent）に約1,800行（120KB超）のコードを単一ストリームで出力し続けたことによる、1ステップあたりの制限時間（Deadline）超過と通信強制切断が真因と判明。

GoogleのRPC（リモートプロシージャコール）設計ガイドラインでも、DEADLINE_EXCEEDED は「処理自体が正常に進んでいても、設定された締め切り時間内に1回のリクエストが完了しなかった場合に発生する」と明確に定義されています。

📖 一次技術仕様の要点（Google Cloud gRPC Status Code 定義より要旨整理）

ステータスコード DEADLINE_EXCEEDED (4) は、操作が完了する前に期限（Deadline）が切れたことを示します。サーバー側で処理が進行中であっても、単一リクエストの完了までに要する時間が制限値を超えると即座に切断されます。

出典：gRPC Official Documentation - Status Codes (DEADLINE_EXCEEDED)

【5. 現状〜8. 対策案の選択】品質を一切落とさずタイムアウトを0件にする3パターン実測比較

原因が「1回のツール呼び出しあたりの出力サイズ過大」にあると特定できたところで、現状の課題整理から3つの対策案の立案・比較、そして最適案の選択を行いました。なお、「普段100〜200行程度の短いスクリプト修正しか行わず、一度もDeadline exceededが出たことがない方」は、無理にファイルを分割する必要はありません。

• 【項目5：現状の課題（モノリシックな1ファイル出力）】
  3つ分の大型データ定義（各450行×3＝1,350行）と統合実行ロジック（約450行）の計1,800行を1つのPythonファイルにまとめて出力させていたため、1ステップの生成時間が制限時間を突破してクラッシュ。
• 【項目6：対策立案（3つのアプローチ）】
  この壁を突破するため、「パターン①：そのまま再実行・会話リセット」「パターン②：出力するコードや文章を削って短くする」「パターン③：1ファイル300〜450行のモジュール分割＋一括実行用の親スクリプト」の3案を立案して実測比較。

【項目7：対策案の比較】 実際に3つのパターンを試した際の3パターン4列実測比較表（所要時間・エラー発生率・品質維持・トークン効率）は以下の通りです。

【項目8：対策案の選択】 比較の結果、スピードやエラー回避のためだけに成果物の密度を落とす「パターン②」は却下し、「品質最優先」と「タイムアウト完全根絶」を両立できる『パターン③：1ファイル300〜450行のモジュール分割 ＋ 一括実行用の親スクリプト』を選択しました。

【9. 実行〜10. 結果確認】約1,800行を4ファイルへ分割し、約20秒で完走した実践手順

選択した「パターン③」に基づき、実際にモノリシックな巨大スクリプトを4つの独立モジュールへ分割して統合実行したステップと、その実測結果（ビフォーアフター）を解説します。

1. 【項目9-①：実行（サブモジュールへの4分割書き出し）】
   これまで1ファイルに詰め込んでいた約1,800行のコードを、① module_part1.py（約320行：共通部品＋第1モジュール）、② module_part2.py（約410行：第2モジュール）、③ module_part3.py（約380行：第3モジュール）、④ run_all.py（約290行：一括実行用の親スクリプト）の4ファイルへ分割し、順番に write_to_file を実行。
2. 【項目9-②：実行（親スクリプトからの1コマンド統合ビルド）】
   4つのファイルが揃った直後、一括実行用の親スクリプトをターミナルから1コマンドで起動。親スクリプト内部での ThreadPoolExecutor 並列処理とHTTP Keep-Aliveセッション再利用により、全モジュールの結合・構文チェック・API送信を一気通貫で処理。
3. 【項目10：結果確認】エラー発生0件・各ファイル約2秒・全体ビルド19.85秒で完走！
   分割前は3分以上かかった挙げ句に Deadline exceeded で強制終了していた処理が、分割後は各ファイルの書き出し約1.8〜2.1秒（4ファイル合計約8秒）、親スクリプト実行19.85秒（タイムアウト0件・一発合格）という大幅な改善を達成。

【11. 次回に向けた取り組み＆学び】作業前に「GEMINI.md」へ仕込む出力上限ルール

最後に、今回得られた大きな学びである「毎回プロンプトで細かく指示しなくても、エージェントが最初から自律的に450行以内でモジュール分割してくれる仕組み（作業前にやると嬉しいこと）」をご紹介します。

• ① ワークスペース直下の「GEMINI.md」に『単一ステップ出力上限ガード（450行ルール）』を明記しておく
  チャット開始のたびに「ファイルを分けて出力して」と人間が入力する手間や、指定忘れによる Deadline exceeded の再発を防止。プロジェクト直下の GEMINI.md（カスタムルールファイル）に「1回の write_to_file は最大450行以内とし、超える場合は機能別サブモジュールに分割して一括実行用の親スクリプトで結合すること」と記述することで、全セッションでの自動分割設計を定着化。
• ② 通信や画像処理などの重いI/Oは「非同期バックグラウンド実行（WaitMsBeforeAsync=500）」で後続のコード作成とオーバーラップさせる
  アップロードやテスト実行などの待ち時間（25〜35秒）をバックグラウンドタスクとして先行起動し、その裏で次のモジュールファイルを書き出す「非同期パイプライン・オーバーラップ」の併用により、全体作業時間の30%以上短縮を実現。

まとめ｜今日からできる「GEMINI.md」への出力上限ルール追加で快適開発へ

Google Antigravityで発生する Deadline exceeded: Agent execution terminated due to error. の原因と、品質を一切妥協せずに解決するモジュール分割設計を振り返りました。

• エラーの真因
  無限ループやサーバー障害ではなく、1回の write_to_file に1,000行超の巨大コードを詰め込んだことによる単一ステップの時間切れ（Deadline超過）
• 根本解決策
  1ファイルあたり300〜450行以内の機能別サブモジュールに分割して書き出し（各約2秒）、一括実行用の親スクリプトから1コマンドで統合実行する
• 再発防止の仕組み
  作業開始前にワークスペースの GEMINI.md へ「1回のファイル出力は450行以内・大型処理はモジュール分割＋非同期オーバーラップ」を明記しておく

あわせて、Pythonによるブラウザ自動操作の段階的移行手順や、Web API自動化スクリプトの切り分け術を解説した以下の記事もぜひご覧ください。