◈ Agents & Manager/2026-06-12中級

Managed Agents API を動かして考えた、クラウド実行と手元実行の境界線

Gemini API の Managed Agents（公開プレビュー）を Python から起動し、ポーリング・アーティファクト回収・コストガードまで実装した記録です。手元の CLI エージェントとの使い分け基準も5項目にまとめました。

Antigravity²²² Managed Agents Gemini API² エージェント³³ サンドボックス Python¹¹

✦ プレミアム記事

6月18日の Gemini CLI 提供終了を前に、手元のスクリプト群を Antigravity CLI へ移し替える作業を少しずつ進めていました。その途中でふと手が止まったのが、Gemini API 側に入った Managed Agents（公開プレビュー）の存在です。

1回の API 呼び出しで、推論・ツール使用・コード実行までを隔離された Linux 環境で済ませてくれる仕組み。I/O 2026 の発表で概要は知っていたものの、実際に触ってみると「手元のエージェント運用と役割が重なるのでは」という感触と、「いや、明確に別物として扱うべきです」という感触が交互にやってきました。

数日かけて自分の運用ジョブをいくつか移してみた結果、いまは「境界線を引けば両方とも手放せない」と考えています。本稿はその試行の記録です。コードはすべて執筆時点（2026年6月12日）の公開プレビューでの挙動に基づきます。GA までにフィールド名や挙動が変わる可能性がある点は、あらかじめご了承ください。

Managed Agents は何を肩代わりしてくれるのか

Antigravity 2.0 は、デスクトップアプリ・CLI・SDK・Managed Agents API・エンタープライズ経路の5つのサーフェスで構成されています。前の3つが「手元のマシンでエージェントを動かす」ための入口なのに対して、Managed Agents だけは性質が異なります。エージェントの実行環境そのものを Google 側のインフラに置く経路です。

呼び出しは1回。その向こうで Gemini 3.5 Flash が推論し、必要に応じてツールを使い、隔離された Linux サンドボックスでコードを実行して、成果物を返してくれます。

これを自前で組もうとすると、Docker コンテナの準備、実行ごとのクリーンアップ、権限分離、ネットワーク制限の設計が全部こちらの仕事になります。実際に私自身、記事公開パイプラインの隔離実行を自前のコンテナで運用していた時期がありますが、本体の処理よりも「環境を壊さない・漏らさない」ための周辺コードの方が大きくなりました。その周辺一式を API の向こう側へ置けるのが、この仕組みの本質と感じています。

一方で、手元のリポジトリを深く読みながら対話的に進める作業には向きません。そこは後半で整理します。

最小構成で起動する：エージェント実行は「リクエスト」ではなく「ジョブ」

最初に意識を切り替えるべき点がここでした。generateContent のような同期呼び出しではなく、Managed Agents の実行は非同期のジョブです。投げると run の ID が返り、状態が QUEUED → RUNNING → SUCCEEDED（または FAILED / TIMED_OUT）と遷移していきます。

依存パッケージの更新候補を調べさせる、小さなジョブを投げる例です。

import os
from google import genai
 
client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
 
run = client.agents.runs.create(
    model="gemini-3.5-flash",
    instructions=(
        "アップロードした package.json を読み、依存パッケージのうち"
        "メジャーバージョン更新候補を、互換性リスクの所感つきで"
        "Markdown の一覧にまとめてください。"
    ),
    input_files=["./package.json"],
    sandbox={"timeout_seconds": 600},
    metadata={"job": "dep-audit-2026-06-12"},
)
 
print(run.id, run.state)  # 例: runs/8f3c... QUEUED

このコードが解決するのは「実行環境の準備を一切せずに、コード実行込みの調査ジョブを投げる」ことです。sandbox.timeout_seconds はサンドボックス側の実行上限。metadata に自前のジョブ名を入れているのは、後述する冪等性のためです。

私の環境では、投入からサンドボックス確保（RUNNING への遷移）まで平均8秒前後でした。手元で Docker コンテナを起こすのと体感は大きく変わりません。コールドスタートを心配していたぶん、拍子抜けした部分です。

✦

ここまでお読みいただきありがとうございます。

この記事の続きを読む

この先には、実装コードやベンチマーク結果など、実務でお役に立てる内容をご用意しています。このサイトは広告を掲載しておらず、サーバーや開発にかかる費用はメンバーの皆様のご支援で成り立っています。もしお役に立てていましたら、ご支援いただけますと大変ありがたいです。

この記事で得られること

✦Managed Agents API の起動からポーリング・アーティファクト回収までを、動く Python 実装で一通り追えます

✦タイムアウト・冪等性・トークン予算ガードの3点を、運用目線でどうコードに落としたかを共有します

✦クラウドの隔離サンドボックスに乗せる処理と、手元の CLI エージェントに残す処理の判断基準を5項目に整理しました

Stripe による安全な決済 · いつでもキャンセル可能

✦

この記事を購入する

この先の内容をすべてお読みいただけます。一度のご購入で、いつでも何度でもアクセスできます。このサイトは広告を掲載しておらず、皆さまのご支援がサーバー費用などの運営を支えています。

または

メンバーシップなら全記事が読み放題 →

結果とアーティファクトの回収は「その場で」済ませる

実行が終わったら、テキスト出力とアーティファクト（サンドボックス内で生成されたファイル）を回収します。

result = client.agents.runs.get(run.id)
 
if result.state == "SUCCEEDED":
    print(result.output_text)  # エージェントの最終応答
    for artifact in result.artifacts:
        data = client.agents.artifacts.download(artifact.id)
        with open(artifact.filename, "wb") as f:
            f.write(data)
        print(f"saved: {artifact.filename}")
elif result.state == "FAILED":
    print(result.error.message)

ここで一つ注意点があります。サンドボックスは実行終了とともに破棄され、アーティファクトの保持にも期限があります。プレビューでの私の観測では、48時間を過ぎた run のアーティファクトは取得できなくなりました。「回収はあとで」と考えていると成果物ごと消えます。run の完了を検知したら、その場でダウンロードまで済ませる設計を推奨します。

output_text とアーティファクトの使い分けも最初は迷いました。いまは「人間が読む要約はテキスト、後続処理に渡すものはファイル」と割り切っています。Markdown のレポートも、後で別ジョブの入力にするならアーティファクトとして出させた方が扱いやすいためです。

待ち方の設計：ポーリング間隔・タイムアウト・冪等性

プレビュー時点では完了通知の Webhook が見当たらず、ポーリングで待つ構成にしました。定期実行に組み込むなら、ここの設計が実質的な本体です。

import time
 
def wait_for_run(client, run_id, deadline_seconds=900):
    """run の完了を指数バックオフで待つ。deadline はクライアント側の保険。"""
    started = time.monotonic()
    interval = 2
    while True:
        run = client.agents.runs.get(run_id)
        if run.state in ("SUCCEEDED", "FAILED", "TIMED_OUT", "CANCELLED"):
            return run
        if time.monotonic() - started > deadline_seconds:
            client.agents.runs.cancel(run_id)
            raise TimeoutError(f"client deadline exceeded: {run_id}")
        time.sleep(interval)
        interval = min(interval * 1.5, 30)  # 2s → 3s → ... → 上限30s

設計判断は3つあります。

タイムアウトは二重に持つ。sandbox.timeout_seconds（サーバ側）と deadline_seconds（クライアント側）は役割が違います。前者はジョブの暴走を、後者はポーリング自体の宙吊りを止めます。サーバ側だけに頼ると、状態取得が失敗し続けた場合にスクリプトが帰ってきません。
ポーリング間隔は指数バックオフ。固定2秒で回すと、長いジョブで状態取得のリクエスト数だけが積み上がります。上限30秒まで緩める形で十分でした。
再投入の前に metadata で検索する。ネットワーク断などで run の ID を取りこぼすと、「課金だけされて結果が行方不明」という嫌な状態になり得ます。私は create を呼ぶ直前にジョブ名をローカルのログへ一行書き、再実行時はまず metadata.job で既存 run を検索してから投げ直すようにしました。簡易的な write-ahead log です。

この3点目は実際に一度やらかしました。Wi-Fi の切断で ID を失い、同じジョブを二重投入。実害は小さい金額でしたが、cron に載せる前に気づけたのは幸運でした。

コストを予算で縛ってから定期実行に載せる

気になる実行コストですが、私の試行では package.json の依存調査のような軽いジョブで1回あたり 10〜15円前後、npm のビルドとテストまで回すジョブで 40〜60円程度でした（トークン消費とサンドボックス実行時間の合算。プレビュー時点の値なので、あくまで桁の目安としてご覧ください）。

単発なら誤差の範囲。怖いのは定期実行に載せて忘れた頃です。手元の並行エージェントに予算ガードを入れた経験は並行エージェントのトークンコストを予算で抑える — 暴走を止めるバジェットガードの設計に書きましたが、Managed Agents でも考え方は同じでした。実行の前に止めます。

import json
from datetime import date
from pathlib import Path
 
LEDGER = Path.home() / ".agent_budget.json"
DAILY_CAP_JPY = 300  # 1日の上限。超えたら投げない
 
def spend_or_block(estimated_jpy: float) -> bool:
    today = date.today().isoformat()
    ledger = json.loads(LEDGER.read_text()) if LEDGER.exists() else {}
    used = ledger.get(today, 0.0)
    if used + estimated_jpy > DAILY_CAP_JPY:
        return False  # 投入しない。翌日に回すかジョブを見直す
    ledger[today] = used + estimated_jpy
    LEDGER.write_text(json.dumps(ledger))
    return True

見積もりは過去の実績の中央値で十分に機能します。重要なのは精度ではなく、「上限を決めずに cron へ載せない」という原則の方です。

クラウドに乗せる処理・手元に残す処理：私の判断基準

数日の試行で、ジョブを振り分ける基準は次の5項目に落ち着きました。

入力と出力がファイルで閉じているか。閉じているならクラウド向きです。ファイルを投げて、ファイルを回収して終わるジョブは Managed Agents と相性が良いと感じます。
手元の認証情報や秘密に触る必要があるか。あるなら手元に残します。サンドボックスへ渡すファイルは選べるとはいえ、API キーや署名鍵を外へ出さない原則は崩したくありません。
失敗したとき途中状態を覗きたいか。覗きたい作業（リポジトリを深く触る修正など）は手元の CLI で進めます。Antigravity CLI（agy）を触る：Gemini CLI からの移行手順とスラッシュコマンドの読み解きで書いた対話的な使い方は、こちら側の話です。
実行環境の再現性に悩まされてきたか。「手元では動く」問題が続いたジョブほど、毎回まっさらなサンドボックスで走る恩恵が大きくなります。
定期実行で並列数が増えていく見込みか。増えるならクラウド。ただし前節の予算ガードを先に入れてからです。

私自身の振り分けでは、App Store と Google Play 向けのリリースノート整形、AdMob レポートの月次集計のような「入力も出力もファイルで閉じる定型ジョブ」を Managed Agents へ移しました。個人開発で複数のアプリとサイトを並行して見ていると、この種の定型ジョブが静かに溜まっていきます。逆に、コードベースの修正やレビューは引き続き手元の agy 側。境界線を引いてみると、どちらの道具も置き換えではなく分担なのだと腑に落ちました。