1. はじめに
この Codelab では、Google の Agent Development Kit（ADK）と Gemini を使用して、初めての AI エージェントを段階的に構築します。推論と行動の基本コンセプトを示す、コンテンツを計画して作成する基本的なブログ作成エージェントを作成します。
演習内容
- ADK の開発環境を設定する。
- プランナーとライターを使用してマルチエージェント システムを作成する。
- エージェントをローカルで実行し、ADK ウェブ UI を介してエージェントとやり取りする。
必要なもの
- ウェブブラウザ（Chrome など）。
- マシンにインストールされた Python 3.10 以降。
- Google AI Studio API キー。
この Codelab は、初心者を含むあらゆるレベルのデベロッパーを対象としています。
所要時間: 30 分。
2. ビジュアル ガイド: AI エージェントとは
構築を開始する前に、AI エージェントとは何か、また AI エージェントが従う一般的なパターンについて簡単に説明します。
AI エージェントとは何ですか？
最もシンプルなレベルでは、エージェントは単に回答するだけでなく、決定して行動できるソフトウェアです。従来型のチャットボットのように単一のレスポンスを生成するのではなく、リクエストを確認して、実行する手順を把握し、API を呼び出してコードを実行し、結果を確認してから、次のアクションを決定します。
最も明確な説明の 1 つは、研究論文「 ReAct: Synergizing Reasoning and Acting in Language Models 」に記載されています。この論文のアイデアはシンプルですが強力です。言語モデルはテキストを一度に生成するだけではありません。実際には、ステップごとに推論し、ツールや API の呼び出しなどのアクションを実行し、結果を観察してから、次のアクションを決定できます。
推論、行動、観察、調整のサイクルは、最新の AI エージェントの動作の基盤となります。また、Google Cloud の定義とも一致しています。推論、計画、メモリーを備え、ユーザーに代わって適応して意思決定を行うのに十分な自律性を備えたシステムです。
3 つのエージェント動作パターン
すべてのエージェントが同じように動作するわけではありません。エージェントは、次の 3 つの広範なパターンで考えることができます。
- シーケンシャル エージェント: 組み立てラインのようにステップごとに実行されます。ステップ 1、ステップ 2、ステップ 3 の順に実行されます。予測可能ですが、柔軟性はありません。
- リアクティブ エージェント: 瞬時に判断を下します。現在の状態を確認して、「次に何をすべきか」を尋ねます。ツール A を使用したり、ツール B を使用したりします。柔軟性がありますが、事前に計画することはありません。
- 熟慮型エージェントまたはプランニング エージェント: 一時停止して計画をスケッチしてから実行します。旅行の予約について考えてみましょう。フライトをランダムに購入するのではなく、日付やホテルを選択し、手順を並べてから実行します。
どれが「正しい」ですか？問題によって異なります。単純で予測可能なフローの場合は、シーケンシャルで問題ありません。動的なタスクの場合は、リアクティブの方が適しています。依存関係のある複数ステップの目標の場合は、プランニング エージェントを使用します。
このラボでは、最初にアウトラインを作成してからブログ投稿を作成する熟慮型/プランニング エージェントを構築します。
3. 始める前に
Google Cloud アカウントとプロジェクトを作成する
このラボで後ほどエージェントを Google Cloud Run にデプロイするには、Google Cloud アカウントと課金が有効になっているプロジェクトが必要です。
- Google Cloud コンソールにログインします。新しいプロジェクトを作成するか、既存のプロジェクトを再利用します。お持ちでない場合は、Google アカウントを作成する必要があります。
- 次に、Cloud のリソースを使用するために、Cloud コンソールで課金を有効にする必要があります。この Codelab の操作をすべて行っても、費用は数セント未満です。Google Cloud の新規ユーザーは、300 米ドル分の無料トライアル プログラムをご利用いただける場合があります。
- プロジェクト ID （すべての Google Cloud プロジェクトで一意の名前）をメモします。エージェントを構成してデプロイするために必要になります。
Google AI Studio API キーを取得する
Gemini モデルを使用するには、Google AI Studio の API キーが必要です。
- Google AI Studio に移動します。
- [API キーを取得] をクリックします。
- 新しいキーを作成するか、既存のキーを使用します。後で使用するためにキーをコピーします。
4. ブログ作成エージェント プロジェクトの構造を作成する
このステップでは、ローカルマシンにブログ作成エージェントのコードを格納するディレクトリとファイルを設定します。
1. ブログ作成エージェントのワークスペースを作成する
ターミナルを開き、次のコマンドを実行して、ブログ作成エージェント専用のディレクトリを作成して移動します。
mkdir bloggeragent
cd bloggeragent
2. エージェント ファイルを初期化する
Google ADK フレームワークは、プロジェクト ディレクトリからエージェント ワークフローを直接読み込みます。bloggeragent のルートに直接必要なファイルを作成します。
touch requirements.txt .env __init__.py agent.py
5. 依存関係をインストールして環境を設定する
このステップでは、Python 仮想環境を設定し、Google ADK フレームワークをインストールして、Gemini モデルでブログエージェントを認証するための環境変数を構成します。
1. エージェントの要件を構成する
bloggeragent ディレクトリで requirements.txt
ファイルを開き、ブログ作成エージェントに必要なパッケージを指定します。そのためには、次のコードを追加します。
google-adk==2.2.0
python-dotenv
2. エージェントの仮想環境を作成する
bloggeragent ディレクトリから、Python 仮想環境を作成して有効にし、エージェントのパッケージを分離します。
python3 -m venv .venv
source .venv/bin/activate
3. ADK フレームワークをインストールする
requirements.txt で定義された依存関係をインストールして、ローカル ワークスペースに Google ADK をインストールします。
pip install -r requirements.txt
4. エージェント API 認証情報を構成する
プロジェクト ルートに作成した .env ファイルを開き、Gemini API キーを追加します。
GOOGLE_API_KEY=your_api_key
your_api_key は、Google AI Studio からコピーしたキーに置き換えます。
6. マルチエージェント ブログ作成ツールを構築する
このステップでは、ブログ作成エージェント システムのコア ワークフローを実装します。
単純な単一プロンプトのチャットボットではなく、自己修正ループとアウトライン検証を使用して高品質の技術投稿を作成する複雑なマルチエージェント システムを構築します。これは、先ほど説明した熟慮型/プランニング パターンに従います。
アーキテクチャの概要
システム内のスペシャリスト エージェントは次のように連携します。
init.py を構成する
テキスト エディタで __init__.py を開き、次のインポートを追加して、エージェント ワークフローをランナーに公開します。
from . import agent
ブログ作成エージェントのワークフローを記述する
コードエディタで agent.py を開き、プランナー、ライター、検証チェッカー、メインのブログ作成エージェントを定義する次のコードを追加します。
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
エージェント アーキテクチャについて
マルチエージェントのプランニングと作成のワークフローを実装する方法を理解するために、agent.py に追加したコードの主なコンポーネントを分解してみましょう。
1. BlogPlanner サブエージェント
blog_planner エージェントは、コンテンツのプランニングを担当します。ユーザーが指定したトピックを受け取り、Markdown
で構造化されたアウトライン（タイトル、導入、4 ～ 6 個のセクション、結論）を生成します。アウトラインは、キー "blog_outline"
で共有状態ディクショナリに保存されます。
2. OutlineValidationChecker
OutlineValidationChecker エージェントは品質ゲートとして機能します。状態の
"blog_outline" を確認します。アウトラインが有効な場合は、"ok"
で応答します。それ以外の場合は、不足しているもののリストとともに "retry" を返します。
3. RobustBlogPlanner ループ
エージェントが不適切なアウトラインを生成しないように、プランナーと検証チェッカーを robust_blog_planner という LoopAgent
でラップします。検証に失敗して "retry" が返された場合、ループはプランナーを自動的に最大 3
回実行し、次のステージに進む前に自己修正を行います。
4. BlogWriter サブエージェント
アウトラインが確定すると、blog_writer エージェントは状態から "blog_outline"
を読み取り、アウトラインの構造に合わせてソフトウェア エンジニア向けに調整された完全な技術記事を Markdown で生成します。
5. BlogPostValidationChecker と RobustBlogWriter ループ
アウトラインと同様に、最終的な記事は BlogPostValidationChecker
によって検証され、すべての重要なセクションが存在し、明確であることを確認します。ライターとチェッカーは robust_blog_writer
ループでラップされ、チェッカーが問題を検出した場合に最大 3 回自己修正できます。
6. ループをツールとして公開する
AgentTool を使用して、プランナー ループ（robust_blog_planner）とライター
ループ（robust_blog_writer）をツール（planner_tool と writer_tool）としてラップします。これにより、他のエージェントはこれらの複雑なワークフローをシンプルなツールのように呼び出すことができます。
7. Blogger ルート エージェント
root_agent（Blogger という名前）は、ワークフロー全体をオーケストレートします。トピックが指定されると、次の手順で処理されます。
planner_toolを呼び出して、検証済みのアウトラインを生成します。writer_toolを呼び出して、そのアウトラインに基づいて下書きを作成します。- 最後に、3 つの代替タイトルと 2 つのツイート フックを生成します。
このマルチエージェント ループ アーキテクチャにより、LLM の書式設定や構造上の誤りをキャッチして修正してからユーザーに出力することで、信頼性を確保できます。
7. エージェントを実行してテストする
エージェントの動作を確認しましょう。
1. ADK ウェブ UI を起動する
ターミナルで bloggeragent プロジェクトのルート ディレクトリに移動し、仮想環境が有効になっている（source .venv/bin/activate）ことを確認してから、ウェブ インターフェースを起動します。
adk web
2. エージェントとやり取りする
- ブラウザを開き、
http://127.0.0.1:8000（または指定したポート）に移動します。 - ADK ウェブ UI に
Bloggerエージェントが読み込まれ、そのビジュアル レイアウトが表示されます（Blogger ルート エージェントが RobustBlogPlanner ツールと RobustBlogWriter ツールを指しています）。
- メッセージ ボックスに技術的なトピックを入力して、Enter キーを押します。エージェントの評価に使用できるテスト プロンプトをいくつかご紹介します。
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- UI で実行トレースを確認します。
BlogPlannerがアウトラインを作成し、OutlineValidationCheckerが検証し、BlogWriterがアウトラインに基づいて最終的な下書きを作成します:
8. Cloud Run にデプロイする
エージェントがローカルで動作することを確認したので、他のユーザーが使用できるように Google Cloud Run にデプロイしましょう。
Google Cloud Run はマネージド コンピューティング プラットフォームで、ウェブ リクエストまたは Pub/Sub イベント経由で呼び出し可能なステートレス コンテナを実行できます。
1. デプロイの前提条件
ブログ作成エージェントを Cloud Run にデプロイするには、ローカルマシンに Google Cloud CLI（gcloud）をインストールして認証する必要があります。
- Google Cloud CLI をインストールする: インストールしていない場合は、オペレーティング システム（macOS、Windows、Linux）用の Google Cloud CLI インストール ガイドの手順に沿ってインストールします。
- ローカル ターミナルを認証する: インストールしたら、ターミナルで次のコマンドを実行して Google Cloud アカウントにログインします。
gcloud auth login - 認証を確認する: アカウントに正常にログインし、Google Cloud リソースにアクセスできることを確認します。
gcloud auth list
2. Google Cloud プロジェクトを設定する
ターミナルでアクティブなプロジェクトを設定します。
gcloud config set project <YOUR_PROJECT_ID>
コンテナ化されたエージェントをビルドしてデプロイするために必要な Google Cloud サービスを有効にします。
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
ADK deploy コマンドは Google Cloud Build を使用してビルドプロセスを自動化するため、デフォルトの Compute サービス アカウントに Cloud Build を使用する権限を付与する必要があります。
次のコマンドを実行して、プロジェクト番号を確認します。
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
次のコマンドを実行して、必要な IAM ロールをバインドします（
- コンテナをビルドする権限を Cloud Build に付与します。
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- Gemini Enterprise へのアクセス権を付与して、デプロイされたエージェントが API キーを必要とせずに Gemini モデルを呼び出せるようにします。
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. ローカル環境変数を設定する
デプロイ コマンドを簡略化して入力ミスを防ぐため、ターミナル セッションでプロジェクト ID を環境変数として設定します。
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. ADK CLI を使用してデプロイする
ADK CLI には、エージェントを Cloud Run にデプロイするための合理化されたコマンドが用意されています。
仮想環境が有効になっていて、bloggeragent プロジェクト ディレクトリに移動していることを確認してから、デプロイ コマンドを実行します。
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
デプロイ プロセス中に、ターミナルに次の 2 つの質問が表示されます。
- リポジトリの作成を確認する:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Y」と入力して Enter キーを押します。 - 未認証のアクセスを許可する:
Allow unauthenticated invocations to [bloggeragent] (y/N)?
y」と入力して Enter キーを押します（これにより、ブラウザで ADK ウェブ UI に公開アクセスできます）。
5. デプロイされたエージェントにアクセスする
デプロイが完了すると、コマンドから URL が出力されます。その URL をブラウザで開いて、公開アクセス可能なライブ ADK ウェブ UI にアクセスします。
9. クリーンアップ
Google Cloud アカウントに継続的に課金されないようにするには、この Codelab で作成したリソースを削除します。
1. Cloud Run サービスを削除する
デプロイされた bloggeragent サービスを削除します。
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. Artifact Registry リポジトリを削除する
ビルドされたコンテナ イメージを保存するために作成した Docker リポジトリを削除します。
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. ローカル サーバーを停止する
ローカル ADK サーバーを停止するには、実行中のターミナルで CTRL+C を押して、仮想環境を無効にします。
deactivate
10. 完了
おめでとうございます！Google の ADK と Gemini を使用して、初めての AI エージェントを構築しました。
学習した内容
- AI エージェントの基本コンセプト（推論と行動）。
- Google ADK を使用してマルチエージェント システムを構築する方法。
- ウェブ UI を使用してエージェントを実行してテストする方法。
次のステップ
- エージェントにツール（ウェブ検索や API 呼び出しなど）を追加してみる。
- MCP サーバーを統合する動画 2 をご覧ください。