• • 「データサイエンスエージェントでArtifactを使えるようにしてみた！（ローカル開発編）」の実装が完了していること。

• • Artifactを保存するためのGCSバケットが作成済みであること。

• • ローカルPCにgcloud CLIがインストールされていること。

• gcloudで認証したアカウントが、Artifactを保存するGCSバケットに対して適切なIAM権限を持っていること。

  • • 具体的には「ストレージ オブジェクト管理者」（roles/storage.objectAdmin）ロールがあれば、Artifactの作成、読み取り、削除が可能です。

ローカル編では、Artifactはエージェントが動作するコンテナのメモリ内に保存されていました。今回は、ADKのArtifactストレージ設定を変更し、その保存先をGCSバケットに向けます。

ユーザーからのリクエストフローは変わりませんが、tool_context.save_artifactが呼び出された際のバックエンドの動きがメモリへの書き込みからGCSへのAPIコールに切り替わります。これにより、エージェントが生成したSQLや画像は、堅牢でスケーラブルなGCSに永続的に保存されるようになります。

このアーキテクチャの最大の利点は、エージェントのロジック（tools.py）とインフラストラクチャ（保存先）が完全に分離されている点です。開発者は、Artifactをどこに保存するかを意識することなく、save_artifactを呼び出すだけで済みます。

まずは、ローカルでadk webコマンドを使ってエージェントを動かしながら、GCSへのArtifact保存を試す方法です。

1. 必要なライブラリのインストール

GCSと連携するために必要なクライアントライブラリをプロジェクトに追加します。ターミナルで、python/agents/data-scienceディレクトリに移動し、以下のコマンドを実行してください。

poetry add "google-cloud-storage<3.0.0"

2. gcloud CLIでの認証とADKの起動

ローカル環境からGCSに接続するための認証を行います。

まず、ターミナルで以下のコマンドを実行し、ご自身のGoogleアカウントで認証を行ってください。ブラウザが起動し、認証フローが開始されます。

gcloud auth application-default login

認証が完了すると、ADKを含むGoogle Cloudクライアントライブラリは、この認証情報を自動的に利用してGCSにアクセスします。

次に、ADKを起動します。このとき、–artifact_service_uriオプションに、gs://に続けてArtifactを保存するGCSバケット名を指定します。（data-scienceディレクトリで実行してください）

poetry run adk web --artifact_service_uri="gs://your-gcs-bucket-name"

3. 動作確認

ADKのWebコンソールが開いたら、ローカル編と同じプロンプトを試してみましょう。

Input: trainテーブルの日ごとの売上合計を取得し、その結果を可視化してください

エージェントの処理が完了した後、今度はADKのコンソールではなく、Google Cloudコンソールで指定したGCSバケットの中身を確認してください。以下のように、バケット内にdata_science/test_user/（セッションID）/のようなフォルダが作成され、その中に生成されたSQLファイルや分析結果イメージファイルが格納されたフォルダが保存されていれば、実装は大成功です！

ADKを使用してGCSにArtifactを保存する際、そのパス構造がどのようになっているか理解しておくと、より柔軟な活用が可能になります。tool_context.save_artifact() を呼び出すと、ADKはGCS上に以下のようなパス（オブジェクト名）を自動的に構築します。

gs://[バケット名]/[アプリ名]/[ユーザーID]/[セッションID]/[アーティファクト名]/[バージョン番号]

ここで重要なのは、save_artifactのnameパラメータで指定した名前（例: “generated_query.sql”）が、パスの中の[アーティファクト名]になる点です。GCSのコンソールでは、パスの区切り文字 / がフォルダとして解釈されるため、あたかも “generated_query.sql” という名前のフォルダが作成され、その中に 0, 1 といったバージョニングされたファイルが保存されているように見えます。

これは、ADKが個々のアーティファクトを「バージョン管理されたファイルの集合体」として扱っているための仕様です。同じ名前で複数回保存すると、バージョン番号が自動的にインクリメントされ、変更履歴がすべてGCS上に記録されます。これにより、エージェントによる分析プロセスの再現性と追跡可能性が担保されるのです。

このパス構造を理解していれば、例えば特定のセッションで生成されたすべてのアーティファクトを一覧したり、GCSイベント通知と連携して特定のアーティファクトが作成されたことをトリガーに後続処理を起動したりといった応用も容易になります。

次に、エージェントを本番環境であるAgent Engineにデプロイし、GCS連携を有効にする方法です。Agent Engine環境ではインメモリのArtifact Serviceが期待通りに動作しない場合があるため、GCSの利用が推奨されます。

ここでは、デプロイスクリプトを修正し、環境変数で挙動を制御できるようにします。

1. デプロイスクリプトの修正

python/agents/data-science/deployment/deploy.pyを修正し、環境変数に応じてArtifact Serviceを切り替えるロジックを追加します。これにより、デプロイ時にGCSを使うか、インメモリを使うかを選択できるようになります。

以下の内容でdeploy.pyを更新してください。

# python/agents/data-science/deployment/deploy.py



# ... (既存のimport文) ...

from google.adk.artifacts import (

    GcsArtifactService,

    InMemoryArtifactService,

)



# ... (中略) ...



def create(env_vars: dict[str, str]) -> None:

    """Creates and deploys the agent."""

    # --- Artifact Service Builder ---

    def artifact_service_builder():

        artifact_storage_type = os.getenv("ARTIFACT_STORAGE_TYPE")

        if artifact_storage_type == "gcs":

            bucket_name = os.getenv("ARTIFACT_GCS_BUCKET_NAME")

            if not bucket_name:

                raise ValueError(

                    "ARTIFACT_GCS_BUCKET_NAME must be set when"

                    " ARTIFACT_STORAGE_TYPE is 'gcs'"

                )

            logger.info(

                "Using GCS Artifact Service with bucket: %s", bucket_name

            )

            return GcsArtifactService(bucket_name=bucket_name)

        else:

            logger.info("Using In-Memory Artifact Service.")

            return InMemoryArtifactService()



    adk_app = AdkApp(

        agent=root_agent,

        artifact_service_builder=artifact_service_builder,

        enable_tracing=False,

    )

    

    # ... (以降の処理は同じ) ...



# ... (main関数内のenv_varsに以下を追加) ...

    env_vars["ARTIFACT_STORAGE_TYPE"] = os.getenv("ARTIFACT_STORAGE_TYPE")

    env_vars["ARTIFACT_GCS_BUCKET_NAME"] = os.getenv(

        "ARTIFACT_GCS_BUCKET_NAME"

    )

2. 環境変数の設定とデプロイ

デプロイに必要な情報をターミナルで環境変数に設定します。これにより、デプロイスクリプトがGCSをArtifactの保存先として認識するようになります。

YOUR_GCP_PROJECT_IDとYOUR_GCS_BUCKET_NAMEの部分は、ご自身の環境に合わせて書き換えてください。

# --- ご自身の環境に合わせて設定してください ---

export GOOGLE_CLOUD_PROJECT="YOUR_GCP_PROJECT_ID"

export ARTIFACT_STORAGE_TYPE="gcs"

export ARTIFACT_GCS_BUCKET_NAME="YOUR_GCS_BUCKET_NAME"

# --- 設定ここまで ---



# python/agents/data-science ディレクトリでパッケージングを実行

poetry build --format=wheel --output=deployment



# deployment ディレクトリに移動

cd deployment/



# デプロイを実行

poetry run python deploy.py --create

Agent Engine環境では、デプロイされたエージェントはその環境のサービスアカウントの権限を自動的に引き継いでGCSにアクセスするため、ローカル開発のように個別の認証設定は不要です。

3. デプロイしたエージェントの動作確認

デプロイが成功すると、ターミナルにリソース名が出力されます。このリソースIDを控えておきましょう。

Successfully created agent: projects/YOUR_GCP_PROJECT_ID/locations/us-central1/reasoningEngines/<リソースID>

次に、テスト用のスクリプトを実行して、デプロイしたエージェントが正しく動作し、GCSにArtifactを保存できるか確認します。控えておいたリソースIDを環境変数に設定してください。

export RESOURCE_ID="<リソースID>"

export USER_ID="test-user-01"

export GOOGLE_CLOUD_STORAGE_BUCKET="YOUR_GCP_PROJECT_ID-adk-staging"

poetry run python test_deployment.py --resource_id=$RESOURCE_ID --user_id=$USER_ID

対話型のCLIが起動したら、ローカル編と同様のプロンプトを入力します。

Input: trainテーブルの日ごとの売上合計を取得し、その結果を可視化してください

エージェントからの応答があった後、GCSバケットを確認し、生成されたSQLファイルや分析結果イメージファイルが格納されたフォルダが保存されていれば、デプロイとGCS連携は完璧です！

今回は、ADKの柔軟な設定機能を活用し、ローカル開発環境と本番のAgent Engine環境の両方で、Artifactの保存先をGCSに切り替える方法を解説しました。特にAgent Engineでは、デプロイスクリプトを一度修正するだけで、あとは.envファイルの環境変数で挙動を制御できるため、DevOpsのプラクティスに非常に親和性が高いことがお分かりいただけたかと思います。

これにより、データサイエンスエージェントは、実行されたすべての分析の証跡を、信頼性の高いクラウドストレージに記録・保管できるようになりました。これは、AIエージェントの透明性や再現性を確保する上で、非常に重要な一歩です。

ここからさらに、GCSイベントをトリガーにしてメタデータをBigQueryに連携させたり、Looker StudioでArtifactを可視化したりと、可能性が広がります。ぜひ、皆さんも試してみてください！