Gemini API マネージドエージェント入門 — Google管理サンドボックスで自律AIを動かす

はじめに

Google が Gemini API のマネージドエージェント（Managed Agents）を公開プレビューとして提供開始しました（2026年5月19日発表）。1回の API コールで Google がホストする Linux サンドボックスがプロビジョニングされ、その中でエージェントが「推論・計画・コード実行・ファイル操作・Web 閲覧」を自律的に行います。

これまで自律エージェントを動かすには、コード実行用のサンドボックス、ファイルの永続化、ツール呼び出しのオーケストレーションといった「足回り（スキャフォールディング）」を自前で構築する必要がありました。マネージドエージェントは、この足回りを Google 側が肩代わりするマネージドサービスです。

この記事では、公式ドキュメントをもとに Gemini API マネージドエージェントの全体像と、google-genai SDK を使った基本的な実装パターンを解説します。

この記事で学べること

• Gemini API マネージドエージェントの仕組みと提供される2種類のエージェント
• client.interactions.create() を使った基本的な呼び出し方
• サンドボックス環境（Environment）を再利用してマルチターンで状態を引き継ぐ方法
• カスタムエージェントの定義方法とネットワーク制御・料金体系の要点

対象読者

• AI エージェントをアプリケーションに組み込みたいエンジニア
• コード実行サンドボックスを自前で運用する手間を減らしたい方
• Gemini API でツール実行型エージェントを試したい方

前提環境

• Python 3.9 以上
• google-genai SDK
• Gemini API キー（Google AI Studio で取得）

マネージドエージェントは執筆時点（2026年6月）で公開プレビューです。モデル名（例: antigravity-preview-05-2026）や API 仕様は GA までに変わる可能性があります。最新情報は公式ドキュメントを参照してください。

TL;DR

• Gemini API マネージドエージェントは、1コールで Linux サンドボックスを立ち上げて自律エージェントを動かすマネージドサービス
• 汎用の Antigravity エージェント（Gemini 3.5 Flash ベース） と Deep Research エージェント の2種類が提供される
• client.interactions.create(agent=..., input=..., environment="remote") で呼び出し、environment_id を渡せば状態を引き継げる

マネージドエージェントとは

公式ドキュメントでは、マネージドエージェントを「設定可能なエージェントハーネス（agent harness）」と説明しています。ここでいうハーネスとは、モデルが思考し、ツールを呼び出し、その結果を受け取って次の行動を決める、という一連のループを回す実行基盤のことです。

従来の「単発の生成 API」との違いは、1回のリクエストで複数の推論ループが回る点にあります。エージェントはタスクを受け取ると、自分でコードを書いて実行し、生成されたファイルを読み、Web を検索して……という試行錯誤を、人間が逐次指示しなくても自律的に進めます。

提供される2種類のエージェント

エージェント	ベースモデル	用途
Antigravity	Gemini 3.5 Flash	汎用。コード実行・ファイル管理・Web 閲覧を行う
Deep Research	（リサーチ特化）	市場分析・デューデリジェンス・文献調査などの自律リサーチ

Antigravity が汎用エージェントで、まずはこちらを試すのが基本になります。Deep Research は複雑な調査タスクに特化したエージェントです。

サンドボックス環境の仕様

エージェントが動く Linux サンドボックスには、あらかじめ実行環境が用意されています。公式ドキュメントによると、主な仕様は次のとおりです。

• ベース OS: Ubuntu（Python 3.12・Node.js 22 がプリインストール）
• 環境は非アクティブ状態が7日間続くと完全に削除される
• 1アカウントあたり最大1,000エージェントまで作成可能
• VM は一定の非アクティブ期間でシャットダウンし、次のリクエストで状態を復元（コールドスタート）

つまり、コード実行用のコンテナや言語ランタイムを自分で用意する必要がなく、ファイルや状態もある程度の期間は維持されます。

基本的な使い方

ここからは google-genai SDK を使った実装パターンを見ていきます。まずは SDK をインストールします。

pip install google-genai

最初のエージェント呼び出し

クイックスタートに沿って、Antigravity エージェントに簡単なタスクを依頼してみます。client.interactions.create() がマネージドエージェントを呼び出す中心的なメソッドです。

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. Then read the file "
        "and print its contents."
    ),
    environment="remote",
)

print(f"Interaction ID: {interaction.id}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output: {interaction.output_text}")

主要なパラメータは次のとおりです。

パラメータ	説明
agent	使用するエージェントの ID（例: antigravity-preview-05-2026）
input	エージェントへの指示（自然言語）
environment	実行環境。"remote" で新しいサンドボックスを割り当て

このコードでは、エージェントが「フィボナッチ数を生成する Python スクリプトを書く → 実行する → ファイルに保存する → 読み返して表示する」という複数ステップを、サンドボックス内で自律的に処理します。レスポンスの environment_id は次の呼び出しで再利用するための識別子です。

状態を引き継ぐマルチターン実行

エージェントの真価は、前の作業結果を引き継いで続きの作業ができる点にあります。先ほどの呼び出しで得た interaction.id と interaction.environment_id を次の呼び出しに渡すと、同じサンドボックス上で会話を継続できます。

interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    previous_interaction_id=interaction.id,
    environment=interaction.environment_id,
    input="Now plot the Fibonacci sequence as a line chart and save it as chart.png.",
)

print(interaction_2.output_text)

previous_interaction_id で会話の文脈を、environment に environment_id を渡すことでファイルシステムの状態を引き継ぎます。これにより、1回目で作成した fibonacci.txt を2回目でそのまま読み込んでグラフ化する、といった連続作業が可能になります。

ストリーミングで途中経過を受け取る

長時間かかるタスクでは、エージェントの思考やツール実行の途中経過をストリーミングで受け取れます。stream=True を指定すると、イベントを逐次受信できます。

stream = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
    environment="remote",
    stream=True,
)

for event in stream:
    print(event)

この例では、Web を閲覧して Hacker News の上位記事を要約し、PDF として保存する一連の作業の進捗を順次出力します。

カスタムエージェントを定義する

汎用の Antigravity に加えて、独自の指示やツール構成を持つカスタムエージェントを定義できます。client.agents.create() で、ベースエージェント・システム指示・利用ツールを指定します。

agent = client.agents.create(
    id="research-planner",
    base_agent="antigravity-preview-05-2026",
    description="Multi-stage research agent",
    system_instruction="You are a research planner...",
    tools=[
        {"type": "code_execution"},
        {"type": "google_search"},
        {"type": "url_context"},
    ],
)

作成したエージェントは、agent="research-planner" のように ID を指定して interactions.create() から呼び出せます。なお、ファイルシステム操作は environment を指定して実行する際に自動的に利用可能になるため、上記のように明示的にツールへ追加しなくても、生成したファイルの読み書きは行えます（指定可能なツールの正確な一覧は公式ドキュメントを参照してください）。

公式ブログによれば、エージェントの振る舞いは AGENTS.md や SKILL.md といった Markdown ファイルでカスタム指示やスキルを定義することでも拡張でき、複雑なオーケストレーションコードを書く必要がない設計になっています。Claude Code の CLAUDE.md や AGENTS.md 標準と同じ発想で、エージェントの「人格」と「手順」を宣言的に記述できるわけです。

ネットワーク制御と料金体系

アウトバウンド通信の制御

サンドボックスは、デフォルトでは外部へのアウトバウンド通信が無制限です。そのため、不要な通信を遮断したい場合は、ネットワークの allowlist（許可リスト）を設定して、特定のドメインやワイルドカードパターンのみに送信先を制限できます。具体的な設定方法は公式ドキュメントを確認してください。

エージェントが生成したコードやデータ変換、設定変更は、デプロイ前に必ず検証してください。とくに外部システムと連携したりデータを変更したりするタスクでは、出力の妥当性確認が重要だと公式ドキュメントでも注意喚起されています。

料金の考え方

料金はトークン使用量とツール消費に基づく従量課金です。公式ドキュメントによると、1回のインタラクションは複数の推論ループを伴うため、おおむね10万〜300万トークンを消費するとされています。単発の生成 API と比べてトークン消費が桁違いに大きくなりやすい点は、コスト設計の上で押さえておきたいポイントです。

なお、サンドボックスのコンピュート費用は公開プレビュー期間中は課金されないとされています（プレビュー終了後の扱いは変わる可能性があります）。

他のマネージドエージェントとの位置づけ

ツール実行型のマネージドエージェントは、各社が相次いで投入している領域です。Anthropic も Claude 向けに、自社インフラ上のサンドボックスでツールを実行する仕組みを提供しています。Gemini API のマネージドエージェントは、Google がホストするサンドボックスをそのまま使えるフルマネージド型である点が特徴で、インフラ運用の負担を最小化したいケースに向いています。

一方で、サンドボックスの実行環境を完全に自社管理下に置きたい場合は、セルフホスト型を提供する選択肢もあります。要件（運用負荷を下げたいか／実行環境を統制したいか）に応じて使い分けるとよいでしょう。

まとめ

• Gemini API マネージドエージェントは、1コールで Linux サンドボックスを立ち上げ、自律エージェントを動かすフルマネージドサービス
• 汎用の Antigravity（Gemini 3.5 Flash） と Deep Research の2種類が提供される
• client.interactions.create() が中心。environment_id と previous_interaction_id を引き継げばマルチターンで状態を維持できる
• client.agents.create() でツール構成や指示を持つカスタムエージェントを定義できる
• 1インタラクションで10万〜300万トークンを消費しうるため、コスト設計に注意

足回りの構築を Google に任せられるため、エージェントの「やりたいこと」に集中できるのが大きな利点です。まずは Antigravity エージェントで簡単なタスクを依頼し、環境の再利用やカスタムエージェント定義へと広げていくとよいでしょう。

参考リンク

• Agents Overview | Gemini API — マネージドエージェントの全体像・仕様
• Managed Agents Quickstart | Gemini API — 基本的な呼び出しコード
• Introducing Managed Agents in the Gemini API | Google Blog — 公式発表（2026-05-19）