🐕

Agent Development Kit（ADK）のノート（コマンド編）

2025/05/21に公開

Google Cloud

Google

Gemini

Agent Development Kit

tech

はじめに

この記事はAgent Development Kitについてまとめた記事です。
adkはコマンドが利用できるのでコマンドの使い方についてまとめてみました。誤りなどがあれば、随時修正していく予定です。

Agent Development Kit（ADK）とは

Google Cloud が提供する、AI エージェントを構築するための開発キットです。
ADKを活用することで関数処理や外部ツールの利用などが簡単に実装できます。マルチエージェントの実装も可能です。

利用方法

ローカル環境Python
Python仮想環境
- 例：venv
Docker環境（クラウドIDEなどを利用して実行）

※Docker 環境の場合はDev Containerを利用することを推奨
お試しリポジトリ：adk_quick_start - GitHub

事前準備

GitHub Codespacesを利用する場合は、以下のURLをクリックすることで、すぐに環境を立ち上げることが可能です。

Pythonとpipがインストールされている環境で以下のコマンドを実行することでADKがセットアップできます。

pip install --upgrade pip && pip install google-adk

adk-samplesを試しに実行するため、gcloudをセットアップします。

gcloudをインストールするためには以下のコマンドを実行します。

curl -sSL https://sdk.cloud.google.com | bash && exec -l $SHELL && gcloud init

gcloudコマンドが実行できる環境になれば、adk-samplesは動作します。認証と環境変数をセットします。

gcloud auth login
gcloud auth application-default login

環境変数をセットします。

export GOOGLE_CLOUD_PROJECT=`gcloud config list --format 'value(core.project)'`
export GOOGLE_CLOUD_LOCATION=us-central1
export "GOOGLE_GENAI_USE_VERTEXAI=TRUE"

最後にサンプルリポジトリをクローンします。

git clone https://github.com/google/adk-samples.git

最後にディレクトリを変更します。

cd agents/customer-service

コマンドラインで利用

ここからはGitHub Codespacesをベースにコマンドラインでの利用方法を説明します。

コマンドヘルプ

ヘルプを見る時は--helpのオプションをつけて実行することで表示されます。

adk --help

実行結果

Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --help  Show this message and exit.

Commands:
  api_server  Start a FastAPI server for agents.
  deploy      Deploy Agent.
  eval        Evaluates an agent given the eval sets.
  run         Run an interactive CLI for a certain agent.
  web         Start a FastAPI server with Web UI for agents.

api_server

adk api_server

概要
エージェントのためのFastAPIベースのAPIサーバーを起動します。

実行方法は以下のとおりです。

adk api_server --session_db_url=[db_url] --port=[port] path/to/agents_dir

AGENTS_DIR: エージェントのディレクトリ。各サブディレクトリは単一のエージェントを表し、少なくとも__init__.pyとagent.pyファイルを含む必要があります。
ディレクトリ構造としては以下のようになります。

AGENTS_DIR
├── agent1
│   ├── __init__.py
│   └── agent.py

参考になるディレクトリ構造

api_serverの起動オプション

まだ細かく使うことはないと思いますが、一応メモ

Options:
  --session_db_url TEXT           Optional. The database URL to store the session.
                                  - Use 'agentengine://<agent_engine_resource_id>' to connect to Vertex managed session service.
                                  - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
                                  - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs.
  --port INTEGER                  Optional. The port of the server
  --allow_origins TEXT            Optional. Any additional origins to allow for CORS.
  --log_level [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Optional. Set the logging level
  --log_to_tmp                    Optional. Whether to log to system temp folder instead of console. This is useful for local debugging.
  --trace_to_cloud                Optional. Whether to enable cloud trace for telemetry.

deploy

adk deploy

概要
AIエージェントをデプロイします。

実行例

adk deploy cloud_run customer_service

上記のコマンドを実行するとデプロイリージョンとArtifact Registryの作成について質問されます。
最終的にCloud Runにエージェントがデプロイされます。

実行結果

Start generating Cloud Run source files in /tmp/cloud_run_deploy_src/20250520_151519
Copying agent source code...
Copying agent source code complete.
Creating Dockerfile...
Creating Dockerfile complete: /tmp/cloud_run_deploy_src/20250520_151519/Dockerfile
Deploying to Cloud Run...
Use default project: virtual-voyage-425916-s5
Please specify a region:
 [1] africa-south1
 [2] asia-east1
 [3] asia-east2
 [4] asia-northeast1
 [5] asia-northeast2
 [6] asia-northeast3
 [7] asia-south1
 [8] asia-south2
 [9] asia-southeast1
 [10] asia-southeast2
 [11] australia-southeast1
 [12] australia-southeast2
 [13] europe-central2
 [14] europe-north1
 [15] europe-north2
 [16] europe-southwest1
 [17] europe-west1
 [18] europe-west10
 [19] europe-west12
 [20] europe-west2
 [21] europe-west3
 [22] europe-west4
 [23] europe-west6
 [24] europe-west8
 [25] europe-west9
 [26] me-central1
 [27] me-central2
 [28] me-west1
 [29] northamerica-northeast1
 [30] northamerica-northeast2
 [31] northamerica-south1
 [32] southamerica-east1
 [33] southamerica-west1
 [34] us-central1
 [35] us-east1
 [36] us-east4
 [37] us-east5
 [38] us-south1
 [39] us-west1
 [40] us-west2
 [41] us-west3
 [42] us-west4
 [43] cancel
Please enter numeric choice or text value (must exactly match list item):  2

To make this the default region, run `gcloud config set run/region asia-east1`.

Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region
 [asia-east1] will be created.

Do you want to continue (Y/n)?  Y

Allow unauthenticated invocations to [adk-default-service-name] (y/N)?  y

deployの起動オプション

なし。--helpでも設定項目はなし。

eval

adk eval

概要
エージェントを評価します。

実行例

adk eval customer_service

ModuleNotFoundError: No module named 'customer_service'という結果になりますが、実行の先頭で以下のように評価されています。

Using evaluation creiteria: {'tool_trajectory_avg_score': 1.0, 'response_match_score': 0.8}

evalの起動オプション

Usage: adk eval [OPTIONS] AGENT_MODULE_FILE_PATH [EVAL_SET_FILE_PATH]...

  Evaluates an agent given the eval sets.

  AGENT_MODULE_FILE_PATH: The path to the __init__.py file that contains a module by the name "agent". "agent" module contains a root_agent.

  EVAL_SET_FILE_PATH: You can specify one or more eval set file paths.

  For each file, all evals will be run by default.

  If you want to run only specific evals from a eval set, first create a comma separated list of eval names and then add that as a suffix to the eval set
  file name, demarcated by a `:`.

  For example,

  sample_eval_set_file.json:eval_1,eval_2,eval_3

  This will only run eval_1, eval_2 and eval_3 from sample_eval_set_file.json.

  CONFIG_FILE_PATH: The path to config file.

  PRINT_DETAILED_RESULTS: Prints detailed results on the console.

Options:
  --config_file_path TEXT   Optional. The path to config file.
  --print_detailed_results  Optional. Whether to print detailed results on console or not.
  --help                    Show this message and exit.

run

adk run

概要
エージェントを対話的に実行します。

実行例

adk run customer_service

結果

ymd65536 ➜ /workspaces/adk-samples/agents/customer-service (main) $ adk run customer_service
Log setup complete: /tmp/agents_log/agent.20250520_150917.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
Running agent customer_service_agent, type exit to exit.
[user]: Hello
[customer_service_agent]: Hi Alex, welcome back to Cymbal Home & Garden! I see you've been a customer since 2022. Is there anything I can help you with today?

web

adk web

概要
エージェントのためのFastAPIベースのWeb UIを起動します。デフォルトでは8000番ポート

adk web

まとめ

おおむねの操作方法を理解することができましたが、adk evalだけどうしてもエラーが出てしまうので仕様をよく読んで
細かく調査したいと思いました。※おそらくパッケージの読み込みでNGになっている。

また、Googleのsampleですが、厳密に動作要件のようなものが書かれていないため
試行錯誤で環境構築しているような感じがありました。とはいえ、ある程度、stableな環境を用意したら実行できましたので
そこまで苦労はしませんでした。

次は実際にagentを作ってみようと思います。

参考

クイックスタート: エージェント開発キットを使用してエージェントをビルドする