G-gen の佐々木です。当記事では、Agent Development Kit（以下 ADK と記載）で開発した AI エージェントを Cloud Run にデプロイし、Cloud Run のサンドボックス機能による Code Execution（LLM が生成したコードの安全な実行）を試します。

構成

当記事では、ADK で開発した AI エージェントを、サンドボックス機能を有効化した Cloud Run サービスとしてデプロイします。

処理の流れは以下のとおりです。

ユーザーが ADK の Web UI からエージェントに質問する
エージェントが質問への回答に必要なコードを生成し、サンドボックス内でコードを実行するためのカスタムツールを呼び出す
ツールが Cloud Run の隔離されたサンドボックス内でコードを実行する
エージェントが実行結果を元に回答を生成する

LLM が生成したコードをアプリケーションのコンテナ内で直接実行すると、意図しないファイル操作や外部通信などのリスクがあります。Cloud Run のサンドボックス機能を使用すると、ホストコンテナから隔離された環境でコードを実行できます。

当記事で使用するもの

Cloud Run とは

Cloud Run は、Google Cloud のフルマネージドなサーバーレスコンテナ実行基盤です。コンテナイメージまたはソースコードをデプロイするだけで、リクエスト数に応じた自動スケーリングを備えた Web サービスを実行できます。

Cloud Run の詳細は、以下の記事で解説しています。

blog.g-gen.co.jp

Cloud Run のサンドボックスとは

サンドボックスの概要

Cloud Run のサンドボックス（Cloud Run sandboxes）は、信頼できないコードを高速・安全・隔離された環境で実行するための機能です。

Cloud Run サービスでサンドボックス機能を有効化すると、コンテナ内で sandbox コマンドラインツールが利用可能になり、任意のコマンドをサンドボックス内で実行できます。2026年7月現在、この機能は Preview 公開です。

サンドボックスの主な特徴は以下のとおりです。

第2世代実行環境の Cloud Run でのみ使用可能
サンドボックスは必要に応じて瞬時に作成され、すぐにコマンドを実行できる
サンドボックス内のプロセスは非 root ユーザーとして実行され、デフォルトでは親ワークロードや Cloud Run のメタデータサーバーにアクセスできない（プロセスレベルの分離）
ホストコンテナの環境変数はサンドボックスに継承されず、API キーなどの機密情報が意図せず参照されることを防げる（渡す場合は --env フラグで明示的に指定する）
外部へのアウトバウンド通信はデフォルトでブロックされる（--allow-egress フラグで許可できる）
サンドボックスから見えるルートファイルシステムは読み取り専用（--write フラグやバインドマウントで書き込みを許可できる）
サンドボックスはホストコンテナと同一インスタンス内で動作し、CPU とメモリをホストコンテナと共有する
サンドボックスの作成・削除などのライフサイクルイベントは Cloud Logging に自動的に記録される

参考 : Code execution in Cloud Run
参考 : Configure sandboxes for services

sandbox コマンドラインツール

sandbox コマンドラインツールには以下のサブコマンドがあります。

コマンド	説明
`sandbox do`	一時的なサンドボックスを作成してコマンドを実行し、終了後に破棄する
`sandbox run`	サンドボックスを起動する
`sandbox exec`	実行中のサンドボックスでコマンドを実行する
`sandbox tar`	サンドボックスのファイルシステムのスナップショットを取得する
`sandbox delete`	サンドボックスを削除する

当記事では、単発のコード実行に適した sandbox do を使用します。

実行結果の取得とファイルの受け渡し

サンドボックス内で実行したプロセスの標準出力・標準エラーは、呼び出し元のプロセスに直接返されます。後述のサンプルコードでは、この仕様を利用して subprocess モジュール経由でコードの実行結果を取得します。

サンドボックスのファイルシステムへの書き込みは、--write フラグで許可した場合も一時的なもので、ホストコンテナからは参照できません。

実行結果としてファイルを取り出す場合は、サンドボックス内で変更されたファイルを tar アーカイブとして出力する --export-tar フラグ（取り込みは --import-tar、双方向同期は --sync-tar）や、--mount フラグによるバインドマウントを使用して、ホストコンテナとファイルを受け渡しします。

Agent Development Kit（ADK）とは

Agent Development Kit（以下 ADK と記載）は、Google が開発するオープンソースのエージェント開発フレームワークです。

ADK は Python、TypeScript、Go、Java に対応しており、開発したエージェントはローカル環境のほか、Agent Runtime（旧称 Agent Engine）、Cloud Run、Google Kubernetes Engine（GKE）にデプロイできます。

当記事では Python 版の ADK（google-adk）を使用します。

参考 : Agent Development Kit
参考 : google/adk-python

エージェントの開発

ディレクトリ構成

作成するプロジェクトのディレクトリ構成は以下のとおりです（uv init が生成する README.md や .python-version などは省略）。

sandbox-agent/
├── .dockerignore
├── Dockerfile
├── main.py              # FastAPI アプリのエントリーポイント
├── pyproject.toml
├── uv.lock
└── sandbox_agent/       # ADK エージェントのパッケージ
    ├── __init__.py
    └── agent.py         # エージェントとツールの定義

uv プロジェクトの作成

uv プロジェクトを初期化し、依存パッケージとして google-adk と uvicorn を追加します。

# uv のセットアップ
$ uv init sandbox-agent --python 3.13
$ cd sandbox-agent
  
# 依存パッケージのインストール
$ uv add google-adk uvicorn
  
# エージェントのパッケージディレクトリとファイルの作成
$ mkdir sandbox_agent
$ touch sandbox_agent/__init__.py sandbox_agent/agent.py Dockerfile .dockerignore

main.py は uv init によって生成されるため、ここでは作成せず、後の手順で内容を書き換えます。各ファイルの中身は以降の節で順に記述していきます。

pyproject.toml は以下のようになります。

[project]
name = "sandbox-agent"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
    "google-adk>=2.4.0",
    "uvicorn>=0.51.0",
]

agent.py

エージェント本体とカスタムツールを sandbox_agent/agent.py に定義します。

import subprocess
  
from google.adk.agents import Agent
from google.adk.tools import FunctionTool
  
SANDBOX_BIN = "/usr/local/gcp/bin/sandbox"
PYTHON_BIN = "/usr/local/bin/python3"
  
  
def execute_python_code(code: str) -> dict:
    """Python コードをサンドボックス内で実行し、結果を返す。
  
    Args:
        code: 実行する Python ソースコード。
  
    Returns:
        stdout、stderr、returncode を含む dict。
    """
    result = subprocess.run(
        [SANDBOX_BIN, "do", "--", PYTHON_BIN, "-c", code],
        capture_output=True,
        text=True,
        timeout=60,
    )
    return {
        "stdout": result.stdout,
        "stderr": result.stderr,
        "returncode": result.returncode,
    }
  
  
root_agent = Agent(
    name="sandbox_agent",
    model="gemini-2.5-flash",
    description="Python コードをサンドボックスで実行して回答するエージェント",
    instruction=(
        "あなたはユーザーの質問に答えるアシスタントです。"
        "計算やデータ処理が必要な場合は、必ず Python コードを書いて"
        " execute_python_code ツールで実行し、その実行結果に基づいて回答してください。"
        "実行結果の stdout をそのまま引用し、コードの内容も簡単に説明してください。"
    ),
    tools=[FunctionTool(func=execute_python_code)],
)

ポイントは以下のとおりです。

execute_python_code 関数を FunctionTool でラップしてエージェントのツールとして登録している。関数のドキュメンテーション文字列と型ヒントがツールの仕様として LLM に渡される
ツール内では、サンドボックス機能の有効化時にコンテナへ配置されるバイナリ /usr/local/gcp/bin/sandbox を subprocess で呼び出し、sandbox do -- /usr/local/bin/python3 -c <コード> の形式で LLM が生成した Python コードをサンドボックス内で実行している
サンドボックスからはホストコンテナのルートファイルシステムが読み取り専用で参照できるため、コンテナイメージに含まれる Python ランタイムをサンドボックス内でも実行できる
サンドボックスにはホストの環境変数が継承されず、実行するコマンドの PATH 解決も行われないため、コマンドは /usr/local/bin/python3 のような絶対パスで指定する必要がある

init.py

ADK がエージェントを認識できるように、sandbox_agent/__init__.py で agent モジュールをインポートしておきます。

from . import agent

main.py

Cloud Run 上でエージェントを Web アプリケーションとして公開するため、ADK が提供する get_fast_api_app() で FastAPI アプリを作成します。

import os
  
from google.adk.cli.fast_api import get_fast_api_app
  
AGENTS_DIR = os.path.dirname(os.path.abspath(__file__))
  
app = get_fast_api_app(
    agents_dir=AGENTS_DIR,
    allow_origins=["http://localhost:8080", "http://127.0.0.1:8080"],
    web=True,
)
  
if __name__ == "__main__":
    import uvicorn
  
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

get_fast_api_app() は、ADK の開発用 Web UI とエージェント実行用の REST API を含む FastAPI アプリを返します。agents_dir にはエージェントのパッケージ（当記事では sandbox_agent/）が置かれたディレクトリを指定し、web=True で Web UI を有効化します。ポート番号は Cloud Run が設定する環境変数 PORT から取得します。

allow_origins には、後述の動作確認で gcloud run services proxy コマンド経由で Web UI にアクセスするときのオリジンを指定します。ADK の API サーバーは、セキュリティ対策として POST などの状態変更リクエストの Origin ヘッダーを検証します。プロキシ経由のアクセスでは Origin（http://127.0.0.1:8080 など）とリクエスト先（run.app ドメイン）が一致しないため、allow_origins を指定していないと Web UI からの操作が403エラーになります。

Dockerfile

uv を使用してコンテナイメージをビルドする Dockerfile を作成します。

FROM python:3.13-slim
  
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
  
WORKDIR /app
  
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
  
COPY . .
  
ENV PATH="/app/.venv/bin:$PATH"
  
CMD ["python", "main.py"]

.dockerignore

.dockerignore に以下の内容を記述し、ローカルの .venv などをコンテナイメージのビルドコンテキストから除外します。

.venv
__pycache__
*.pyc
.git

後述のデプロイで使用する --source フラグは、カレントディレクトリ全体を Cloud Build にアップロードします。.dockerignore で除外していない場合、COPY . . の際にローカル環境用の .venv がコンテナ内に作成済みの .venv を上書きし、コンテナの起動に失敗するため注意してください。

Google Cloud 側の準備

API の有効化

使用する API を有効化します。ソースコードからのデプロイ（--source フラグ）では Cloud Build と Artifact Registry も使用されるため、あわせて有効化します。なお2026年7月現在、Gemini の呼び出しに使用する Agent Platform の API 名や IAM ロール ID には、旧称の Vertex AI に由来する aiplatform という名称が残っています。

$ gcloud services enable \
    run.googleapis.com \
    aiplatform.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    --project=<プロジェクトID>

サービスアカウントの作成

Cloud Run サービスが使用するサービスアカウントを作成します。エージェントが Agent Platform の API 経由で Gemini を呼び出すため、Agent Platform ユーザー（roles/aiplatform.user）を付与します。

# サービスアカウントの作成
$ gcloud iam service-accounts create sandbox-agent \
    --project=<プロジェクトID>
  
# Agent Platform ユーザーの付与
$ gcloud projects add-iam-policy-binding <プロジェクトID> \
    --member="serviceAccount:sandbox-agent@<プロジェクトID>.iam.gserviceaccount.com" \
    --role="roles/aiplatform.user"

デプロイ

作成したプロジェクトのディレクトリ（sandbox-agent/）で、以下のコマンドを実行して Cloud Run にデプロイします。サンドボックス機能を有効化する --sandbox-launcher フラグは、2026年7月現在、gcloud beta コマンドでのみ使用できます。

$ gcloud beta run deploy sandbox-agent \
    --source . \
    --project=<プロジェクトID> \
    --region=asia-northeast1 \
    --execution-environment=gen2 \
    --sandbox-launcher \
    --service-account=sandbox-agent@<プロジェクトID>.iam.gserviceaccount.com \
    --set-env-vars=GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=<プロジェクトID>,GOOGLE_CLOUD_LOCATION=asia-northeast1 \
    --no-allow-unauthenticated

主なフラグの意味は以下のとおりです。

フラグ	説明
`--source .`	カレントディレクトリのソースコードから Cloud Build でコンテナイメージをビルドしてデプロイする。`Dockerfile` が存在する場合はそれが使用される
`--execution-environment=gen2`	第2世代実行環境を指定する。サンドボックス機能の使用に必須
`--sandbox-launcher`	サンドボックス機能を有効化する。コンテナ内に `sandbox` コマンドラインツールが配置される
`--service-account`	ランタイムサービスアカウントとして、前の手順で作成したサービスアカウントを指定する
`--set-env-vars`	ADK が Agent Platform 経由で Gemini を呼び出すための環境変数を設定する。`GOOGLE_GENAI_USE_VERTEXAI` という変数名にも旧称に由来する名称が残っている
`--no-allow-unauthenticated`	未認証のアクセスを拒否する

環境変数 GOOGLE_CLOUD_LOCATION は、Gemini を呼び出す Agent Platform 側のロケーションであり、Cloud Run サービスのリージョン（--region）とは独立しています。当記事では asia-northeast1 を指定し、東京リージョンのリージョンエンドポイント経由でモデルを呼び出します。

参考 : gcloud beta run deploy

動作確認

Web UI へのアクセス

デプロイしたサービスは未認証アクセスを拒否しているため、gcloud run services proxy コマンドで手元の端末からプロキシ経由でアクセスします。

$ gcloud run services proxy sandbox-agent \
    --project=<プロジェクトID> \
    --region=asia-northeast1

ブラウザで http://localhost:8080 を開くと、ADK の開発用 Web UI にアクセスできます。画面左上のプルダウンでエージェント sandbox_agent を選択します。

ADK の開発用 Web UI にアクセスし、sandbox_agent を選択する

エージェントとの対話

エージェントに、コード実行が必要な質問を送信します。例として「1から100までの素数の合計を計算してください」と質問すると、エージェントは Python コードを生成して execute_python_code ツールを呼び出し、サンドボックス内での実行結果を元に回答します。

Web UI の Info ペインでは、ツール呼び出しの内容を確認できます。Function Calls イベントにはエージェントが生成した Python コードが、Function Responses イベントにはサンドボックスでの実行結果（stdout など）が記録されています。

ログの確認

前述のとおり、サンドボックスのライフサイクルイベントは Cloud Logging に自動的に記録されます。サンドボックスの実行ログは、Cloud Run の標準ログ（stdout や requests）とは別の専用ログ run.googleapis.com//var/log/sandbox.log に出力されるため、ログエクスプローラで以下のクエリを実行して確認します。

resource.type="cloud_run_revision"
resource.labels.service_name="sandbox-agent"
logName="projects/<プロジェクトID>/logs/run.googleapis.com%2F%2Fvar%2Flog%2Fsandbox.log"

sandbox do の実行1回につき [start] と [end] のペアが記録され、実行したコマンドの全文（LLM が生成した Python コードを含む）が残ります。以下は先ほどの対話で実際に記録されたログです（[end] のコマンド文字列は省略しています）。

[start] cwd=/app "/usr/local/gcp/bin/sandbox do -- /usr/local/bin/python3 -c
def is_prime(n):
    if n < 2:
        return False
    for i in range(2, int(n**0.5) + 1):
        if n % i == 0:
            return False
    return True
  
total_sum = 0
for number in range(2, 101):
    if is_prime(number):
        total_sum += number
  
print(total_sum)
"

[end] exit_code=0 elapsed=541ms "/usr/local/gcp/bin/sandbox do -- /usr/local/bin/python3 -c ..."

[end] エントリには終了コード（exit_code）と実行時間（elapsed）が付くため、サンドボックスが実際に使用されたこと、どのようなコードが実行されたか、正常に終了したかどうかまで確認できます。今回の実行時間は約540ミリ秒で、サンドボックスの作成からコード実行、破棄までが高速に完了していることもわかります。

参考 : Code execution in Cloud Run

構成