Gemini APIで数十分かかるリサーチタスクやコード実行を投げると、素朴なリクエストではまず間違いなくタイムアウトする。通常のHTTP接続は長くても数十秒でクローズされるため、「リポジトリを丸ごと解析してTODOを一覧化して」のような重いタスクは接続が切れた時点で結果が失われる。実際にantigravity-preview-05-2026エージェントへ数分かかるコード実行タスクを投げて検証したところ、同期呼び出しのままだとクライアント側のタイムアウト設定に処理時間が振り回されることを確認した。
この問題への公式の答えが、Interactions APIのbackgroundパラメータだ。"background": trueを渡すだけで、サーバー側に処理を投げっぱなしにしてIDだけを即座に受け取り、あとはポーリングかストリーミングで結果を回収する設計に切り替わる。2026年7月7日にGoogleが公開した機能拡張の発表では、この仕組みが「リポジトリをクローンしてコードベースを解析しTODOコメントを洗い出す」「オブザーバビリティデータとgitコミットを突き合わせてパフォーマンス問題を調査する」といった、まさに長時間かかるユースケースのために用意されたと説明されている。
この記事では、公式ドキュメント（Background Execution）とManaged Agents Quickstart、Antigravity Agentの3ページで確認できる仕様だけを根拠に、セットアップから最小コード、長時間タスクの投げ方、ポーリング・再接続、エラー処理、料金と制約、実運用の勘所までを実装順に解説する。Gemini SparkのようなAntigravity基盤そのものの設計思想を知りたい場合は、別記事「Gemini Sparkのアーキテクチャを開発者視点で読み解く」でアーキテクチャ面を扱っているので、そちらを先に読むと全体像がつかみやすい。本記事はアーキテクチャ論には立ち入らず、手を動かして動くコードを書くことだけに集中する。
結論：background=Trueで何が変わるか
先に要点を並べる。
- 挙動：
background=Trueを渡すと、サーバー側で非同期実行され、APIは即座にinteraction IDを返す。クライアントは接続を維持し続ける必要がなくなる。 - 対応モデル・エージェント：標準のGeminiモデル（
gemini-3.6-flash、gemini-3.1-pro-previewなど）に加え、Managed Agentsのantigravity-preview-05-2026やdeep-research-preview-04-2026でも利用できる。 - 回収方法：ポーリング（
interactions.get）、ストリーミング、切断後のlast_event_idによる再接続の3通りが用意されている。 - 状態遷移：
in_progress→completed/failed/cancelled、入力待ちの場合はrequires_actionを経由する。 - 必須条件：background実行には
store=True（既定値）が必要。store=Falseにするとprevious_interaction_idもbackground実行も使えなくなる。
対象読者：Gemini APIで数分〜数十分かかるエージェントタスクを本番アプリに組み込みたい開発者。
今日やること：後述の最小コードを1本動かし、background=TrueのレスポンスがIDだけ返ってくる挙動を自分の目で確認する。
セットアップ——SDKとAPIキー
Python SDKはgoogle-genaiパッケージを使う。公式ドキュメントのコード例はいずれも次の形でクライアントを初期化している。
# 動作環境: Python 3.10+
pip install --upgrade google-genai
# APIキーを環境変数に設定（Google AI Studioで発行）
export GEMINI_API_KEY="あなたのAPIキー"from google import genai
# 環境変数 GEMINI_API_KEY を自動で読み込む
client = genai.Client()注意：本番環境で使用する前に、必ずテスト環境で動作確認してください。APIキーはコードに直接書かず、環境変数かシークレットマネージャーで管理する。
最小コードでInteractions APIを動かす
まずbackgroundを使わない同期呼び出しで、Managed Agentsの基本形を確認する。agentにエージェントID、environmentに"remote"を渡すと、Google側がフレッシュなLinuxサンドボックスを用意してエージェントを起動する。
from google import genai
client = genai.Client()
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
environment="remote",
)
print(interaction.output_text)この呼び出しはタスクが完了するまでブロックする。動作環境はUbuntu上のLinuxサンドボックスで、Python 3.12とNode.js 22があらかじめ用意され、4 CPUコア・16GBメモリというスペックが公式ドキュメントに明記されている。Hacker Newsの要約程度なら数十秒で終わるが、リポジトリ全体の静的解析やデータ処理をやらせると、この同期呼び出しのままタイムアウトに引っかかる。ここでようやくbackgroundの出番になる。
長時間タスクをbackground=Trueで投げる
標準モデル向けのBackground Executionドキュメントでは、次のようにモデルを直接指定して非同期実行を開始する例が示されている。
interaction = client.interactions.create(
model="gemini-3.6-flash",
input="Write a guide on space exploration.",
background=True,
)Managed Agentsでも同じbackgroundパラメータが使える。公式の機能拡張発表は「Managed Agentsでのbackground実行」を明確にサポート対象として挙げており、対応エージェントとしてantigravity-preview-05-2026を名指ししている。両ページの仕様を組み合わせると、実装上はエージェント呼び出しにbackground=Trueを足すだけでよい。
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="GitHubリポジトリをクローンして、TODOコメントをすべて洗い出しMarkdownの一覧表にまとめて",
environment="remote",
background=True,
)
print(f"Interaction ID: {interaction.id}")
print(f"Status: {interaction.status}") # in_progressこの呼び出しはほぼ即座に返る。output_textはまだ空で、代わりにidとin_progressステータスが手に入る。ここから先はポーリングかストリーミングで結果を回収する。
ポーリングで結果を待ち受ける
もっとも単純な回収方法は、一定間隔でinteractions.getを叩いてステータスを確認するポーリングだ。公式ドキュメントのPython例は次の形になっている。
import time
while interaction.status == "in_progress":
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
if interaction.status == "completed":
print(interaction.output_text)
elif interaction.status == "failed":
print("Failed:", interaction.error)JavaScript版ではsetIntervalを使った同等のパターンが紹介されている（Interactions API開発者ガイド、2026年6月23日公開）。
const poll = setInterval(async () => {
const result = await ai.interactions.get(interaction.id);
if (result.status === "completed") {
console.log(result.output_text);
clearInterval(poll);
} else if (result.status === "failed") {
console.error("Failed:", result.error);
clearInterval(poll);
}
}, 5000);状態はin_progress（サーバー実行中）、requires_action（クライアント入力待ち）、completed（正常終了）、failed（エラー終了）、cancelled（クライアントが中断）の5つを遷移する。ポーリング間隔は公式に固定値の指定はないため、タスクの想定所要時間に応じて調整するのが妥当だ。数秒で終わるタスクを5秒間隔でポーリングするとリクエスト回数だけ無駄に増えるので、後述のストリーミングと使い分けるとよい。
ストリーミングと切断後の再接続
進捗をリアルタイムに見たい場合はstream=Trueを使う。Managed Agents Quickstartのサンプルでは、ツール呼び出しやコード実行のステップが逐次イベントとして流れてくる。
stream = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Read Hacker News, summarize the top 10 stories, and save the results as a PDF.",
environment="remote",
stream=True,
)
for event in stream:
print(event)
if event.event_type == "step.stop" and event.usage:
print(event.usage)Wi-Fiが切れる、モバイル回線が不安定になるなどでストリームが途中で切断されても、background実行なら処理自体はサーバー側で継続している。Background Executionドキュメントは、切断されたストリームへlast_event_idを指定して再接続する方法を明記している。
stream = client.interactions.get(
id=interaction_id,
stream=True,
last_event_id=last_event_id,
)直前に受信できていた最後のイベントIDを保存しておけば、そこから続きのイベントだけを受け取れる。長時間タスクをモバイルクライアントやサーバーレス関数から呼ぶ場合、この再接続パターンを実装しておかないと、接続が切れるたびに最初から結果を取りに行く羽目になる。
マルチターンでの継続——previous_interaction_idとenvironment_id
1回のタスクで終わらず、結果を見てから追加の指示を出したい場合はprevious_interaction_idで会話履歴を引き継ぐ。さらに同じenvironment_idを渡すと、サンドボックス内のファイルやインストール済みパッケージも維持される。
interaction_2 = client.interactions.create(
agent="antigravity-preview-05-2026",
previous_interaction_id=interaction.id,
environment=interaction.environment_id,
input="さっき集計したデータを折れ線グラフにして保存して",
background=True,
)ここで必ず押さえておくべき制約が1つある。直前のinteractionがcompleted状態に到達する前に、それをチェーンした新しいinteractionを作ろうとすると400 Bad Requestが返る（Background Executionドキュメント明記）。background実行中のタスクに対して「続きの指示」を投げたくなる場面は多いが、まずポーリングかrequires_action状態を確認してからチェーンする必要がある。
エラー・タイムアウト処理
background実行のエラーハンドリングで押さえるべきポイントは3つある。
1. failed状態のerrorプロパティを必ず見る
タスクが失敗するとstatusがfailedになり、errorプロパティにデバッグ用の情報が入る。ポーリングループの中でcompletedだけでなくfailedも明示的に分岐させる（上記のコード例参照）。
2. トークン予算超過はincompleteとして返る
Antigravityエージェントのドキュメントによると、agent_config内にmax_total_tokensを設定すると、入力・出力・thinkingの合計トークンがその上限に達した時点でstatus: "incomplete"としてinteractionが返る。エラーで落ちるのではなく、それまでのエージェントの文脈と作業内容を保持したまま返却されるため、previous_interaction_idで新しいトークン予算を設定して続きから再開できる。ただし「エージェントがステップ間で予算をチェックするタイミング」に依存するため、実際の消費量が上限をわずかに超える場合があると明記されている。
3. 429・5xxはSDKの自動リトライに任せつつ、レート制限は自分でも見ておく
公式SDKにはタイムアウト・ネットワークエラー・429/5xxエラーに対する指数バックオフ付きの自動リトライがデフォルトで組み込まれている（Troubleshooting guide）。レート制限はAPIキー単位ではなくプロジェクト単位で適用され、モデルごとに上限が異なる（Rate limits）。background実行でポーリングの頻度を上げすぎると、この上限に別枠で引っかかる可能性があるため、ポーリング専用のリトライ・バックオフ処理を別途入れておくと安全だ。
料金と制約——公開情報の範囲で
Managed Agents（antigravity-preview-05-2026など）には専用の課金体系はなく、内部で使われているGeminiモデルのトークン単価とツール利用量に応じた従量課金になる。公式ドキュメントで確認できる目安は次のとおり。
| 項目 | 内容 |
|---|---|
| 課金モデル | 従量課金（基盤モデルのトークン単価＋ツール利用量ベース） |
| 典型的なトークン消費 | リサーチ・要約系タスクで入力10万〜50万トークン、複雑なデータ処理タスクで300万〜500万トークンに達する場合がある |
| 目安コスト | タスクの複雑さに応じて1回あたり$0.25〜$3.25以上 |
| キャッシュトークン | 課金対象外 |
| コンピュート（CPU/メモリ） | プレビュー期間中は課金されない |
| 無料枠 | クォータとレート制限つきで用意されている |
（出典：Antigravity Agent公式ドキュメント、参照日2026-07-30。プレビュー期間中の無償項目は正式リリース時に変更される可能性がある）
あわせて把握しておきたい制約は次のとおり。
- background実行にはstore=True（既定）が必須。Interactions APIはデフォルトで会話を保存するが（有料ティアで55日間、無料ティアで1日間）、
store=Falseにするとbackground実行とprevious_interaction_idの両方が使えなくなる。 - Antigravityエージェントでは
temperature・top_p・top_k・stop_sequences・max_output_tokensは非対応。構造化出力も未対応。 file_search・computer_use・google_mapsツールは利用不可。入力はテキストと画像のみで、音声・動画・ドキュメント入力は非対応。- Function callingを使う場合は
previous_interaction_idによるステートフルモードが前提になる。
実運用Tips
- 環境を使い捨てにしない：毎回
environment="remote"で新規サンドボックスを作ると、pip installやファイル準備が毎回走ってコストと時間の両方が増える。同じタスク系列を扱うならenvironment_idを再利用してファイル・パッケージの状態を持ち回す。 - コスト予算を先に決めてmax_total_tokensを設定する：background実行は放置しても動き続けるため、上限を設定しないと想定外のトークン消費に気づきにくい。
- 不要になったinteractionは明示的にcancel/deleteする：
client.interactions.cancel(id=...)で状態をcancelledに、client.interactions.delete(id=...)でレコード自体を削除できる（削除後に取得しようとすると404 Not Found）。長時間タスクを試行錯誤する開発中は、放置せずに片付ける習慣をつけておくとダッシュボードの見通しがよくなる。 - Remote MCPサーバーと組み合わせる：2026年7月7日の機能拡張で、Managed Agentsからカスタムプロキシを自作せずにリモートMCPサーバーへ直接接続できるようになった。社内DBや内部APIにアクセスさせたい長時間タスクでは、この経路を検討する価値がある。実装の詳細な比較は「AIエージェントツール完全比較12選」でMCP対応状況も含めて整理している。
【要注意】よくある失敗パターンと回避策
失敗1：in_progress中のinteractionにチェーンして400エラー
❌ background実行を投げた直後に、そのIDをprevious_interaction_idにして次の指示を送る。
⭕ ポーリングかストリーミングでcompletedを確認してから次のinteractionを作る。
なぜ重要か：Background Executionドキュメントに明記された仕様上の制約であり、リトライしても状態が変わるまで同じエラーが返り続ける。
失敗2：store=Falseにしたままbackground実行を試みる
❌ プライバシー配慮のつもりでstore=Falseを設定し、そのままbackground=Trueも一緒に渡す。
⭕ background実行やprevious_interaction_idを使う経路ではstore=True（既定値のまま）にし、代わりに不要になった時点で明示的にdeleteする運用にする。
なぜ重要か：この2つの設定は仕様上両立しない組み合わせで、意図せず片方を潰すとbackground実行そのものが機能しなくなる。
失敗3：ポーリング間隔を固定5秒のまま数十分タスクに使い続ける
❌ どんなタスクでも例のコードそのまま5秒間隔でポーリングし続ける。
⭕ 想定所要時間が長いタスクは間隔を指数的に伸ばす（5秒→10秒→30秒…）か、ストリーミング＋再接続に切り替える。
なぜ重要か：プロジェクト単位のレート制限は別枠で存在するため、無意味な高頻度ポーリングはクォータを消費するだけでなく、本来の推論リクエストの制限にも影響しうる。
失敗4：トークン予算を設定せず長時間タスクを本番投入する
❌ max_total_tokensを設定せずに、複雑なデータ処理タスクをbackgroundでいきなり本番投入する。
⭕ 開発段階で典型的なトークン消費量（数十万〜数百万トークン）を計測し、agent_configに予算を設定してから本番に出す。
なぜ重要か：Antigravityエージェントは自律的に複数ステップのツール実行を繰り返すため、意図しない長いループに入ると消費トークンが青天井になりうる。
よくある質問
Q. background=Trueとstream=Trueは同時に使えますか？
A. 公式ドキュメントでは、background実行はポーリング・ストリーミング・切断後の再接続という3つの回収方法を前提にした設計として説明されており、background=Trueで作成したinteractionに対して後からstream=Trueで再接続してリアルタイムの進捗を見ることができる。作成時にbackgroundとstreamを同時に指定した場合の挙動まで明示した一次情報はこの記事の調査範囲では確認できなかったため、まずは作成時はbackground=Trueのみで投げ、必要ならinteractions.get(id=..., stream=True)で接続する構成を推奨する。
Q. background実行のタイムアウト上限はどれくらいですか？
A. 公式ドキュメントに具体的な最大実行時間の数値は明記されていない。ドキュメントが強調しているのは「通常のHTTP接続が数十秒でクローズされる」問題をサーバー側非同期実行で回避する設計思想であり、時間ではなくポーリング・再接続で結果を回収する運用に切り替えることが前提になっている。長時間タスクではmax_total_tokensで予算上限を設定し、時間ではなくトークン消費で制御するのが公式ドキュメントに沿ったアプローチだ。
Q. antigravity-preview-05-2026以外のエージェントでもbackgroundは使えますか？
A. 公式の機能拡張発表ではantigravity-preview-05-2026に加えてdeep-research-preview-04-2026もbackground実行のサポート対象として挙げられている。標準のGeminiモデル（gemini-3.6-flash、gemini-3.1-pro-previewなど）でも同じbackgroundパラメータが使える。
Q. Interactions APIは無料で試せますか？
A. 無料ティアが用意されており、クォータとレート制限つきで利用できる。ただしデータ保存期間は有料ティアの55日間に対して無料ティアは1日間と短く、Antigravityエージェントのコンピュート費用はプレビュー期間中は課金されないとドキュメントに明記されている。正式な料金上限や上限額は公式の料金ページで最新情報を確認してほしい。
Q. previous_interaction_idだけ渡してenvironment_idを省略するとどうなりますか？
A. 公式ドキュメントは、previous_interaction_idが会話履歴（入力と出力）の継続を担い、environment_idがサンドボックス環境（ファイルやインストール済みパッケージの状態）の継続を担う、と役割を分けて説明している。会話の文脈だけ引き継いでサンドボックスは作り直したい場合はenvironment_idを省略し、ファイル状態も含めて完全に続きから作業させたい場合は両方を渡す、という使い分けになる。
参考・出典
- Background execution | Gemini API — Google AI for Developers（参照日: 2026-07-30）
- Managed Agents Quickstart | Gemini API — Google AI for Developers（参照日: 2026-07-30）
- Antigravity Agent | Gemini API — Google AI for Developers（参照日: 2026-07-30）
- Interactions API Overview | Gemini API — Google AI for Developers（参照日: 2026-07-30）
- Rate limits | Gemini API — Google AI for Developers（参照日: 2026-07-30）
- Troubleshooting guide | Gemini API — Google AI for Developers（参照日: 2026-07-30）
- Expanding Managed Agents in Gemini API: background tasks, remote MCP and more — Google公式ブログ（2026年7月7日、参照日: 2026-07-30）
- Getting started with the Gemini Interactions API — Philipp Schmid（2026年6月23日、参照日: 2026-07-30）
まとめ：今日から始める3つのアクション
- 今日やること：
pip install --upgrade google-genaiを実行し、本記事の最小コードでbackground=TrueのレスポンスがIDだけ返ってくる挙動を確認する。 - 今週中：自分のユースケースでポーリングとストリーミング＋再接続のどちらが適しているかを判断し、
failed状態のハンドリングとmax_total_tokensの予算設定を組み込む。 - 今月中：
environment_idの再利用とRemote MCPサーバー連携を検証し、長時間タスクを本番のワークフロー（バッチ処理・夜間ジョブなど）に組み込む。
あわせて読みたい:
- Gemini Sparkのアーキテクチャを開発者視点で読み解く — 同じAntigravity基盤の設計思想を、消費者向け製品Gemini Sparkの外形から分解した記事
- Gemini CLI終了とAntigravity CLI移行ガイド — CLI版Antigravityへの移行手順
- Claude Agent SDK｜長時間稼働エージェント — 別ベンダーでの長時間タスク設計との比較
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』。
この記事を読んで導入イメージが固まってきた方へ
UravationではAIエージェント導入の研修・コンサルを行っています。長時間タスクを含むエージェント設計の実装支援も可能です。
