Gemini 3 Flash と AlloyDB AI を使用して自律型サプライチェーンを構築する

1. 概要

「読み取り専用チャットボット」の時代は終わりを迎えつつあります。エージェントビジョンの時代が到来しています。

この Codelab では、推測しない AI システムを構築するプラクティスである決定論的 AI エンジニアリングを実装します。標準の AI モデルは、複雑な画像内のアイテムの数を尋ねられると、しばしば「ハルシネーション」（推測）します。サプライチェーンでは、推測は危険です。AI が 12 個のアイテムがあると推測したときに、実際には 15 個のアイテムがある場合、コストのかかるエラーが発生します。

Gemini 3 Flash の新しい Think, Act, Observe ループを活用して、自律型サプライチェーンエージェントを構築します。単に調べるだけでなく、調査も行います。

決定論的アーキテクチャ

まず、「ブラインド」システムと「健忘症」システムから始めます。感覚を 1 つずつ手動で「目覚め」させます。

目（Vision エージェント）: コード実行で Gemini 3 Flash を有効にします。モデルは、トークンを予測して数値を推測するのではなく、Python コード（OpenCV）を記述してピクセルを決定論的にカウントします。
メモリ（サプライヤーエージェント）: ScaNN（Scalable Nearest Neighbors）で AlloyDB AI を有効にします。これにより、エージェントは数ミリ秒で数百万のオプションの中から部品の正確なサプライヤーを特定できます。
ハンドシェイク（A2A プロトコル）: 標準化された agent_card.json を使用してエージェント間通信を可能にし、Vision Agent が Supplier Agent に自律的に在庫を注文できるようにします。

作成するアプリの概要

カメラフィードで「視覚的数学」を実行する Vision Agent。
高速ベクトル検索用の AlloyDB ScaNN を基盤とするサプライヤーエージェント。
自律ループを可視化するリアルタイム WebSocket 更新を備えた Control Tower フロントエンド。

学習内容

Gemini API を使用して gemini-3-flash-preview で Agentic Vision を有効にする方法。
AlloyDB で <=>（コサイン距離）演算子を使用してベクトル検索を実装する方法。
Auth Proxy を使用して Cloud Shell を AlloyDB にブリッジする方法。

要件

ブラウザ（Chrome、Firefox など）
課金を有効にした Google Cloud プロジェクト
Vision エージェント用の Gemini API キー（Google AI Studio で無料枠を利用可能）。

2. 始める前に

プロジェクトを作成する

Google Cloud コンソールのプロジェクト選択ページで、Google Cloud プロジェクトを選択または作成します。
Cloud プロジェクトに対して課金が有効になっていることを確認します。詳しくは、プロジェクトで課金が有効になっているかどうかを確認する方法をご覧ください。

Google Cloud 上で動作するコマンドライン環境の Cloud Shell を使用します。Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします。

[Cloud Shell をアクティブにする] ボタンの画像

Cloud Shell に接続したら、次のコマンドを使用して、すでに認証済みであることと、プロジェクトがプロジェクト ID に設定されていることを確認します。

gcloud auth list

これを探してた！

これで、ワンクリックセットアップの準備が整いました。次のセクションでは、以下の内容について説明します。

Cloud Shell を自動的に開く
リポジトリのクローンを作成する
インタラクティブなチュートリアルで設定全体を説明します

3. Cloud Shell でのワンクリック設定

設定は、ガイド付き Cloud Shell チュートリアルにまとめられています。インフラストラクチャのプロビジョニング、AlloyDB の設定、Auth Proxy の構成、データベースのシード設定など、すべてが自動化されています。

Cloud Shell チュートリアルを起動する

⚠️ 重要 - クリックする前に: 下のボタンをクリックすると、[Cloud Shell で開く] を求めるセキュリティダイアログが表示されます。これは、リポジトリのクローンの前に表示されます。

以下を行ってください:

✅ [Trust repo] のチェックボックスをオンにします。
✅ [確認] をクリックします。

これがないと、リポジトリはクローンされません。

準備ができたらクリックして、手順に沿ったチュートリアルでプロジェクトを開きます。

今後の流れ:

リポジトリが事前にクローンされた状態で Cloud Shell が開く
右側にチュートリアルパネルが表示され、手順が表示されます
次の手順が表示されます。

Gemini API キーを取得する（無料枠あり）
ターミナルで GCP プロジェクトを設定する
設定を実行しています（API の確認、必要に応じて有効化、AlloyDB のプロビジョニング: 約 15 分）
2 つのキーコードを変更する（ビジョンとメモリを有効にする）
エージェントカードの作成（A2A プロトコル）
すべてのサービスを開始する

このチュートリアルはインタラクティブです。各ステップに番号が付けられ、進捗状況が記録されます。

代替手段: 手動設定

手動で管理する場合:

Cloud Shell を開き、プロジェクトが設定されていることを確認する

gcloud config get-value project

必要に応じてプロジェクトを設定する

gcloud config set project YOUR_PROJECT_ID

リポジトリのクローンを作成する

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb

設定を実行する

sh setup.sh

セットアップスクリプトの画面上の手順に沿って操作します。

次のステップ: チュートリアルに沿って残りの手順を行います。完了したら、セクション 4 に進んで、内部で何が起こったのかを理解します。

4. 舞台裏: Auth Proxy とデータベースシーディング

問題: AlloyDB はプライベート VPC 内に存在します。Cloud Shell はその外にあります。直接接続はできません。

解決策: AlloyDB Auth Proxy は、Cloud Shell の 127.0.0.1:5432 から AlloyDB インスタンスへの安全な IAM 認証トンネルを作成します。インスタンスでパブリック IP が有効になっている場合、プロキシはそれを使用します。有効になっていない場合は、VPC のプライベート IP 経由で接続します。

setup.sh の処理内容

AlloyDB インスタンス（クラスタ、リージョン、プロジェクト）が自動検出された
すべての認証情報（GEMINI_API_KEY、DB_PASS、AlloyDB の詳細）を含む .env を作成しました
Auth Proxy をダウンロードして起動した（該当する場合は –public-ip を使用）
8 個のサンプル在庫部品と ScaNN インデックスでデータベースをシードしました

.env ファイルの準備ができました。以降の実行では、認証情報が自動的に読み込まれます。

動作確認

リポジトリのルートにいることを確認します。

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Auth Proxy が実行されていることを確認する

ps aux | grep alloydb-auth-proxy

作成されたもの

8 つのパーツと 768 次元のエンベディングを含む在庫テーブル
高速ベクトル検索用の ScaNN インデックス（idx_inventory_scann）

5. ステップ 1: メモリ（サプライヤーエージェント）

サプライヤーエージェントは、AlloyDB ScaNN を使用して数百万個の部品を記憶します。A2A サーバーとして起動し、ベクトルクエリを修正します。

監査: 記憶喪失

（プレースホルダ SQL を使用して）サプライヤーエージェントにクエリを実行すると、最も近い一致ではなく、最初に見つかった行が返されます。類似性の概念はありません。記憶喪失です。

サプライヤーエージェントを起動する

A2A サーバー（main.py）は agent_executor.py に委任します。これにより、プロトコルが inventory.py のビジネスロジックにブリッジされます。

pkill -f uvicorn #Kill all uvicorn processes

ステップ 1: エージェントディレクトリに移動する

cd agents/supplier-agent

ステップ 2: 依存関係をインストールする

pip install -r requirements.txt

ステップ 3: エージェントサーバーを起動する

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & は、サーバーをバックグラウンドで実行し、出力を抑制してターミナルを中断しないようにします。

ステップ 4: エージェントが実行されていることを確認する（起動後 2 ～ 3 秒待つ）

curl http://localhost:8082/.well-known/agent-card.json

想定される出力: エージェント構成を含む JSON（エラーなしで返される）

Real Semantic Embeddings

設定時に、Google Gen AI SDK の text-embedding-005 モデルを使用して生成された実際のセマンティックエンベディングがデータベースにシードされました。これにより、ランダムなベクトルではなく、正確な類似性マッチングが保証されます。シード処理では、並列エンベディング生成を使用して 13 個のサンプルアイテムに対して約 10 秒かかります。これにより、各部分の意味論的意味を捉えた意味のある 768 次元のベクトルが作成されます。

AlloyDB の寄り道: ScaNN を使用する理由

修正: <=> 演算子の実装

エージェントにはプレースホルダクエリが付属しています。ScaNN ベクトル検索を有効にする必要があります。

ステップ 1: 在庫ファイルを開く

cd agents/supplier-agent

ステップ 2: inventory.py で TODO を見つける

47 ～ 60 行付近にある find_supplier() 関数を探します。表示される項目

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

ステップ 3: プレースホルダ SQL を ScaNN ベクトル検索に置き換える

次の 2 行を削除します。

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

これを次のように置き換えます。

sql = """
SELECT part_name, supplier_name
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_vector,))

この機能の用途:

<=> は、PostgreSQL のコサイン距離演算子です。
ORDER BY part_embedding <=> %s::vector は、最も近い一致（距離が最小 = 意味が最も近い）を検索します。
%s::vector は、エンベディング配列を PostgreSQL のベクトル型にキャストします。
LIMIT 1 は最も近い一致のみを返します
ScaNN インデックスは、このクエリを自動的に高速化します。

ステップ 4: ファイルを保存する（Ctrl+S または Cmd+S）

これで、エージェントはランダムな結果を返すのではなく、セマンティック検索を使用するようになります。

確認

A2A 検出とインベントリをテストします。

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

期待される結果: agent-card.json がエージェントカードを返します。Python スニペットは、シードされたデータから部品とサプライヤーを返します。

6. ステップ 2: 目（Vision エージェント）

データベースにアクセスできるようになったら、Gemini 3 Flash を使用して目を覚ましましょう。Vision エージェントは、Code Execution を介して「ビジュアル計算」を実行します。A2A サーバー（main.py）は agent_executor.py に委任し、agent_executor.py は Gemini 分析のために agent.py を呼び出します。

監査: ハルシネーション

標準のマルチモーダルモデルに「この散らかった画像には箱がいくつありますか？」と質問すると、画像は静的なスナップショットとして処理され、推測が行われます。

モデルの回答: 「12 個の箱が見えます。」
現実: 箱は 15 個あります。
結果: サプライチェーンの障害。

解決策: 思考 - 行動 - 観察ループを活性化する

コード実行と ThinkingConfig を有効にして、モデルが Python（OpenCV）を記述して確定的にカウントできるようにします。

agents/vision-agent/agent.py を開きます。
GenerateContentConfig セクションを見つけます。
thinking_config=types.ThinkingConfig(...) ブロックと tools=[types.Tool(code_execution=...)] の両方のコメントを解除します。
クライアントは、環境から GEMINI_API_KEY を使用するようにすでに構成されています。

ファイル: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="LOW",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

thinking_level="LOW" に設定する理由

この特定のタスク（コード実行によるアイテムのカウント）では、「低」で十分な推論予算が提供されます。

Python スクリプトの構造を計画する
使用する画像処理アプローチを決定する
カウントが境界ボックスの数と一致していることを確認する

「HIGH」を使用すると、決定論的タスクの精度が向上することなく、レイテンシとコストが 2 ～ 3 倍になります。複雑なマルチステップの推論（「このサプライチェーンの混乱を分析し、3 つの代替サプライヤーを理由とともに推奨してください」）。

費用対効果の最適化は、本番環境の AI エンジニアリングの重要なスキルです。推論の深さとタスクの複雑さを一致させます。

Vision エージェントを起動する

🔄 パスを確認: まだ agents/supplier-agent/ にいる場合は、まず cd ../.. でリポジトリのルートに戻ります。

ステップ 1: ビジョンエージェントディレクトリに移動する

cd agents/vision-agent

ステップ 2: 依存関係をインストールする

pip install -r requirements.txt

ステップ 3: ビジョンエージェントサーバーを起動する

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

> /dev/null 2>&1 & は、サーバーをバックグラウンドで実行し、出力を抑制してターミナルを中断しないようにします。

確認

A2A 検出のテスト:

curl http://localhost:8081/.well-known/agent-card.json

想定される結果: エージェントの名前とスキルを含む JSON。ステップ 8 で、Control Tower UI を使用して実際のビジョンカウントをテストします。

7. ステップ 3: ハンドシェイク（A2A エージェントカード）

エージェントは問題を確認し（Vision）、サプライヤーを把握しています（Memory）。A2A プロトコルにより、動的検出が可能になります。フロントエンドは、各エージェントのカードを読み取ることで、各エージェントとの通信方法を学習します。

A2A と従来の REST API

Aspect	従来の REST	A2A プロトコル
エンドポイントの検出	構成内のハードコードされた URL	/.well-known/agent-card.json を介した動的
機能の説明	API ドキュメント（人間向け）	スキル（機械可読）
インテグレーション	サービスごとの手動コード	セマンティックマッチング: 「在庫検索が必要」→ スキルを検出
新しいエージェントが追加されました	すべてのクライアントの構成を更新する	構成不要 - 自動検出

実際のメリット: 従来のマイクロサービスでは、3 番目の「ロジスティクスエージェント」を追加する場合、その URL と API コントラクトを使用して Control Tower のコードを更新する必要があります。A2A を使用すると、Control Tower は自動的にエージェントを検出し、自然言語のスキル記述を通じてその機能を理解します。

そのため、A2A では、自律型システムのアーキテクチャパターンであるプラグアンドプレイエージェント構成が有効になっています。

解決策: エージェントカードを作成する

サプライヤーエージェントが何ができるかを定義する必要があります。

agents/supplier-agent/agent_card_skeleton.json を agents/supplier-agent/agent_card.json にコピーします。
ファイルを編集してプレースホルダを置き換えます。

変更前（スケルトン）:

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

変更後（編集後）:

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

サプライヤーエージェントを再起動して、新しいカードを読み込みます。

ステップ 1: 実行中のエージェントを停止する

pkill -f "uvicorn main:app.*8082"

ステップ 2: エージェントディレクトリに移動する

cd agents/supplier-agent

ステップ 3: エージェントを再度起動する

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & は、サーバーをバックグラウンドで実行し、出力を抑制してターミナルを中断しないようにします。

ステップ 4: 新しいエージェントカードを確認する（開始後 2 ～ 3 秒待つ）

curl http://localhost:8082/.well-known/agent-card.json

想定される出力: 名前、説明、スキルが入力された JSON。

8. ステップ 4: Control Tower

FastAPI と WebSockets を使用して Control Tower フロントエンドを実行します。A2A を介してエージェントを検出し、リアルタイム更新でフルループをオーケストレートします。

すべてのサービスを開始

すべてのサービスを開始する最も簡単な方法:

リポジトリのルートにいることを確認する

pwd  # Should end with: visual-commerce-gemini-3-alloydb

次の手順を行ってください。

sh run.sh

この単一のコマンドは次の処理を開始します。

AlloyDB Auth Proxy（実行されていない場合）
ポート 8081 の Vision エージェント
ポート 8082 のサプライヤーエージェント
ポート 8080 の Control Tower

すべてのサービスが初期化されるまで 10 秒ほど待ちます。

システムをテストする

Control Tower にアクセスする:

Cloud Shell ツールバーの [ウェブでプレビュー] ボタン（目のアイコン 👁️）をクリックします。
[ポート 8080 でプレビュー] を選択します。
Control Tower ダッシュボードが新しいタブで開きます。

デモを実行します。

右上: 接続ステータス（緑色の「ライブ」ドット）、デモモード/自動モードの切り替え、音声コントロール
中央: 画像のアップロードと分析の可視化を行うメインのワークフローキャンバス
サイドパネル（分析中に表示）: ワークフローのタイムライン（左）、進行状況の追跡とコードビューア（右）

オプション 1: クイックスタート（推奨）

ホームページに、サンプル画像を含む [クイックスタート] セクションが表示されます。
サンプル画像をいずれかクリックすると、分析が自動的に開始されます。
自律型ワークフローを確認する（約 30 ～ 45 秒）

オプション 2: 自分でアップロードする

倉庫や棚の画像（PNG、JPG、最大 10 MB）をドラッグ＆ドロップするか、クリックして参照します
[Initiate Autonomous Workflow] をクリックします。
4 ステージのパイプラインを観察する

現象:

エージェントの検出: A2A プロトコルのモーダルに、スキルとエンドポイントを含む Vision エージェントとサプライヤーエージェントのカードが表示されます
ビジョン分析: Gemini 3 Flash は、アイテムをカウントする Python コード（OpenCV）を生成して実行します。進行状況バーにサブステップが表示されます。検出されたアイテムに境界ボックスがオーバーレイ表示されます。結果バッジに「✓ コード検証済み」または「~ 推定」が表示される
サプライヤーマッチング: AlloyDB ScaNN ベクトル検索のアニメーション。検索クエリの表示（例: 「工業用金属ボックス」など）。一致した部品、サプライヤー、信頼性スコアが結果カードに表示される
注文完了: 注文 ID、数量、詳細が記載された領収書カード

ヒント: プレゼンテーションの各段階で一時停止するには、デモモードをオン（右上）のままにします。AUTO モードでは、ワークフローは継続的に実行されます。

What Just Happened

Control Tower は A2A プロトコルを使用して、/.well-known/agent-card.json 経由で両方のエージェントを検出し、ビジョン分析（コード実行を伴う Gemini 3 Flash）をオーケストレートし、ベクトル検索（AlloyDB ScaNN）を実行し、自律的な注文を行いました。これらはすべて、リアルタイムの WebSocket 更新で行われました。各エージェントは A2A 標準を介して機能を公開するため、カスタム SDK を使用せずにプラグアンドプレイ構成が可能になります。詳細: A2A プロトコル

トラブルシューティング

パス関連のエラー:

コマンド実行時に「No such file or directory」と表示される: リポジトリのルートにいません。

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

サービスエラー:

「Address already in use」: 前回の実行のプロセスがまだアクティブです。

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

サービスが起動しない: ポートが占有されているかどうかを確認します。

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

AlloyDB への「接続拒否」: Auth Proxy が実行されていることを確認します。

ps aux | grep alloydb-auth-proxy

AlloyDB 接続の問題:

「Connection to server at 127.0.0.1, port 5432 failed」と表示された場合:

127.0.0.1 のポート 5432 でサーバーへの接続に失敗したというメッセージが表示された場合:

Auth Proxy を確認する: ps aux | grep alloydb-auth-proxy
パブリック IP が有効になっていることを確認する: gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
ローカル開発の場合（Cloud Shell 以外）:
問題: Cloud Shell は自動的に動作するが、ローカルマシンには承認済みネットワークが必要
解決策: sh setup.sh を再実行し、プロンプトが表示されたらオプション 1（0.0.0.0/0 を承認）を選択します。
セキュリティに関する注: 0.0.0.0/0 を使用する場合でも、接続には次のものが必要です。
有効な GCP 認証情報（アプリケーションのデフォルト認証情報）
データベースパスワード
mTLS 暗号化（Auth Proxy が処理）

9. クリーンアップ

料金が発生しないようにするには、自動クリーンアップスクリプトを使用してすべてのリソースを破棄します。

# From repo root
sh cleanup.sh

この操作を行うと、以下のものが安全に削除されます。

AlloyDB クラスタ（主な費用要因）
Cloud Run サービス（デプロイされている場合）
関連付けられたサービスアカウント

スクリプトは、削除前に確認を求めるプロンプトを表示します。

10. リファレンスとその他の資料

この Codelab の技術的な主張はすべて、Google Cloud と Google AI の公式ドキュメントで検証されています。

正式なドキュメント

Gemini 3 Flash:

Code Execution API: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
デベロッパーガイド: https://ai.google.dev/gemini-api/docs/gemini-3
モデルのドキュメント: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
モデルカード: https://deepmind.google/models/gemini/flash/

AlloyDB AI と ScaNN:

ScaNN パフォーマンスベンチマーク: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
ScaNN インデックスについて: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
AlloyDB AI の詳細: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
チューニングのベストプラクティス: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
AlloyDB のドキュメント: https://cloud.google.com/alloydb/docs

料金に関する情報:

Gemini API の料金: https://ai.google.dev/gemini-api/docs/pricing
AlloyDB の料金: https://cloud.google.com/alloydb/pricing
Vertex AI の料金: https://cloud.google.com/vertex-ai/pricing

Verified Performance Claims

機能	申請する	ソース
ScaNN と HNSW（フィルタ付き）	10 倍高速	Google Cloud Blog（確認済み）
ScaNN と HNSW（標準）	4 倍高速	Google Cloud Blog（確認済み）
ScaNN のメモリ使用量	3 ～ 4 倍小さい	Google Cloud Blog（確認済み）
ScaNN インデックスの構築時間	8 倍高速	Google Cloud Blog（確認済み）
コード実行のタイムアウト	最大 30 秒	Google Cloud ドキュメント（確認済み）
コード実行ファイル I/O	サポート対象外	Google Cloud ドキュメント（確認済み）
Temperature=0 の動作	決定論的出力	コミュニティ確認済み

参考情報

Agent-to-Agent（A2A）プロトコル:

A2A はエージェントの検出と通信を標準化します
/.well-known/agent-card.json で提供されるエージェントカード
自律型エージェントのコラボレーションに関する新しい標準

ScaNN の研究:

12 年間の Google Research に基づく
数十億規模の Google 検索と YouTube を強化
一般提供開始: 2024 年 10 月
数百万から数十億のベクトルに適した初の PostgreSQL ベクトルインデックス

11. チャレンジモード: エージェントのスキルをレベルアップする

自律型サプライチェーンを構築しました。さらに詳しく見ていきましょう。これらのチャレンジでは、学習したパターンを新しい問題に適用します。

チャレンジ 1: 画像ベースの検索（マルチモーダルエンベディング）

現在のフロー: Vision エージェントがアイテムをカウント → テキストクエリを生成 → サプライヤーエージェントがテキストをエンベディング → AlloyDB を検索

課題: テキストを完全にバイパスし、切り抜いた画像をサプライヤーエージェントに直接送信します。

ヒント:

Vision Agent のコード実行により、棚の画像から個々のアイテムを切り抜くことができる
Vertex AI の multimodalembedding@001 モデルは画像を直接埋め込むことができます
テキストではなく画像バイトを受け入れるように inventory.py を変更する
A2A スキルの説明を「Accepts: image/jpeg or text」と表示するように更新

重要性: 外観が複雑な部品（色のバリエーション、損傷、パッケージの違い）の場合、画像検索の方が正確です。

チャレンジ 2: 可観測性 - 透明性による信頼

現在の状態: システムは機能しているが、内部を確認できない

課題: AlloyDB のクエリログを調べて、ベクトル検索が実行されていることを確認します。

手順:

Query Insights は、AlloyDB でデフォルトで有効になっています。確認するには、次のコマンドを実行します。

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

UI でサプライヤー検索を実行する
実行された実際の SQL を表示します。

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

想定される出力: 実行時間とともに、ORDER BY part_embedding <=> $1::vector LIMIT 1 クエリが表示されます。

重要性: 可観測性は信頼を構築します。ステークホルダーから「このエージェントはどのように意思決定を行うのですか？」と質問された場合は、出力だけでなくクエリプランも提示できます。

課題 3: マルチエージェントの構成

課題: 倉庫の所在地と商品の重量に基づいて送料を計算する 3 番目のエージェント（ロジスティクスエージェント）を追加します。

アーキテクチャ:

Vision エージェントの出力: アイテム数
サプライヤーエージェントの出力: サプライヤーの所在地
ロジスティクスエージェント（新規）の入力: 配送先、重量 → 出力: 送料 + 到着予定日

ヒント: A2A プロトコルを使用すると、これは簡単です。calculate_shipping スキルを含む新しいエージェントカードを作成します。Control Tower はこれを自動的に検出します。

学習するパターン: これは、エージェント指向アーキテクチャの中核です。つまり、小さなコンポーザブルスペシャリストから構築された複雑なシステムです。

12. まとめ

生成 AI から Agentic AI への移行が完了しました。

構築した内容:

ビジョン: 「推測」をコード実行（API キー経由の Gemini 3 Flash）に置き換えました。
メモリ: 「遅い検索」を AlloyDB ScaNN（GCP 経由）に置き換えました。
対応: 「API 統合」を A2A プロトコルに置き換えました。

ハイブリッドアーキテクチャのメリット:

この Codelab では、ハイブリッドアプローチについて説明しました。

Vision Agent: Gemini API（API キー）を使用 - シンプル、無料枠あり、GCP の課金は不要
サプライヤーエージェント: GCP（Vertex AI + AlloyDB）を使用 - エンタープライズグレード、コンプライアンス対応

これが自律型経済のアーキテクチャです。コードはそのままお使いいただけます。

次のステップ

Gemini 3 Flash と AlloyDB AI を使用して自律型サプライ チェーンを構築する

1. 概要

決定論的アーキテクチャ

作成するアプリの概要

学習内容

要件

2. 始める前に

プロジェクトを作成する

これを探してた！

3. Cloud Shell でのワンクリック設定

Cloud Shell チュートリアルを起動する

代替手段: 手動設定

4. 舞台裏: Auth Proxy とデータベース シーディング

setup.sh の処理内容

動作確認

作成されたもの

5. ステップ 1: メモリ（サプライヤー エージェント）

監査: 記憶喪失

サプライヤー エージェントを起動する

Real Semantic Embeddings

AlloyDB の寄り道: ScaNN を使用する理由

修正: <=> 演算子の実装

確認

6. ステップ 2: 目（Vision エージェント）

監査: ハルシネーション

解決策: 思考 - 行動 - 観察ループを活性化する

Vision エージェントを起動する

確認

7. ステップ 3: ハンドシェイク（A2A エージェント カード）

A2A と従来の REST API

解決策: エージェント カードを作成する

8. ステップ 4: Control Tower

すべてのサービスを開始

システムをテストする

What Just Happened

トラブルシューティング

9. クリーンアップ

10. リファレンスとその他の資料

正式なドキュメント

参考情報

11. チャレンジ モード: エージェントのスキルをレベルアップする

チャレンジ 1: 画像ベースの検索（マルチモーダル エンベディング）

チャレンジ 2: 可観測性 - 透明性による信頼

課題 3: マルチエージェントの構成

12. まとめ

Gemini 3 Flash と AlloyDB AI を使用して自律型サプライチェーンを構築する

4. 舞台裏: Auth Proxy とデータベースシーディング

5. ステップ 1: メモリ（サプライヤーエージェント）

サプライヤーエージェントを起動する

7. ステップ 3: ハンドシェイク（A2A エージェントカード）

解決策: エージェントカードを作成する

11. チャレンジモード: エージェントのスキルをレベルアップする

チャレンジ 1: 画像ベースの検索（マルチモーダルエンベディング）