Gemini API の Code Execution を使いはじめたとき、最初にぶつかりやすい壁は「コードを渡したのに実行されない」という現象です。
私自身、壁紙アプリの色分析バッチ処理に Code Execution を試したとき、最初の30分は理由も分からずに空の応答を眺めていました。2014年から個人でアプリ開発を続けてきて、エラーメッセージを読む習慣はついていたつもりでしたが、この機能はエラーメッセージすら出ないケースがあるので、普段と勝手が違いました。
ここでは実際に遭遇しやすい3つのパターンとその修正方法を、動作するコードと合わせて紹介します。
Code Execution が有効になっていない(最多の原因)
まず確認してほしいのが、tools パラメータです。Code Execution を使うには、モデルの呼び出し時に明示的に指定する必要があります。これを省略すると、Gemini はコードを「生成」しますが「実行」はしません。
# ❌ これだとコードを書いてくれるが実行されない
import google.generativeai as genai
model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content("Pythonで1から100の合計を計算して")
print(response.text)
# 出力: "Pythonで1から100の合計を計算するには、以下のコードを使います..."(実行結果なし)# ✅ tools に code_execution を渡すと実行される
import google.generativeai as genai
model = genai.GenerativeModel(
model_name="gemini-2.5-flash",
tools="code_execution", # これが必須
)
response = model.generate_content("Pythonで1から100の合計を計算して")
# レスポンスからコードと実行結果を取得する
for part in response.candidates[0].content.parts:
if hasattr(part, "executable_code"):
print("=== 実行したコード ===")
print(part.executable_code.code)
elif hasattr(part, "code_execution_result"):
print("=== 実行結果 ===")
print(part.code_execution_result.output)
# 出力:
# === 実行したコード ===
# total = sum(range(1, 101))
# print(total)
# === 実行結果 ===
# 5050response.text だけを見ていると実行結果が見つからないように感じることがあります。parts を一つずつ確認する必要があるのが、この機能の扱いやすさを少し下げているポイントです。
import エラー — サンドボックスで使えないライブラリ
Code Execution はサンドボックス環境で動作するため、使えるライブラリに制限があります。requests、flask、selenium などのネットワークアクセスや外部依存を持つライブラリはインポートできません。
# ❌ これはエラーになる(サンドボックス内でネットワーク不可)
import google.generativeai as genai
model = genai.GenerativeModel(
model_name="gemini-2.5-flash",
tools="code_execution",
)
response = model.generate_content(
"requestsライブラリでhttps://example.comのHTMLを取得して解析して"
)
# code_execution_result に以下のようなエラーが出る:
# ModuleNotFoundError: No module named 'requests'
# または接続エラーが返ってくる現時点でサンドボックス内で使える主なライブラリは、標準ライブラリに加えて以下のようなものです。
numpy,pandas,scipy(数値計算・データ処理)matplotlib,seaborn(グラフ描画)scikit-learn(機械学習)pillow(画像処理)sympy(数式処理)
逆に、使えないもの(実行時にエラーになる)の代表例は以下の通りです。
requests,httpx,aiohttp(HTTP通信)selenium,playwright(ブラウザ操作)flask,fastapi,django(Webフレームワーク)psycopg2,pymongo(データベースドライバ)
# ✅ サンドボックスで動作する処理の例(NumPy を使った計算)
model = genai.GenerativeModel(
model_name="gemini-2.5-flash",
tools="code_execution",
)
response = model.generate_content(
"NumPyを使って100個の正規分布乱数を生成し、平均と標準偏差を計算して"
)
for part in response.candidates[0].content.parts:
if hasattr(part, "code_execution_result"):
print(part.code_execution_result.output)
# 出力例:
# 平均: 0.023
# 標準偏差: 0.998ライブラリが使えるかどうかを事前に確認したい場合は、シンプルな import テストを実行させてみるのが手早い方法です。
タイムアウト — 重い処理は途中で打ち切られる
サンドボックスの実行時間には上限があります。公式ドキュメントには明示されていませんが、実用上は数秒から数十秒程度の軽い処理向けだと考えておくのが安全です。
私が色分析処理に使おうとして詰まったのはまさにここで、数千枚の画像データに対する統計処理をそのまま渡したところ、途中で応答が止まりました。
# ❌ 重い処理(100万回ループなど)はタイムアウトになりやすい
response = model.generate_content(
"1から1000万までの素数を全部リストアップして"
)
# code_execution_result に以下のようなメッセージが返ってくることがある:
# TimeoutError または出力が途中で途切れた状態対処策は2つあります。
① 処理のスコープを絞る
# ✅ 件数を限定する
response = model.generate_content(
"1から1000までの素数をリストアップして、件数と最大値を教えて"
)② 重い処理はローカルで実行し、結果だけを Gemini に渡す
Code Execution の本来の強みは「数値を渡して分析・解釈をさせる」ことです。大量データの前処理をローカルで行い、集計済みの数値を Gemini に渡すパターンが実際の開発では安定しています。
import pandas as pd
import google.generativeai as genai
# ローカルで前処理を済ませる
df = pd.read_csv("sales_data.csv")
summary_stats = df.describe().to_string()
model = genai.GenerativeModel(
model_name="gemini-2.5-flash",
tools="code_execution",
)
# 集計済みデータを渡して分析させる
response = model.generate_content(
f"以下の売上データの統計サマリーを分析して、気になる傾向を教えて:\n\n{summary_stats}"
)
for part in response.candidates[0].content.parts:
if hasattr(part, "code_execution_result"):
print(part.code_execution_result.output)
elif part.text:
print(part.text)エラー情報を取得する実装パターン
Code Execution のレスポンスには outcome フィールドが含まれており、実行が成功したか失敗したかを確認できます。本番で使う際はこれを見てハンドリングするのがおすすめです。
import google.generativeai as genai
model = genai.GenerativeModel(
model_name="gemini-2.5-flash",
tools="code_execution",
)
def run_with_code_execution(prompt: str) -> dict:
"""Code Execution の結果を構造化して返す関数"""
response = model.generate_content(prompt)
result = {
"code": None,
"output": None,
"outcome": None,
"text": [],
}
for part in response.candidates[0].content.parts:
if hasattr(part, "executable_code"):
result["code"] = part.executable_code.code
elif hasattr(part, "code_execution_result"):
result["outcome"] = part.code_execution_result.outcome.name
result["output"] = part.code_execution_result.output
elif part.text:
result["text"].append(part.text)
# outcome の値: OUTCOME_OK, OUTCOME_FAILED, OUTCOME_DEADLINE_EXCEEDED
if result["outcome"] == "OUTCOME_FAILED":
print(f"⚠️ コード実行エラー: {result['output']}")
elif result["outcome"] == "OUTCOME_DEADLINE_EXCEEDED":
print("⏱️ タイムアウト: 処理を分割するか、スコープを絞ってください")
return result
# 使用例
result = run_with_code_execution("fibonacci数列の最初の20項を計算して")
print(f"実行結果: {result['output']}")
print(f"ステータス: {result['outcome']}")outcome を見ることで、エラーメッセージがなくても何が起きているかを把握できます。実際の開発では最初からこのパターンを使っておくと、デバッグ時間をかなり節約できます。
全体を振り返って
Code Execution で詰まるポイントを整理すると、ほとんどのケースは以下のどれかに当てはまります。
tools="code_execution"の指定漏れ- サンドボックスで使えないライブラリの import
- 実行時間が長すぎる処理
まず outcome フィールドを確認する習慣をつけると、原因の特定が早くなります。Code Execution は軽量な計算・分析処理との相性が非常によく、適切なスコープで使えばとても便利な機能です。ぜひ Gemini Code Execution APIの基本ガイドも合わせてご参照ください。
APIの認証周りで詰まった場合は認証エラーの対処法、レート制限に関しては429エラーのトラブルシューティングも参考になると思います。