CLI Reference

This page contains the auto-generated command-line reference for the adk tool.

adk

Agent Development Kit CLI tools.

adk [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

api_server

Starts a FastAPI server for agents.

AGENTS_DIR: The directory of agents, where each sub-directory is a single agent, containing at least __init__.py and agent.py files.

Example:

adk api_server –port=[port] path/to/agents_dir

adk api_server [OPTIONS] [AGENTS_DIR]

Options

--host <host>

Optional. The binding host of the server

Default:

'127.0.0.1'

--port <port>

Optional. The port of the server

--allow_origins <allow_origins>

Optional. Any additional origins to allow for CORS.

--log_level <log_level>

Optional. Set the logging level

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

--trace_to_cloud

Optional. Whether to enable cloud trace for telemetry.

Default:

False

--reload, --no-reload

Optional. Whether to enable auto reload for server. Not supported for Cloud Run.

--a2a

Optional. Whether to enable A2A endpoint.

Default:

False

--reload_agents

Optional. Whether to enable live reload for agents changes.

Default:

False

--session_service_uri <session_service_uri>

Optional. The URI of the session service. - Use ‘agentengine://<agent_engine_resource_id>’ to connect to Agent Engine sessions. - 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 database URIs.

--artifact_service_uri <artifact_service_uri>

Optional. The URI of the artifact service, supported URIs: gs://<bucket name> for GCS artifact service.

--eval_storage_uri <eval_storage_uri>

Optional. The evals storage URI to store agent evals, supported URIs: gs://<bucket name>.

--memory_service_uri <memory_service_uri>

Optional. The URI of the memory service. - Use ‘rag://<rag_corpus_id>’ to connect to Vertex AI Rag Memory Service. - Use ‘agentengine://<agent_engine_resource_id>’ to connect to Vertex AI Memory Bank Service. e.g. agentengine://12345

--session_db_url <session_db_url>

Deprecated. Use –session_service_uri instead.

--artifact_storage_uri <artifact_storage_uri>

Deprecated. Use –artifact_service_uri instead.

Arguments

AGENTS_DIR

Optional argument

create

Creates a new app in the current folder with prepopulated agent template.

APP_NAME: required, the folder of the agent source code.

Example:

adk create path/to/my_app

adk create [OPTIONS] APP_NAME

Options

--model <model>

Optional. The model used for the root agent.

--api_key <api_key>

Optional. The API Key needed to access the model, e.g. Google AI API Key.

--project <project>

Optional. The Google Cloud Project for using VertexAI as backend.

--region <region>

Optional. The Google Cloud Region for using VertexAI as backend.

Arguments

APP_NAME

Required argument

deploy

Deploys agent to hosted environments.

adk deploy [OPTIONS] COMMAND [ARGS]...

agent_engine

Deploys an agent to Agent Engine.

AGENT: The path to the agent source code folder.

Example:

adk deploy agent_engine –project=[project] –region=[region]

–staging_bucket=[staging_bucket] –display_name=[app_name] path/to/my_agent

adk deploy agent_engine [OPTIONS] AGENT

Options

--project <project>

Required. Google Cloud project to deploy the agent. It will override GOOGLE_CLOUD_PROJECT in the .env file (if it exists).

--region <region>

Required. Google Cloud region to deploy the agent. It will override GOOGLE_CLOUD_LOCATION in the .env file (if it exists).

--staging_bucket <staging_bucket>

Required. GCS bucket for staging the deployment artifacts.

--trace_to_cloud

Optional. Whether to enable Cloud Trace for Agent Engine.

Default:

False

--display_name <display_name>

Optional. Display name of the agent in Agent Engine.

Default:

''

--description <description>

Optional. Description of the agent in Agent Engine.

Default:

''

--adk_app <adk_app>

Optional. Python file for defining the ADK application (default: a file named agent_engine_app.py)

--temp_folder <temp_folder>

Optional. Temp folder for the generated Agent Engine source files. If the folder already exists, its contents will be removed. (default: a timestamped folder in the system temp directory).

--env_file <env_file>

Optional. The filepath to the .env file for environment variables. (default: the .env file in the agent directory, if any.)

--requirements_file <requirements_file>

Optional. The filepath to the requirements.txt file to use. (default: the requirements.txt file in the agent directory, if any.)

Arguments

AGENT

Required argument

cloud_run

Deploys an agent to Cloud Run.

AGENT: The path to the agent source code folder.

Example:

adk deploy cloud_run –project=[project] –region=[region] path/to/my_agent

adk deploy cloud_run [OPTIONS] AGENT

Options

--project <project>

Required. Google Cloud project to deploy the agent. When absent, default project from gcloud config is used.

--region <region>

Required. Google Cloud region to deploy the agent. When absent, gcloud run deploy will prompt later.

--service_name <service_name>

Optional. The service name to use in Cloud Run (default: ‘adk-default-service-name’).

--app_name <app_name>

Optional. App name of the ADK API server (default: the folder name of the AGENT source code).

--port <port>

Optional. The port of the server

--allow_origins <allow_origins>

Optional. Any additional origins to allow for CORS.

--log_level <log_level>

Optional. Set the logging level

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

--trace_to_cloud

Optional. Whether to enable cloud trace for telemetry.

Default:

False

--reload, --no-reload

Optional. Whether to enable auto reload for server. Not supported for Cloud Run.

--a2a

Optional. Whether to enable A2A endpoint.

Default:

False

--reload_agents

Optional. Whether to enable live reload for agents changes.

Default:

False

--with_ui

Optional. Deploy ADK Web UI if set. (default: deploy ADK API server only)

Default:

False

--verbosity <verbosity>

Deprecated. Use –log_level instead.

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

--temp_folder <temp_folder>

Optional. Temp folder for the generated Cloud Run source files (default: a timestamped folder in the system temp directory).

--adk_version <adk_version>

Optional. The ADK version used in Cloud Run deployment. (default: the version in the dev environment)

Default:

'1.7.0'

--session_service_uri <session_service_uri>

Optional. The URI of the session service. - Use ‘agentengine://<agent_engine_resource_id>’ to connect to Agent Engine sessions. - 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 database URIs.

--artifact_service_uri <artifact_service_uri>

Optional. The URI of the artifact service, supported URIs: gs://<bucket name> for GCS artifact service.

--eval_storage_uri <eval_storage_uri>

Optional. The evals storage URI to store agent evals, supported URIs: gs://<bucket name>.

--memory_service_uri <memory_service_uri>

Optional. The URI of the memory service. - Use ‘rag://<rag_corpus_id>’ to connect to Vertex AI Rag Memory Service. - Use ‘agentengine://<agent_engine_resource_id>’ to connect to Vertex AI Memory Bank Service. e.g. agentengine://12345

--session_db_url <session_db_url>

Deprecated. Use –session_service_uri instead.

--artifact_storage_uri <artifact_storage_uri>

Deprecated. Use –artifact_service_uri instead.

Arguments

AGENT

Required argument

eval

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.

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

Options

--config_file_path <config_file_path>

Optional. The path to config file.

--print_detailed_results

Optional. Whether to print detailed results on console or not.

Default:

False

--eval_storage_uri <eval_storage_uri>

Optional. The evals storage URI to store agent evals, supported URIs: gs://<bucket name>.

Arguments

AGENT_MODULE_FILE_PATH

Required argument

EVAL_SET_FILE_PATH

Optional argument(s)

run

Runs an interactive CLI for a certain agent.

AGENT: The path to the agent source code folder.

Example:

adk run path/to/my_agent

adk run [OPTIONS] AGENT

Options

--save_session

Optional. Whether to save the session to a json file on exit.

Default:

False

--session_id <session_id>

Optional. The session ID to save the session to on exit when –save_session is set to true. User will be prompted to enter a session ID if not set.

--replay <replay>

The json file that contains the initial state of the session and user queries. A new session will be created using this state. And user queries are run againt the newly created session. Users cannot continue to interact with the agent.

--resume <resume>

The json file that contains a previously saved session (by–save_session option). The previous session will be re-displayed. And user can continue to interact with the agent.

Arguments

AGENT

Required argument

web

Starts a FastAPI server with Web UI for agents.

AGENTS_DIR: The directory of agents, where each sub-directory is a single agent, containing at least __init__.py and agent.py files.

Example:

adk web –port=[port] path/to/agents_dir

adk web [OPTIONS] [AGENTS_DIR]

Options

--host <host>

Optional. The binding host of the server

Default:

'127.0.0.1'

--port <port>

Optional. The port of the server

--allow_origins <allow_origins>

Optional. Any additional origins to allow for CORS.

--log_level <log_level>

Optional. Set the logging level

Options:

DEBUG | INFO | WARNING | ERROR | CRITICAL

--trace_to_cloud

Optional. Whether to enable cloud trace for telemetry.

Default:

False

--reload, --no-reload

Optional. Whether to enable auto reload for server. Not supported for Cloud Run.

--a2a

Optional. Whether to enable A2A endpoint.

Default:

False

--reload_agents

Optional. Whether to enable live reload for agents changes.

Default:

False

--session_service_uri <session_service_uri>

Optional. The URI of the session service. - Use ‘agentengine://<agent_engine_resource_id>’ to connect to Agent Engine sessions. - 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 database URIs.

--artifact_service_uri <artifact_service_uri>

Optional. The URI of the artifact service, supported URIs: gs://<bucket name> for GCS artifact service.

--eval_storage_uri <eval_storage_uri>

Optional. The evals storage URI to store agent evals, supported URIs: gs://<bucket name>.

--memory_service_uri <memory_service_uri>

Optional. The URI of the memory service. - Use ‘rag://<rag_corpus_id>’ to connect to Vertex AI Rag Memory Service. - Use ‘agentengine://<agent_engine_resource_id>’ to connect to Vertex AI Memory Bank Service. e.g. agentengine://12345

--session_db_url <session_db_url>

Deprecated. Use –session_service_uri instead.

--artifact_storage_uri <artifact_storage_uri>

Deprecated. Use –artifact_service_uri instead.

Arguments

AGENTS_DIR

Optional argument