Tracks
AIエージェントの基礎
6時間
今週初め、Google の I/O 2026 開発者会議で、Google は Gemini マネージドエージェントを発表しました。これは自律型 AI エージェントのデプロイを簡素化するツールで、開発者は 1 回の API 呼び出しで、孤立した一時的な Linux 環境内で推論、計画、ウェブ閲覧、コード実行が可能なエージェントを立ち上げられます。
本チュートリアルでは、Gemini マネージドエージェントとは何か、その仕組み、そして API を使ってあらゆる種類のデータを分析できるデータアナリストエージェントを作成する方法を学びます。
エージェント型 AI が初めての方は、Introduction to AI Agents コースから始めてください。
Gemini API のマネージドエージェントとは？
エージェントは、自分専用の分離されたコンピュータにアクセスできる自律的な作業者と考えるとわかりやすいでしょう。データセットの分析といったタスクが与えられると、エージェントは作業に必要なコードを自律的に作成・実行します。処理が完了すると、エージェントのワークスペースにアクセスして結果を取得できます。
マネージドエージェントはコードを書く以上のことができます。インターネットとやり取りし、ファイルを管理し、幅広いツールを活用してタスクの実行を効率化します。
これらのエージェントは、Gemini モデル向けの汎用エージェント基盤である Google の Antigravity エージェントによって動作します。
実行環境内に事前構成された運用ツール群を提供し、手動セットアップを不要にします。これには Bash、Python、Node.js のコード実行用サンドボックス化されたランタイムが含まれ、エージェントはローカルでコードの作成、デバッグ、実行が可能です。
また、リモートコンテナ内の永続ファイルシステムによるファイル管理も提供され、エージェントは連続するターンをまたいでファイルの読み書き、編集、検索が行えます。
最後に、ウェブ統合により Google 検索への直接アクセスが提供され、最新情報のグラウンディングや、非構造データの取得・解析ユーティリティが利用できます。
ユースケース例
喫茶店を経営し、売上を分析したいとします。マネージドエージェントを設定して、売上データベースにアクセスできるようにします。
あとはレポートが必要なときに、平易な英語でデータ分析を依頼するだけです。エージェントは自律的に Python コードを作成・実行し、要約レポートを生成して、レビューできるようファイルシステムに保存します。
Gemini API のマネージドエージェントの料金は？
Gemini マネージドエージェントの料金には多くの要素が関わるため、正確な見積もりは難しい場合があります。主な要因は次の 4 つです。
- モデル利用（トークン）: 基盤となる Gemini モデルが処理する入出力トークン数に基づいて課金されます。これには中間結果で生成されるトークンも含まれます。たとえば、レポート作成のためにエージェントが Python スクリプトを生成した場合、そのスクリプトに必要なトークンも課金対象です。
- インフラ／プラットフォーム手数料: マネージドエージェントは Google の統合環境内で動作し、エージェントの管理・デプロイに Vertex AI Agent Builder などのプラットフォームツールを利用するため、そのサービス利用料が発生します。
- コンテキストキャッシング: 同じデータを頻繁に再利用する場合、マネージドエージェントはコンテキストキャッシングを活用できます。これは通常、標準的なトークン課金と比べて大幅なコスト削減につながります。
- グラウンディング: エージェントが Google Search や Google Maps などの Google のグラウンドサービスを利用する場合は、これらが別途課金されます。多くの場合、無料枠のクォータ後に 1,000 クエリあたりの単価（一般的に $14/1,000 クエリ程度）が適用されます。
本チュートリアルでは、antigravity-preview-05-2026 エージェント上に、d by Gemini 3.5 Flash を基盤とするエージェントを構築します。Gemini 3.5 Flash のトークン単価は以下のとおりです。
Gemini API でマネージドエージェントを構築する方法
このガイドでは、Gemini API と Python を使ってマネージドエージェントを構築します。マネージドエージェントはベータ版として最近リリースされたため、一部の実装詳細は今後変わる可能性があります。
本チュートリアルで記述するコードはすべてこの GitHub リポジトリに保存されており、データアナリストエージェントとデータを共有する際にも使用します。
API のセットアップ
AI キーを作成するには、Google AI Studio に移動し、右上の「Create API Key」をクリックします。
API キーは Google Cloud プロジェクトに関連付ける必要があります。既存プロジェクトを選択するか、新規作成します。ここでは gemini-managed-agents という名前で作成しました。
キーを作成したらコピーします。次に、エージェントを作成するフォルダに .env というファイルを作成し、以下の形式で貼り付けます。
GEMINI_API_KEY=<paste_your_api_key_here>Google AI Studio を閉じる前に、作成した API キーで課金設定を行う必要があります。これを行わないと、Google が課金できないためリクエストは拒否されます。課金を設定するには「Set up billing」ボタンをクリックします。
Python 環境のセットアップ
このプロジェクトの Python 環境構築には Anaconda を使用します。Anaconda で環境を作成するには、次のコマンドを使用します。
conda create --name gemini_agents python=3.12 -yこれにより、Python バージョン 3.10 を使用する gemini_agents という環境が作成されます。-y パラメータは、環境作成時のすべての質問に自動で「yes」と回答するためのショートカットです。
次に、環境を有効化します。
conda activate gemini_agents最後に、必要な依存関係をインストールします。以下のとおりです。
pip install google-genai requests python-dotenvマネージドエージェントとの基本的なやり取りを作成する
これで最初のエージェントを実行する準備が整いました。最初のエージェントは多くは行いません。matplotlib をインストールし、インストールされたバージョンを報告するだけです。
マネージドエージェントとやり取りする手順を段階的に説明します（完全なコードはリポジトリ内の simple_interaction.py スクリプトにあります）。
まず、必要なパッケージをインポートし、先ほど作成した .env ファイルから API キーを読み込みます。
from dotenv import load_dotenv
from google import genai
# Load secure environment variables
load_dotenv()次に、Gemini クライアントを初期化し、現在 antigravity-preview-05-2026 という名前のベースエージェントに matplotlib のインストールを依頼して、やり取りを作成します。
# Initialize the GenAI Client
client = genai.Client()
# Create a basic interaction with a managed agent
interaction = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Install the matplotlib package, verify its version, and report back.",
environment="remote"
)最後に、status、environment_id、output_text プロパティを確認してエージェントの出力を取得します。
# Output the status of the agent
print(f"Status: {interaction.status}")
print(f"Environment ID: {interaction.environment_id}")
print(f"Output:\n{interaction.output_text}")結果は次のとおりです。
Status: completed
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6
Output:
I have successfully installed the matplotlib package in the sandbox environment and verified its installation.
Here are the details:
- **Installation Command:** python3 -m pip install --break-system-packages matplotlib
- **Installed Version:** 3.10.9サンドボックスのライフサイクル状態
上の例では、マネージドエージェントのやり取りの環境識別子を表示しました。
Environment ID: 104ad7f8-32e0-4b8d-b344-24d92eb74eb6この値は、エージェントが実行された環境の識別子を表すため重要です。エージェントのやり取りは、最後の活動から最大 7 日間保持される一時的な環境に保存され、その後削除されます。
下の図は、やり取り中にエージェントが実行されるサンドボックスのライフサイクルを示しています。
環境が削除されていない間は、環境識別子を使ってアクセスし、さらにやり取りを行うことができます。
複数回のやり取りを行う
この例では、複数のやり取りを行う方法を示します。完全なコードはリポジトリの multiple_interactions.py にあります。
# First interaction
inter1 = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Write a Python script sum.py that adds all integers from 1 to 100.",
environment="remote"
)
# Second interaction
inter2 = client.interactions.create(
agent="antigravity-preview-05-2026",
previous_interaction_id=inter1.id, # Passes the conversation history
environment=inter1.environment_id, # Keeps the same filesystem state
input="Execute 'sum.py' using Python and display the standard output."
)
# Output the status of the agent
print(f"Output:\n{inter2.output_text}")2 回目のやり取りでは、次の 2 つのパラメータを追加している点に注意してください。
-
previous_interaction_id: 直前のやり取りの識別子。これにより、エージェントは会話履歴を把握できます。 -
environment: エージェントがどのサンドボックスで実行すべきかを示す環境識別子。
エージェントとファイルを共有する
データアナリストエージェントを作るには、エージェントにデータへのアクセスを与えられなければなりません。エージェントとデータを共有する方法はいくつかあります。
- インラインデータ: ファイル内容を文字列に読み込み、やり取り時に送信します。
- ホスト済みファイル:データを公開 URL にホストし、エージェントにダウンロード用の URL を提供します。
- GitHub リポジトリ: 公開リポジトリの URL をエージェントに提供します。
- Google Cloud バケット: Google Cloud Storage バケットにファイルをホストし、プロジェクトを構成してエージェントがそのバケットにアクセスできるようにします。
本記事ではこれらすべての方法は扱いません。ローカルファイルを文字列に読み込んで送るインラインデータと、GitHub リポジトリの共有方法を示します。前者は小さなローカルファイル（1 ファイル最大 1 MB、全ファイル合計 2 MB まで）の共有に最適で、後者はデータセットなどの大きなファイルの共有に適しています。
インラインデータの共有
インラインデータを提供する例を示します（完全なコードは inline_example.py）。
inter = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Add all the numbers in the /workspace/numbers.txt file.",
environment={
"type": "remote",
"sources": [
{
"type": "inline",
# The file where to store the data in the agent environment
"target": "/workspace/numbers.txt",
# Assumes that the file data/numbers.txt exists
"content": utils.read_text_file("data/numbers.txt")
}
]
}
)environment 設定内の sources パラメータでデータを提供します。target は、データをエージェントの環境内のどこに保存するかを定義します。ファイルは workspace フォルダに配置する必要があります。この場合は number.txt という名前のファイルになります。
content パラメータはファイルの中身を指定します。inline ソースでは単なる文字列で、ここでは utils.py の read_text_file() 関数で読み込みます。
GitHub リポジトリの共有
より大きなファイルを共有するには、GitHub リポジトリの URL を提供します。方法は次のとおりです。
inter = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Add all the numbers in the /workspace/repository/numbers.txt file.",
environment={
"type": "remote",
"sources": [
{
"type": "repository",
"source": "https://github.com/fran-aubry/gemini-agents-tutorial",
"target": "/workspace/repository"
}
]
}
)上の例では、URL https://github.com/fran-aubry/gemini-agents-tutorial のリポジトリが、エージェントのワークスペース内の repository というフォルダにクローンされます。
エージェントの環境をダウンロードする
すでに、マネージドエージェントとやり取りする方法、およびこれらのエージェントにファイルを提供する方法を学びました。データアナリストエージェントを作成するにあたり、最後に学ぶべきはエージェントの環境をダウンロードする方法です。これは、エージェントが生成したチャートや結果にアクセスするために必要です。
各ワークスペースは次の URL でダウンロードできます。
https://generativelanguage.googleapis.com/v1beta/files/environment-<env_id>:downloadここで、<env_id> はダウンロードしたい環境の識別子に置き換えます。
以下は、requests パッケージを使ってパッケージをダウンロードする Python 関数です（この関数は作成した utils.py の一部です）。
def download_env(env_id, path="environments"):
download_url = f"https://generativelanguage.googleapis.com/v1beta/files/environment-{env_id}:download"
try:
request_params = {"alt": "media"} # Retrieves raw media binary
request_headers = {"x-goog-api-key": os.environ.get("GEMINI_API_KEY")}
# Download the environment
print(f"Downloading environment: {env_id}")
response = requests.get(
download_url,
params=request_params,
headers=request_headers,
allow_redirects=True
)
response.raise_for_status()
# Save the compressed workspace archive locally
archive_name = f"{env_id}.tar"
output_path = os.path.join(path, archive_name)
with open(output_path, "wb") as archive_file:
archive_file.write(response.content)
print(f"Successfully downloaded workspace snapshot archive: {output_path}")
except requests.exceptions.RequestException as error:
print(f"Failed to download sandbox workspace via HTTP request: {error}")
except tarfile.TarError as archive_error:
print(f"Failed to unpack download tarball: {archive_error}")データアナリストエージェントを構築する
このセクションでは、データ分析を行うエージェントの作成方法を学びます。エージェントのテストには、Kaggle から取得し、data フォルダにも保存してあるこの Netflix データセットを使用します。
前の例では常にベースエージェント antigravity-preview-05-2026 とやり取りしてきました。ここではまず、client.agents.create() 関数を使ってエージェントを作成します。
エージェントを作成する
エージェントの作成方法は次のとおりです。
agent = client.agents.create(
id=”data-analyst”,
base_agent="antigravity-preview-05-2026",
base_environment={
"type": "remote",
"sources": [
{
"type": "inline",
"target": ".agents/AGENTS.md",
"content": read_text_file(".agents/AGENTS.md")
},
# Explicitly load the skill
{
"type": "inline",
"target": ".agents/skills/csv-aggregator/SKILL.md",
"content": read_text_file(".agents/skills/csv-aggregator/SKILL.md")
},
{
"type": "repository",
"source": "https://github.com/fran-aubry/gemini-agents-tutorial",
"target": "/workspace/repository"
}
]
}各パラメータを分解して説明します。
-
id: エージェントの名前を定義します。この例ではdata-analystです。以降は、これまで使用してきたantigravity-preview-05-2026の代わりに、client.interactions.create()のagent引数にこの識別子を使います。 -
base_agent: ベースとして使用するエージェント。つまり、antigravity-preview-05-2026の上にエージェントを構築します。 -
base_environment: 前と同様に、エージェントにファイルを提供できます。ここでは.agents/AGENTS.mdと.agents/skills/csv-aggregator/SKILL.mdの 2 つの特別なファイルを提供しました。これらのファイルでエージェントの動作を定義します。AGENTS.mdはエージェントの一般的な振る舞いを、SKILL.mdは特定のスキルを定義します。さらに、分析対象のデータファイルへアクセスできるよう、リポジトリも提供しました。
AGENTS.md を理解する
このファイルはシステムプロンプトのようなものです。エージェントの主要な指示書として機能します。エージェントの具体的な役割、主な目標、作業時に守るべき境界を明確に定義するのに使います。
また、エージェントがアクセスを許可されている特定のツールやデータソースを列挙したり、望ましいコミュニケーションやタスク処理の例を示したりするのにも最適な場所です。
このファイル内の指示をシンプルかつ整理しておくことで、エージェントはどのように振る舞い、どのような成果を期待されているのかを正確に理解できます。
エージェント環境内でのファイルの配置場所は .agents/AGENTS.md にする必要があります。
SKILL.md を理解する
スキルファイルは、エージェントに特定のスキルを付与するために使用します。エージェントは複数のスキルを持つことができ、それぞれを .agents/skills/<skill_name>/SKILL.md（<skill_name> はスキル名に置き換え）にある SKILL.md で記述します。
スキルファイルの構成は次のようにします。
---
name: <skill_name>
description: <description of when to use the skill>
---
<steps on how to perform the task>例として、data-analyst エージェントに csv-aggregator というスキルを付与しました。定義はこちらです。このスキルは、CSV の行をある列でグループ化し、別の列を加算したいときに使用します。
Netflix データセットの場合、視聴回数が最も多いジャンルを知りたければ、Genre 列で行をグループ化し、Viewership 列の値を加算します。このスキルファイルは、このタスクの実行方法をエージェントに説明します。
エージェントを読み込む
エージェントは永続的であるため、作成を 2 回実行しようとするとエラーになります。このため、utils.py に load_or_create_agent() 関数を用意しました。この関数はエージェントの作成を試み、既に存在する場合は client.agents.load() を使って読み込みます。
すべてを組み合わせる
データアナリストエージェントが用意できたので、Netflix のジャンルを分析するよう依頼してテストします。
まず、これまでどおりライブラリをインポートし、API キーを読み込み、クライアントを初期化します。
from dotenv import load_dotenv
from google import genai
import utils
load_dotenv()
client = genai.Client()次に、utils.load_or_create_agent() 関数を使って（初回でなければ読み込み）data-analyst エージェントを作成します。
data_analyst = utils.load_or_create_agent(client, "data-analyst")
print(f"Agent '{data_analyst.id}' initialized.")以降は、これまでと同じ方法でエージェントとやり取りできます。唯一の違いは、agent パラメータに antigravity-preview-05-2026 の代わりに自分のエージェントを指定する点です。
まず、matplotlib パッケージのインストールを依頼します。
inter1 = client.interactions.create(
agent=data_analyst.id,
input="Install the matplotlib package.",
environment="remote"
)環境はすでにエージェント側で構成済みのため、ファイルを提供する必要はありません。文字列 ”remote” を渡すだけで構いません。
次に、csv-aggregator ツールを使って Netflix のジャンル別データを分析し、最も視聴されたジャンルを可視化するよう依頼します。
inter2 = client.interactions.create(
agent=data_analyst.id,
input="Use the csv-aggregator to plot the top 10 genres from /workspace/repository/data/netflix.csv in terms of viewership",
environment=inter1.environment_id
)エージェントがその上で作業を継続できるよう、直前のやり取りの環境識別子を指定している点に注意してください。
最後に、前のステップで作成された genres.py スクリプト（SKILL.md がこのスクリプトの作成を指示）を実行して、データをプロットするよう依頼します。
inter3 = client.interactions.create(
agent=data_analyst.id,
input="Execute the genres.py script using python.",
environment=inter2.environment_id
)このやり取りの後、プロットが作成されているはずです。環境をダウンロードしてローカルに取得します。
utils.download_env(inter3.environment_id)結果は次のとおりです。
エージェントとのやり取りの完全なコードは、analyze_netflix_genres.py にあります。
まとめ
サンドボックスを用意するために複雑なクラウドコンピューティング基盤に依存せず、1 回の API 呼び出しで高度なエージェントを作成できるのは非常に強力です。これにより、エージェントの実行環境を気にせず、強力なエージェントを容易に作成できます。
本チュートリアルでは、Gemini マネージドエージェントの基礎を扱いましたが、真に複雑なエージェントは作成していません。ぜひさらに掘り下げ、この基盤の上に構築を続けてスキルを磨いてください。