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行以内のモジュール分割と一括実行用スクリプトで解決する手順を解説します。
わたしもまさにこのエラーに直面しました！『3 files changed +991 -35』まで進んであと少しで完了という瞬間に突然ブツッと切れてしまい、再試行ボタンを押しても新しいチャットでやり直しても同じ場所で止まるので本当に焦りましたが、原因が『1ステップあたりの出力行数』にあると分かってからは一度も起きなくなりました！
この記事でできるようになること｜Antigravityの「Deadline exceeded」を根絶する3つのゴール
まずはエラーが発生する裏側のメカニズムと、それを突破するための全体像を1枚の図解と3つの基本用語で整理します。
そもそも「Deadline exceeded」や「モノリシック出力」とは？3つの重要用語を30秒で整理
原因分析と具体的な解決手順へ進む前に、本記事で登場する3つの技術キーワードが「一言でいうと何なのか」を平易な言葉で確認しておきます。
Deadline exceededとは、AIエージェントが1つのアクション（ファイルの書き出しやコマンド実行など）を開始してから完了するまでの「1ステップあたりの制限時間（締め切り時間）を超過して強制終了した状態」のことです。
通信規格（gRPC）のエラーコード「DEADLINE_EXCEEDED」に由来しており、AIが1回のツール呼び出しの中で長すぎるコード文字列を生成し続けた際によく発生します。
モノリシック出力とは、複数の画面テンプレートやデータ定義、実行ロジックを「たった1つの巨大なファイル（1,000行〜2,000行超）に丸ごと詰め込んで、1回のファイル作成ツールで一気に出力させるやり方」のことです。
AIが1文字ずつコードを紡ぎ出すのに数分間かかり続けるため、途中で制限時間（Deadline）の壁に激突してすべてが水泡に帰す最大の原因になります。
モジュール分割とは、大きなプログラムを「1ファイルあたり300〜450行以内の小さな部品ファイル（モジュール）」に分けて順番に保存し、最後に一括実行用の親スクリプトで読み込んで動かす設計手法のことです。
1ファイルあたりのAI出力時間がわずか約2秒に短縮されるため、制限時間エラーが物理的に起こらなくなります。
【1. 作業環境〜4. 原因分析】なぜ「3 files changed +991」の直後に強制終了したのか？
実際にエラーが発生したときの作業環境から、事象の検知、Web上の先行情報調査、そして真の原因を特定するまでのプロセスを順番に振り返ります。
- 【項目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：事象の検知】「3 files changed +991 -35」まで進んだ直後に赤文字で強制停止
3つ分の大型HTMLテンプレートと統合検証処理を1本のPythonスクリプトへ一気に書き出させていた最中、画面下部の変更行数が3 files changed +991 -35に達したところでピタッと停止。赤い三角アイコンとともにError Deadline exceeded: Agent execution terminated due to error.が表示されてエージェントが強制終了。 - 【項目3：調査】Google検索の「AIによる概要」や先行ブログ・note記事を調査
エラー文面で検索しても、Googleの「AIによる概要」には「無限ループの解消」「外部APIの応答待ち」「クラウド環境のTimeout設定延長」といった一般的なクラウド開発の抽象回答のみ表示。既存の解説記事やnote記事も「しばらく時間を置く・キャッシュを消す」といった応急処置や「過去バージョンの画像添付リトライ不具合」の話題にとどまり、今回のケースに当てはめて再実行しても解決せず。 - 【項目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 定義より要旨整理）
ステータスコード
出典：gRPC Official Documentation - Status Codes (DEADLINE_EXCEEDED)DEADLINE_EXCEEDED (4)は、操作が完了する前に期限（Deadline）が切れたことを示します。サーバー側で処理が進行中であっても、単一リクエストの完了までに要する時間が制限値を超えると即座に切断されます。
つまり、AIがサボっていたわけでもサーバーが壊れていたわけでもなく、『1回のファイル保存コマンドで原稿用紙300枚分のコードをノンストップで書き続けようとして、1ターンあたりの持ち時間（制限時間）を超えてしまった』というのが真相だったんです。これなら、もう一度同じプロンプトを送っても同じ場所で時間切れになるわけですよね！
【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行のモジュール分割 ＋ 一括実行用の親スクリプト』を選択しました。
『エラーが出ない代わりにコードや文章の密度を削る』という妥協は絶対にしたくなかったので、品質は1ミリも落とさずに1回の出力単位だけを450行以内に分割するパターン③を選んだのが最大のブレイクスルーでした！
AIコーディング環境で巨大ファイル出力によるエラーや手戻りを防ぎ、人間と生成AIが協調して保守性の高いモジュール構造を組み立てるための実践ノウハウが体系的にまとまった一冊です。
自律型AIエージェントが内部でどのようにツールを呼び出し、なぜ単一ステップの制限時間（タイムアウト）が発生するのかという基礎構造から、安定した分割実行パイプラインの設計まで詳しく学べます。
【9. 実行〜10. 結果確認】約1,800行を4ファイルへ分割し、約20秒で完走した実践手順
選択した「パターン③」に基づき、実際にモノリシックな巨大スクリプトを4つの独立モジュールへ分割して統合実行したステップと、その実測結果（ビフォーアフター）を解説します。
- 【項目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を実行。 - 【項目9-②：実行（親スクリプトからの1コマンド統合ビルド）】
4つのファイルが揃った直後、一括実行用の親スクリプトをターミナルから1コマンドで起動。親スクリプト内部でのThreadPoolExecutor並列処理とHTTP Keep-Aliveセッション再利用により、全モジュールの結合・構文チェック・API送信を一気通貫で処理。 - 【項目10：結果確認】エラー発生0件・各ファイル約2秒・全体ビルド19.85秒で完走！
分割前は3分以上かかった挙げ句にDeadline exceededで強制終了していた処理が、分割後は各ファイルの書き出し約1.8〜2.1秒（4ファイル合計約8秒）、親スクリプト実行19.85秒（タイムアウト0件・一発合格）という大幅な改善を達成。
以前公開した「Excelマクロが突然動かない悲劇を根絶！ブラウザ自動操作ツール「Playwright」への段階移行で止まらない定型業務を作る実践手順」や「複雑なWeb API認証エラーで徹夜しない！Postman段階切り分けからPython自動取得スクリプト化までの最短突破法」でも、大きな自動化処理ほど『小さく切り分けて段階的に繋ぐ』ことの大切さを実感しましたが、AIエージェントにコードを書かせるときもまったく同じなんですね！1ファイル450行以内にするだけで、こんなにもサクサク動くようになるとは感動でした。
【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』へこの2行を書いておくだけで、毎回プロンプトで細かく注意しなくてもエージェントが最初から自動で400行ずつのモジュールに分けてくれるようになります。まさに『作業前にやっておくと一番嬉しい予防策』ですね！
生成AIが出力したコードの良し悪しを正しく見極め、実務レベルのモジュール分割設計や非同期処理・エラーハンドリングを自力で組み立てられる開発基礎力を身につけたい方に適した実践型トレーニング講座です。
AIエージェントへのプロンプト指示や定型コマンド呼び出しをキーマップに割り当てられるプログラマブル設計のテンキーレスメカニカルキーボードです。長時間の開発でも指への負担が少なく快適に作業できます。
まとめ｜今日からできる「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行以内・大型処理はモジュール分割＋非同期オーバーラップ」を明記しておく
夜中に1,800行の生成が『+991行』で止まったときは『また最初からやり直しか…』と頭を抱えましたが、400行ずつのモジュールに分けた途端、パチパチッと2秒ずつファイルが生まれて20秒で全部終わったときは本当にスカッとしました！ぜひ今日、お手元のGEMINI.mdに『1ファイル450行以内』のルールを1行足してみてください。驚くほど開発が止まらなくなるはずです！
あわせて、Pythonによるブラウザ自動操作の段階的移行手順や、Web API自動化スクリプトの切り分け術を解説した以下の記事もぜひご覧ください。
Pythonブラウザ自動操作を安定・高速化するための段階的移行手順と実測ノウハウを詳しく解説しています。
外部API・Web自動連携のエラー切り分けと堅牢なバッチ設計のポイントをわかりやすくまとめています。
