Gemini APIでManaged Agentsを構築する: 開発者向け完全ガイド

推論し、コードを書いて実行し、Webを閲覧し、ファイルを管理する自律エージェントには、これまで何週間ものインフラ構築が必要でした。Gemini APIのManaged Agentsの公開により、Googleはそのセットアップを1回のAPI呼び出しにまで圧縮しました。1回のリクエストで、Googleがホストする安全な一時的なLinuxサンドボックスが起動し、その中で実際の作業をこなせるエージェントが使えるようになります。

このガイドでは、Antigravityエージェントの仕組み、カスタムエージェントの構築とデプロイ、再現可能な実行のための環境のフォーク方法、ネットワークと認証情報の制限方法、そして新しいGemini CLIがエージェント中心のワークフローにどう組み込まれるかまで、開発者が知るべきすべてを解説します。

Gemini API Managed Agentsとは？

Managed Agentsは、Gemini API上で自律型AIエージェントを実現するためのGoogleの新しい開発者向けプリミティブです。オーケストレーションロジック、コード実行環境、ツール呼び出しインフラ、セキュリティ制御を自前で組み合わせる代わりに、APIがそれらをすべて処理します。

Interactions APIへの1回の呼び出しで、サンドボックス化されたLinux環境がプロビジョニングされ、Geminiで動作するエージェントが起動し、タスクをエンドツーエンドで実行します。エージェントは、推論と計画、ツール呼び出し、コード実行、ファイル管理、Webブラウジングをすべて、Googleが代わりに管理する安全なランタイム内で行えます。

これを可能にするのが2つの面です。

• Interactions API — ランタイムインターフェースです。タスクを送ると、推論して行動するエージェントが返ってきます。
• Agents API — コントロールプレーンです。カスタム指示、ツール、スキル、環境設定を持つ名前付きエージェントを定義、登録、管理できます。

Antigravityエージェント: すぐ使える汎用エージェント

Gemini APIで最初に提供される汎用Managed AgentがAntigravityです。Gemini 3.5 Flashで動作し、Antigravity IDEやその他のGoogle純正エージェント製品の基盤と同じハーネス上で実行されます。Antigravity以前に利用できたManaged Agentは、複数ステップの調査ワークフロー向けの専用エージェントであるDeep Researchだけでした。

Antigravityはその汎用版です。1回のAPI呼び出しでリモートLinux環境をプロビジョニングし、すぐに作業を開始します。

Antigravityでできること

管理されたサンドボックス内で、Antigravityエージェントは次のことができます。

• Geminiエージェントハーネスを使って推論と計画を行う
• 安全なLinux環境でコードを実行し、ファイルを管理する
• Webを閲覧して最新データを取得・処理する
• Web検索、コード実行、ファイルI/Oなどのツールを使う

最初のAntigravity API呼び出し

最もシンプルなAntigravityの呼び出し例です。1回のAPI呼び出しでリモート環境をプロビジョニングし、エージェントを実行して、結果を返します。

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

これで完了です。コンテナのセットアップも、サンドボックス化のコードも、ツール呼び出しの下準備も不要です。Googleがすべて処理します。

永続環境: ステートフルなマルチターンエージェント

環境は呼び出し間で永続化されます。最初のインタラクションでサンドボックスがプロビジョニングされ、environment_id が返されます。後続リクエストでそのIDを渡すと、エージェントは前回の状態をそのまま引き継いで再開します。ファイル、パッケージ、状態はすべて前回の呼び出し時点のままです。

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

この状態保持こそが、複数ステップのワークフローを実用的にします。ある呼び出しでパッケージをインストールし、ファイルを書き、分析を実行したエージェントが、その作業結果を次の呼び出しへシームレスに引き継げます。再セットアップも、再ダウンロードも、再実行も不要です。

環境には起動時に外部データも取り込めます。Gitリポジトリ、Google Cloud Storageオブジェクト、またはインラインコンテンツを、エージェントが作業を始める前にサンドボックスへマウントできます。

カスタムManaged Agentsの構築

Antigravityエージェントは汎用タスクには十分対応できます。しかし本番用途では、特定の指示、ドメイン固有のスキル、独自ツール、厳選されたデータソースなど、カスタム動作がほぼ必ず必要になります。それがAgents APIの役割です。

Gemini Managed Agentsでは、指示、スキル、ツール、環境を1つの名前付きエージェントにまとめ、IDで呼び出せます。複雑なオーケストレーションコードを書く代わりに、AGENTS.md や SKILL.md のようなMarkdownファイルで宣言的に定義し、一度登録するだけです。

ソースからエージェントを定義する

システム指示とソースを指定して、ゼロからエージェントを作成します。ソースにはGitHubリポジトリ、Google Cloud Storageパス、またはインラインコンテンツを使えます。プラットフォームは、呼び出しのたびにファイルを含んだ新しいサンドボックスをプロビジョニングします。

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

一度登録すれば、data-analyst は名前で呼び出せる永続的なエージェントになります。各実行は、正確な設定を持つクリーンな環境をプロビジョニングします。呼び出し間で状態が漏れることはありません。

既存環境をフォークする

カスタムエージェントへの最短ルートは、反復作業であることもあります。まずはベースのAntigravityエージェントで対話的に作業し、パッケージをインストールし、テンプレートを作成し、環境を設定します。その後、その環境スナップショットを再利用可能な名前付きエージェントへフォークします。

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

保存後は、my-data-analyst の以降の呼び出しはすべてこのベーススナップショットからフォークされ、毎回クリーンで事前設定済みの状態から始まります。

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

フォークして登録するパターンは、重いセットアップに依存するエージェントで特に有効です。複雑な依存関係、大きなモデルアーティファクト、毎回の呼び出しで再構築すると時間がかかる事前コンパイル済みテンプレートなどに向いています。

安全なネットワーク接続と認証情報プロキシ

本番エージェントは、GitHub、社内API、パッケージレジストリなど外部サービスに接続する必要がほぼ確実にあります。そして、その際にサンドボックス内へ機密認証情報を露出させないこともほぼ必須です。Managed Agentsは、設定可能なegress proxyでその両方に対応します。

ネットワーク設定には2つの目的があります。

1. Allowlistは、外向き接続を明示的に許可されたドメインに制限し、エージェントが意図しない外部サービスへ接続するのを防ぎます。
2. Header transformsは、サーバー側で認証情報を注入するため、APIトークンやシークレットがサンドボックス環境自体に渡されることはありません。

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

この設定では、エージェントがアクセスできるのは api.github.com と pypi.org のみです。その他のドメインへの接続はすべてブロックされます。GitHubへのリクエストには Authorization ヘッダーが自動的に付与され、サンドボックス内のコードがトークンを直接見ることはありません。

このアーキテクチャは、社内コードリポジトリ、独自API、または認証情報の取り扱いがコンプライアンス要件となるあらゆる環境にデプロイするエージェントにとって不可欠です。

Gemini API CLI: エージェントファーストの開発体験

APIに加えて、Googleは実験的なオープンソースのGemini API CLIも提供しました。これは、コーディングエージェントが構造化され、エージェント向けに最適化された形でGemini APIとやり取りできるように設計されています。

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

agents init / agents test / agents create のワークフローは、GoogleがGemini API上で開発者に期待している構築方法の変化を反映しています。つまり、ファイルでエージェントの振る舞いを定義し、ローカルでテストし、名前付きのManaged Agentとしてデプロイするという、インフラ・アズ・コードのツールに慣れた人にはおなじみのパターンです。

補完的なツール

CLIに加えて、コーディングエージェントをGemini APIの最新状態に保つための追加要素が2つあります。

• Gemini API Docs MCP server — MCPを通じて、Geminiのドキュメント、SDK、モデル情報へライブアクセスを提供します。コーディングエージェントは古い学習データに頼らず、ドキュメントを直接参照できます。
• gemini-interactions-api Skill — Interactions APIのパターンとベストプラクティスをエージェントのコンテキストへ自動的に注入します。これにより、Gemini Managed Agentsで構築されたエージェントは最初から適切な interaction コードを書けます。

Managed Agentsが本番用途で重要な理由

Managed Agentsの根本的な賭けは、エージェント開発の難しさの大半はモデルそのものではなく、その周辺のインフラにある、という点です。サンドボックス化、ツール統合、認証情報管理、環境の再現性、ネットワークセキュリティは、エージェントを出荷するすべてのチームが個別に解決しなければならない課題です。Managed Agentsは、それらをGoogleの問題にします。

この変化は、本番デプロイに実際的な意味を持ちます。

再現可能な実行。 フォークされた環境により、すべてのエージェント呼び出しが同一のベースラインから始まることが保証されます。依存関係のずれも、実行間の状態汚染もありません。

攻撃対象領域の縮小。 認証情報はサンドボックスに入らず、ネットワークの外向き通信はallowlist制御され、実行環境は一時的で分離されています。これらは任意の強化策ではなく、標準動作です。

高速な反復。 フォークして登録するワークフローにより、チームは対話的に試し、構成を安定化させ、名前付きエージェントとして昇格できます。プロトタイプと本番の間でインフラを書き直す必要はありません。

フレームワーク互換性。 Managed Agentsは、チームが既に使っているオーケストレーションフレームワークと連携できます。ローンチパートナーには Vercel AI SDK、LiteLLM、Agno、Eigent、LlamaIndex が含まれており、既存のワークフローを大きく書き直さなくてもManaged Infrastructureの恩恵を受けられます。

エンタープライズ向けManaged Agents

大規模にカスタムManaged Agentsを運用したい企業向けに、GoogleはGemini Enterprise Agent Platformを提供しています。これは同じAPIに、ガバナンス、集中可視化、組織レベルのポリシー制御を追加したものです。

Gemini APIのManaged Agentsは現在プレビュー提供です。エンタープライズチームは、監査、DLP適用、複数チームのガバナンス向けの追加制御を備えたEnterprise Agent Platform経由で、同じManaged Agentプリミティブを利用できます。

重要なポイント

Gemini APIのManaged Agents公開により、開発者はこれまで同時に得るのが難しかった3つのものを手にしました。すぐ使える有能な汎用エージェント（Antigravity）、本番レベルのセキュリティを備えたカスタムエージェントを定義・デプロイするためのクリーンなAPI、そしてエージェントを構築するエージェントのために設計された開発体験（CLI、MCP server、Skills）です。

インフラの判断も妥当です。永続環境、環境のフォーク、egress allowlist、サーバー側の認証情報注入は、本番エージェントのデプロイに適したプリミティブです。オープンソースのCLIとSkillは、その下にあるモデル能力と同じくらい、エージェント向け開発体験が重要であることをGoogleが認識している証拠です。

Eigentのモデル非依存プラットフォーム上で構築するチームにとって、Gemini Managed Agentsは魅力的なデプロイ先です。Googleがサンドボックス化された実行レイヤーを担当する一方で、Eigentはモデルプロバイダーをまたいでタスクをインテリジェントにルーティングできます。

始めるには、AI Studio PlaygroundでAntigravityエージェントを試し、Managed Agentsのドキュメントを読み、Python SDKまたはJavaScript SDKをインストールしてください。

よくある質問

Gemini API Managed Agentsとは何ですか？

Gemini API Managed Agentsは、Googleがホストするサンドボックス化されたLinux環境内で動作する自律型AIエージェントです。Interactions APIへの1回の呼び出しでサンドボックスがプロビジョニングされ、Geminiで動作するエージェントが起動し、コード実行、Webブラウジング、ファイル管理を含むタスクを、追加のインフラセットアップなしで実行します。

Antigravityエージェントとは何ですか？

Antigravityは、Gemini 3.5 Flashで動作する、Gemini API上のGoogleの汎用Managed Agentです。安全なリモートLinux環境内で、推論と計画、コード実行、ファイル管理、Webブラウジングが可能です。Antigravity IDEやその他のGoogle純正エージェント製品を支えるのと同じエージェントハーネスを使用しています。

永続環境はどのように機能しますか？

environment="remote" を指定した最初のinteraction呼び出しで新しいサンドボックスがプロビジョニングされ、environment_id が返されます。以降の呼び出しでそのIDを渡すと、同じ環境でエージェントが再開され、すべてのファイル、インストール済みパッケージ、状態が保持されます。これにより、呼び出しのたびに再セットアップする必要のないステートフルなマルチターンワークフローが可能になります。

カスタムManaged Agentはどうやって構築しますか？

Agents APIを使って、ベースエージェント、指示、ソース（GitHubリポジトリ、GCSオブジェクト、またはインラインコンテンツ）を指定し、名前付きエージェントを定義します。登録後は、Interactions API経由で名前で呼び出せます。別の方法として、Antigravityで対話的に反復し、その結果の環境を既存の environment_id を指す base_environment を使って名前付きエージェントへフォークすることもできます。

認証情報プロキシはどのように動作しますか？

Managed Agentのegress proxyは、サンドボックスとインターネットの間に位置します。許可されたドメインの allowlist と、必要に応じてドメインごとのヘッダー transform ルールを設定します。プロキシは一致する外向きリクエストに Authorization: Bearer <token> のようなヘッダーを自動で注入するため、サンドボックス内のコードがトークン値に直接アクセスすることはありません。

Gemini Managed Agentsと互換性のあるフレームワークはどれですか？

Gemini Managed Agentsは、ローンチ時点で Vercel AI SDK、LiteLLM、Agno、Eigent、LlamaIndex とそのまま連携できます。Interactions APIはRESTベースなので、HTTPに対応したオーケストレーションフレームワークならどれでも統合可能です。

Gemini API CLIとは何ですか？

Gemini API CLIは、コーディングエージェントがGemini APIとやり取りするために設計された実験的なオープンソースツールです。プロンプトの実行、画像・音声の生成、そして init、test、create、run というManaged Agentのライフサイクル全体をコマンドラインから管理できます。

Gemini Managed Agentsはエンタープライズ利用できますか？

はい。同じManaged Agents APIが、追加のガバナンス制御、集中可視化、DLP適用、組織ポリシー管理を備えたGemini Enterprise Agent Platform経由で利用できます。Gemini APIのManaged Agentsは現在プレビュー提供です。