0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Gemini Managed Agentsのバックグラウンド実行で見つけた2つの罠

0
Posted at

はじめに

Gemini API の Interactions API は2026年6月に正式GA（General Availability）となり1、その約2週間後の7月7日、Managed Agents に「バックグラウンド実行」「リモートMCP統合」「カスタム関数呼び出し」「ネットワーク認証情報のリフレッシュ」という4つの新機能が追加されました2。

Managed Agents は、1回のAPI呼び出しでGoogleがホストする隔離Linuxサンドボックスを立ち上げ、その中でエージェントにコード実行・ファイル操作・Web閲覧をさせられる仕組みです。目玉の「バックグラウンド実行」を使えば、長時間タスクをHTTP接続を張ったまま待つ必要がなくなります。

この記事では、Python SDK（google-genai）で実際に Managed Agents を動かし、遭遇した2つの「ドキュメント通りに動かない」罠を、実際のエラーメッセージとともに紹介します。

この記事で学べること

  • Managed Agents の最小構成コードと、いきなり出る400エラーの正体
  • バックグラウンド実行（background=True）とポーリングの実装、SDKの引数名の罠
  • 8ステップに分解された実行トレースの中身
  • 実測したサンドボックス仕様（CPU・メモリ・ランタイム）と料金

対象読者・前提環境

Gemini API でエージェントを組んでみたい開発者、Managed Agents のプレビュー版（2026年5月）を試して離れていた人、長時間タスクを非同期API化したいバックエンドエンジニアを想定。Python 3.11 と google-genai（Interactions API対応版）、GEMINI_API_KEY 環境変数があれば手元で再現できます。

TL;DR

  • client.interactions.create() は公式サンプルのシンプルな1行呼び出しでは Missing required field 'environment' の400エラー になる。environment="remote" の明示指定が必須。
  • ポーリング用の client.interactions.get() は id= キーワード引数 を取る。interaction_id= ではない（他のAPIとの類推で間違えやすい）。
  • バックグラウンド実行は status: in_progress → completed で状態遷移し、3秒間隔のポーリング2〜3回程度で完了を検知できた（実測）。
  • サンドボックスは Ubuntu / Python 3.12 / Node.js 22 / CPU 4コア / メモリ16GBで、アイドル15分でスナップショット停止、オフライン7日で破棄される3。

Managed Agents を最小構成で動かす

まず google-genai をインストールします。

pip install google-genai

公式ドキュメント4のクイックスタートに載っているサンプルは、次のようにとてもシンプルです。

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt.",
)

このままローカルで実行すると、実際には次のエラーで落ちました。

google.genai.errors.BadRequestError: Error code: 400 -
{'error': {'message': "Missing required field 'environment'", 'code': 'invalid_request'}}

罠1: environment はサンプルコードに書かれていないが必須

environment パラメータの説明は別ページ「Environments」3に分離されており、クイックスタートのトップに出てくるサンプルコードには含まれていません。実際に動かして初めて気づく類の罠です。environment には3つの指定方法があります。

指定方法 例 用途
文字列 "remote" environment="remote" 新規サンドボックスを都度プロビジョニング
既存の環境ID environment="env_abc123" 前回のサンドボックスを再利用（ファイル・インストール済みパッケージが引き継がれる）
設定オブジェクト ネットワークルール等を含む dict サンドボックスのネットワーク制御が必要な場合

environment="remote" を足して再実行すると、正常に完了しました。

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Write a Python script that generates the first 10 Fibonacci numbers and saves them to fibonacci.txt.",
    environment="remote",
)
print(interaction.output_text)

I have successfully created and executed the Python script to generate the first 10 Fibonacci numbers.
...
0
1
1
2
3
5
8
13
21
34

interaction.steps を見ると、エージェントの動きが8ステップに分解されて記録されていました。

# type 内容
0 reasoning summary タスク内容の分析
1〜2 function_call/result (write_file) generate_fibonacci.py の書き込み
3〜4 code_execution_call/result python3 generate_fibonacci.py を実行し標準出力を取得
5〜6 function_call/result (read_file) 出力ファイルを読み直して検証
7 最終応答 ユーザーへの説明文

「実行して終わり」ではなく、書いたファイルを自分で読み返して検証するステップ（5〜6）が自律的に挟まっている点は、実際にステップを見るまで気づきませんでした。

バックグラウンド実行を試す

7月7日の拡張で追加された background=True を使うと、レスポンスを待たずに即座に interaction IDが返り、あとでポーリングして結果を取りに行けます2。

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Sleep for 5 seconds then write hello.txt containing hello world.",
    environment="remote",
    background=True,
)
print(interaction.status)  # -> in_progress

ここでポーリング用の get() を素直に interaction_id= で呼んだところ、これも失敗しました。

TypeError: GeminiNextGenInteractions.get() got an unexpected keyword argument 'interaction_id'

罠2: ポーリングの引数名は id

inspect.signature(client.interactions.get) で調べると、実際のキーワード引数は id でした。

import inspect
print(inspect.signature(client.interactions.get))
# (id: 'str', *, api_version=None, include_input=None, last_event_id=None,
#  stream=False, extra_headers=None, extra_query=None, timeout=None) -> ...

create() が返すオブジェクトの識別子は interaction.id という属性名なので、「get() にも interaction_id= を渡す」という類推は自然に起きます。実際は client.interactions.get(id=interaction.id) が正解です。

import time

got = client.interactions.get(id=interaction.id)
while got.status == "in_progress":
    time.sleep(3)
    got = client.interactions.get(id=interaction.id)

print(got.status)       # -> completed
print(got.output_text)

実測では、5秒の sleep を含むタスクに対して3秒間隔のポーリングを2〜3回（6〜9秒程度）行った時点で status が completed に変わりました。公式ドキュメントにポーリング推奨間隔の明記は見当たらなかったため、レート制限を考慮して3秒程度から様子を見るのが無難です。

マルチターンでサンドボックスは本当に維持されるか

environment_id を使い回すと、ファイルやインストール済みパッケージを引き継いだまま会話を続けられるとドキュメントにあります3。実際に、あるターンで作ったカウンターファイルを次のターンでインクリメントできるか検証しました。

i1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Create a file named counter.txt containing the number 1.",
    environment="remote",
)

i2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Read counter.txt, increment the number by 1, and overwrite the file. Tell me the new value.",
    environment=i1.environment_id,
    previous_interaction_id=i1.id,
)

print(i1.environment_id == i2.environment_id)  # -> True
print(i2.output_text)
# -> The value in `counter.txt` has been incremented. The new value is 2.

environment_id が完全に一致し、2ターン目は「1」からインクリメントした「2」を正しく返しました。ドキュメント記載どおりサンドボックスの状態は維持されています。

サンドボックス仕様と料金（実測・公式ドキュメント確認済み）

サンドボックスの詳細スペックはクイックスタートには書かれておらず、「Environments」ページ3に分離されています。

項目 値
OS Ubuntu
Python 3.12（プリインストール）
Node.js 22（プリインストール）
CPU 4コア
メモリ 16GB
アイドル時 15分の無操作でスナップショットを取り自動停止
オフライン保持 最後のアクティブから7日間、環境IDを渡せば再開可能。以降は破棄

料金面では、サンドボックスのCPU・メモリ・実行自体はプレビュー期間中無料で、課金対象はエージェントが内部で消費するモデルのトークンとツール呼び出しのみです。基盤モデル antigravity-preview-05-2026 の Gemini 3.5 Flash の標準料金は、公式料金ページ5で以下の通り確認しました。

入力 出力（thinkingトークン含む）
標準料金（1Mトークンあたり） $1.50 $9.00

1回の interaction.create() の裏では、上記の8ステップ（reasoning summaryを含む）すべてがトークンを消費します。単純な「1回のAPI呼び出し」に見えても複数ラウンドの推論ループが動くため、想定より早くトークンを消費する可能性は事前に把握しておくとよさそうです。

著者視点の発見ポイント

実際に動かして分かったのは、公式ドキュメントの「1回のAPI呼び出しでサンドボックスを立ち上げられる」というキャッチコピーは正しい一方で、クイックスタートの最初のコード例だけをコピペしても動かない という点でした。environment パラメータの必須化も、get() の引数名が id である点も「別ページを読まないと分からない」情報で、SDKの型ヒント（inspect.signature）を直接確認して初めて特定できました。

また、ステップトレース（interaction.steps）を実際に覗いてみると、エージェントは「ファイルを書く→実行する→読み返して検証する」という自己検証の手順を自発的に踏んでおり、単純な1発実行ではないことも実測して初めて分かった発見でした。

まとめ

  • Managed Agents は environment="remote" を明示しないと動かない（クイックスタートのサンプルは省略形）
  • ポーリングには client.interactions.get(id=...) を使う（interaction_id= ではない）
  • バックグラウンド実行は status の in_progress → completed 遷移をポーリングで検知する設計
  • サンドボックスは Ubuntu / Python 3.12 / Node.js 22 / 4コア / 16GBで、7日間は環境IDを使って再開できる
  • 料金は基盤モデル（Gemini 3.5 Flash: $1.50 / $9.00 per 1Mトークン）のトークン消費のみで、プレビュー期間中サンドボックス自体は無料

リモートMCPサーバー統合やカスタム関数呼び出しは今回未検証のため、続報として別記事で扱う予定です。

参考リンク

  1. Google Makes the Interactions API the Front Door to Gemini（2026-06-22付。Google公式ブログ本文には具体的な発表日の明記がないため、同日付で報じた第三者記事を出典とする） ↩

  2. Expanding Managed Agents in Gemini API（2026-07-07） ↩ ↩2

  3. Building Managed Agents | Gemini API ↩ ↩2 ↩3 ↩4

  4. Managed Agents Quickstart | Gemini API ↩

  5. Gemini Developer API pricing ↩

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?