公開日: 2026年5月17日 00:00 更新日: 2026年5月17日 15:00

tech

【Google Cloud / ADK】マルチエージェント・システムを構築するラボのレビュー【Skills Boost / GENAI106】

#Google Cloud
#Skills Boost
#ADK
#Agent Development Kit
#Gemini
#Vertex AI
#生成AI
#マルチエージェント

はじめに

Google Cloud Skills Boost のハンズオーンラボ 「ADK を使用してマルチエージェントシステムを構築する」（ラボ ID GENAI106、目安 1 時間 30 分・クレジット 5・上級）を完了したので、レビュー兼学びの整理として記事にします。

前提となるラボは公式のとおり、次の内容を済ませておく想定です。

Google Agent Development Kit（ADK）を使ってみる
ツールで ADK エージェントを強化する

エージェント定義の全体像やマルチエージェントの考え方は、公式の Agent Development Kit（ADK）ドキュメント が基準になります。Python の Agent / LlmAgent や instruction の書き方は Get started / About ADK の説明と、トップページのコード例と同じ流儀です。

ラボ（カタログへの入口）

Build Multi-Agent Systems with ADK（Focus）

※ 手順のスクショ付きマニュアル全文は著作権の関係で転載していません。実習は上記公式ラボを利用してください。

ラボのゴール（何ができるようになるか）

ラボで扱う主なトピックは次のとおりです。

複数エージェントを定義し、親エージェントとサブエージェントの関係でつなぐ
複数ターン・複数エージェントにまたがる情報を、**セッションの状態（state）**に書き込み、後続の応答の文脈に使う
状態から値を読み出す（キー・テンプレート、output_key など）
ワークフローエージェント（Sequential / Loop / Parallel）で、エージェント間の処理順・反復・並列を制御する

「1 つの巨大プロンプト」ではなく、役割分割した状態機械に近い形でマルチステップの挙動を組み立てる、というのが大きなメリットの説明でした（設計しやすさ、保守、モジュール性など）。

レビュー：階層エージェントとパス制御

root_agent とサブエージェント

会話は root_agent（ラボでは別名表示あり） から始まる
親エージェントは、各サブの description を踏まえて 会話をどのサブに引き渡すかを判断する、がデフォルトのイメージ
instruction でサブを名前で明示すると、転送ポリシーをより制御しやすい

ピア（兄弟）間の転送

あるサブエージェント上でユーザーの発話が進むと、別サブ（ピア）へ会話が移るケースがあり得る
ピア間転送を禁止したい場合は disallow_transfer_to_peers を使う、というパターンも紹介されていました

読み方のコツ（ラボ内のヒント）

サブを先に定義してから親に sub_agents=[...] でぶら下げるため、ファイルの下から上に読むと会話の流れに沿いやすい、というのは実際のコードリーディングでも有用だと感じました。

レビュー：セッション状態（Session state）

セッションと state の概念は公式 State: The session’s scratchpad にまとまっています（{key?} 形式や output_key の扱いもここで確認できます）。

各会話は Session に属し、関与するエージェントからアクセスできる
会話履歴に加え、state 辞書で「エージェント間で共有したい値」を保持できる

ツールから状態を更新

ツール関数に ToolContext を渡し、tool_context.state[...] を更新する例がありました（カスタム関数ツールの定義方針は公式の Function tools も参照）
ツール実行後に state_delta 的な変化がイベントに載るので、ADK Web UI から追いやすい

キーテンプレート

{ attractions? } のように、状態のキーから値を埋め込む記法（存在しなくても落ちにくい ? 付き）があり、instruction 内でリスト表示などに使えます

output_key

エージェント定義で output_key を指定すると、応答全文をそのキーで state に保存できる、という補足がありました（長文のやり取りを断片ではなく残したいときの選択肢）。

レビュー：ワークフローエージェント

SequentialAgent / LoopAgent / ParallelAgent の役割整理は、公式の Workflow agents に沿っています。ユーザー入力のたびに呼び分けるのではなく、「決まった工程を機械的に回す」用途向け、という整理がしっくりきました。

種類	役割のイメージ
SequentialAgent	サブを順番に実行。前段のアウトプットを次段の入力にするパイプライン向き
LoopAgent	繰り返し（改善ループ、批評と修正など）。`max_iterations` で上限を設けるのが推奨。終了には `exit_loop` など
ParallelAgent	サブを並列。互いに会話履歴や状態を直接共有しないデフォルト挙動の説明あり。実行時間短縮に効く

ラボ後半の 映画企画（調査→執筆→批評ループ→興行収入・キャスティング並列→ファイル出力） は、まさに上記の組み合わせのデモになっており、「クリエイティブ業務の比喩」と「書類ドラフト自動化の現実」の両方をイメージしやすい構成でした。

CustomAgent は今回手を動かさない前提で紹介のみでしたが、「組み込み3種で足りないときの拡張点」としてメモしておく価値があります。

ツール・実行環境まわりの所感

adk run で CLI から対話検証、**adk web** で 開発 UI（State タブ、イベントツリー）を見られるのが理解の助けになる（セットアップの入口は Get started（Quickstart））
Cloud Shell 利用時は --allow_origins で Cloud Shell origins を許可する手順がありました
コードを頻繁に直すなら --reload_agents があると便利、という話はローカル開発でも素直に転用できそうです
ポート 8000 が塞がっているときは --port 8001 などで回避、とも記載されていました

実務イメージ：SRE ナレッジや「他チームからの依頼」に ADK で寄せる構成（例）

所感・構成例の補足
以下はラボで得た「エージェント分割・状態・ワークフロー」の感覚を、読者の方が業務に結びつけやすいようにした あくまで例示 です。実装可否・データの持ち方・承認フロー・モデル利用ポリシーは、所属チームや企業のルール・セキュリティ方針・利用規約に必ず従ってください（個人情報や社外秘をプロンプトに流さない、本番は評価やガードレール設計とセット、など）。

例① SRE チームのナレッジ（Runbook / 障害対応メモ）に寄せる

狙い: 「一次切り分けが早くなる」「初見のオンデューターでも手順に沿って確認質問ができる」。

ADK らしい組み立て方（概念）

親エージェント（root_agent 相当）
- インシデント本文やメトリクス要約を受け取り、**カテゴリ（DB / ネットワーク / デプロイ / 認証 …）**を決め、会話の主導権をどのサブに渡すか決める。
- instruction で「必ず Runbook ID や根拠を述べる」「推測と事実を分ける」など、SRE の運用ルールを明示。
サブ：Runbook 検索・Q&A エージェント
- Function tool で社内の検索 API（例: ベクターストア、Confluence API、内部チケット）を呼ぶ。ツールの設計は Function tools。
- ツール結果を session.state に temp: や通常キーで残し、親が後続ターンで再利用（State）。
（必要なら）ワークフロー
- 「典型的な 5 分チェックリスト」を SequentialAgent で固定化（調査 → 採取スクリプト案 → まとめ）（Workflow agents）。
- 「原因候補の打ち消し」を LoopAgent（上限付き）で回す、などはラボの映画企画デモと同型の発想です。

例② インフラエンジニアへの「他チームからの依頼」受付

狙い: 「要件が曖昧なまま突っ込まない」「標準テンプレに沿った依頼書に近づける」「承認が要る旨を早めに返す」。

ADK らしい組み立て方（概念）

親：インテーク担当。依頼文から 環境（dev/stg/prod）・緊急度・影響範囲・期限 を state に書き出す（不足は質問）。
サブ①：ポリシー / 標準チェック
- ツールで「変更管理カタログ」「承認要否ルール」を参照（実体は DB やドキュメント検索）。
サブ②：下書き生成
- output_key で依頼テンプレのドラフトを state に保存し、人間が Jira / チャットに貼れる形に（output_key）。
ParallelAgent
- 「関連する過去チケット検索」と「リソース名の正規化」を並列、など 待ち時間短縮（ラボで説明されていた並列エージェントの旨味に一致）。

ローカルでのコーディング・環境設定（番号付き／Python 想定）

公式の Python Quickstart に沿った流れです。

Python 3.10+ と pip を用意する。
仮想環境を作る: python3 -m venv .venv → source .venv/bin/activate（Windows は公式手順どおり）。
ADK を入れる: pip install google-adk。
プロジェクト作成: adk create my_agent。生成物は次のような構成です（公式どおり）。
- my_agent/agent.py … root_agent が必須
- my_agent/.env … API キー等（チーム方針に合わせ、本番シークレットはローカル .env 直置き以外の方法を検討）
- my_agent/__init__.py
認証: Gemini API を使う場合、.env に GOOGLE_API_KEY（AI Studio / API Keys）を設定。Vertex AI 等に切り替える場合は Models & Authentication（公式のモデル・認証まとめ）を参照。
エージェント実装: agent.py に root_agent = Agent(...) を定義し、tools=[...] や sub_agents=[...] で階層化（ラボで触れたパターン）。
対話テスト:
- my_agent の 親ディレクトリで adk run my_agent（CLI）
- 同じく親ディレクトリで adk web --port 8000 → ブラウザで UI。ADK Web は開発・デバッグ専用との注意が公式にあります（同上 Quickstart の Caution）。
コードを頻繁に直すときは、ラボでも出てきた --reload_agents などでリロードしながら試すと快適です（運用ルールの許す範囲で）。

`agent.py` のイメージ（短い骨格・実行はしない擬似に近い例）

公式 Quickstart の Agent と ツール の形に寄せています（インポート名やクラス名は ADK のバージョンで多少違うことがあるため、必ず自環境とドキュメントを突き合わせてください）。

# my_agent/agent.py のイメージ（例）
from google.adk.agents.llm_agent import Agent


def search_internal_runbook(query: str) -> dict:
    """社内 Runbook を検索するツール（実装は検索 API / RAG ラッパーに置き換え）。"""
    # 返す dict は LLM が解釈しやすい形に（Function tools の慣習）
    return {"status": "ok", "snippets": [], "citations": []}


runbook_agent = Agent(
    model="gemini-flash-latest",
    name="runbook_specialist",
    description="社内 Runbook を検索し、根拠付きで短く答える。",
    instruction="日本語で簡潔に。ソース（ドキュメント ID 等）を明示する。",
    tools=[search_internal_runbook],
)

root_agent = Agent(
    model="gemini-flash-latest",
    name="sre_triage",
    description="インシデントの一次分類と次アクション案内。",
    instruction="まず影響と症状を整理。必要なら runbook_specialist に任せる。",
    sub_agents=[runbook_agent],
)

マルチファイルにしたい場合は、チームの Python パッケージ構成に合わせて import し、root_agent だけがエントリとして見えるようにすると運用しやすいです。

デプロイ・本番運用の考え方（番号付き）

ローカルや ADK Web で動いたコードを、どう本番に載せるかは公式 Deploying Your Agent が起点です。

開発・検証
- 機能要件に加え、**ログ・レート制限・権限（どのツールが何にアクセスできるか）**を固める。
- 可能なら **評価（オフライン / オンライン）**を設計（ラボ外だが本番では重要。公式トップの Evaluation ナビや組織内基準を参照）。
Google Cloud へ載せる主な選択肢（公式の整理）
- Agent Runtime（Agent Platform） … マネージド寄りのエージェント実行基盤
- Cloud Run … コンテナでスケール
- GKE … 細かな制御やオンモデル運用など
「コンテナにしてどこでも」
- 公式の Cloud Run 手順内に Dockerfile / FastAPI エントリの例への言及があります（Deploy → Cloud Run）。オンプレや別クラウド方針なら、チームのコンテナ標準に合わせて組み立てます。
本番のガバナンス
- 認証・ネットワーク境界・シークレット管理（Secret Manager 等）・監査ログは企業ポリシー優先。ADK のコード構造以前に、変更管理・データ分類・AI 利用申請の有無を確認してください。

工夫すると良さそうな点（ラボ本文にもあった注意）

サンプルはあくまで最小構成なので、各エージェントの instruction を具体化し、例示を増やすほど、本番に近い 安定性・再現性 は上がりそうです。評価（offline / online）とセットで考えると、さらに実務に近づくと感じました。

次にやりたいこと（個人メモ）

Evaluate 系（ADK エージェントの軌跡・ツール利用の評価）との接続を別ラボやドキュメントで掘る
Agent Engine へのデプロイラボと続けて実務イメージを固める
MCP と ADK の組み合わせ（別ラボ）まで踏んで、ツール境界の設計を整理する

（このブログ用メモ）アイキャッチ生成と `.env.local`

本リポジトリ（blog-for-kos）直下の .env.local に GEMINI_API_KEY または GOOGLE_API_KEY を置くと、npm run eyecatch:adk-lab が Gemini 画像 API を呼び出します（読み込みは .env の後に .env.local で上書き）。AI Studio の API キーが generativelanguage.googleapis.com 向けに有効で、かつ利用プラン・モデルが 画像生成に対応している必要があります。キーが無効や未対応の場合は グラデーション＋公式 Cloud ロゴのフォールバックが書き出されます。

参考リンク

さいごに

**「エージェントをツリーと状態で組む」**感覚が、文章だけでなく **実行・可視化（Web UI / イベントグラフ）**付きで体験できる良いラボでした。同系統を追う方の入口になれば幸いです。