Deploy to Agent Runtime with agents-cli¶

Supported in ADKPython

This deployment procedure describes how to perform a deployment using agents-cli and the ADK. Deploying to Agent Runtime via agents-cli provides an accelerated path to a production-ready environment. agents-cli automatically configures Google Cloud resources, CI/CD pipelines, and Infrastructure-as-Code (Terraform) to support the entire development lifecycle. As a best practice, always ensure you review the generated configurations to align with your organization’s security and compliance standards before production deployment.

This deployment guide uses agents-cli to apply a project template to your existing project, add deployment artifacts, and prepare your agent project for deployment. These instructions show you how to use agents-cli to provision a Google Cloud project with services needed for deploying your ADK project, as follows:

Prerequisites: Set up Google Cloud project, IAM permissions, and install required software.
Prepare your ADK project: Modify your existing ADK project files to get ready for deployment.
Connect to your Google Cloud project: Connect your development environment to Google Cloud and your Google Cloud project.
Deploy your ADK project: Provision required services in your Google Cloud project and upload your ADK project code.

For information on testing a deployed agent, see Test deployed agent. For more information on using agents-cli and its command line tools, see the CLI reference and Guide.

Prerequisites¶

You need the following resources configured to use this deployment path:

Google Cloud Project and Permissions: A Google Cloud project with billing enabled. You can use an existing project or create a new one. You must have one of the following IAM roles assigned within this project:
- Agent Platform User role — sufficient to deploy an agent to Agent Runtime.
- Owner role — required for the full production setup (Terraform infrastructure provisioning, CI/CD pipelines, IAM configuration).

Note

An empty project is recommended to avoid conflicts with existing resources. For new projects, see Creating and managing projects.

Python Environment: A Python version supported by agents-cli.
uv Tool: Manage Python development environment and running agents-cli tools. For installation details, see Install uv.
Google Cloud CLI tool: The gcloud command line interface. For installation details, see Google Cloud Command Line Interface.
Make tool: Build automation tool. This tool is part of most Unix-based systems, for installation details, see the Make tool documentation.

Prepare your ADK project¶

When you deploy an ADK project to Agent Runtime, you need some additional files to support the deployment operation. The following agents-cli command backs up your project and then adds files to your project for deployment purposes.

These instructions assume you have an existing ADK project that you are modifying for deployment. If you do not have an ADK project, or want to use a test project, complete one of the Get started guides, which creates an agent project. The following instructions use the my_agent project as an example.

To prepare your ADK project for deployment to Agent Runtime:

In a terminal window of your development environment, navigate to the parent directory that contains your agent folder. For example, if your project structure is:
```
your-project-directory/
├── my_agent/
│   ├── __init__.py
│   ├── agent.py
│   └── .env
```
Navigate to your-project-directory/
Run the agents-cli scaffold enhance command to add the files required for deployment into your project.
```
agents-cli scaffold enhance --deployment-target agent_engine
```
Follow the instructions from the agents-cli tool. In general, you can accept the default answers to all questions. However for the GCP region, option, make sure you select one of the supported regions for Agent Runtime.

When you successfully complete this process, the tool shows the following message:

> Success! Your agent project is ready.

Note

The agents-cli tool may show a reminder to connect to Google Cloud while running, but that connection is not required at this stage.

For more information about the changes agents-cli makes to your ADK project, see Changes to your ADK project.

Connect to your Google Cloud project¶

Before you deploy your ADK project, you must connect to Google Cloud and your project. After logging into your Google Cloud account, you should verify that your deployment target project is visible from your account and that it is configured as your current project.

To connect to Google Cloud and list your project:

In a terminal window of your development environment, login to your Google Cloud account:
```
gcloud auth application-default login
```
Set your target project using the Google Cloud Project ID:
```
gcloud config set project your-project-id-xxxxx
```
Verify your Google Cloud target project is set:
```
gcloud config get-value project
```

Once you have successfully connected to Google Cloud and set your Cloud Project ID, you are ready to deploy your ADK project files to Agent Runtime.

Deploy your ADK project¶

When using agents-cli, you deploy using the agents-cli deploy command. This command builds a container from your agent code, pushes it to a registry, and deploys it to Agent Runtime in the hosted environment.

Important

Make sure your Google Cloud target deployment project is set as your current project before performing these steps. The agents-cli deploy command uses your currently set Google Cloud project when it performs a deployment. For information on setting and checking your current project, see Connect to your Google Cloud project.

To deploy your ADK project to Agent Runtime in your Google Cloud project:

In a terminal window, navigate to your agent project directory (e.g., your-project-directory/).
Deploy your agent code to the Google Cloud development environment:
```
agents-cli deploy
```
The command reads your deployment_target from pyproject.toml and deploys to the configured target (Agent Runtime, Cloud Run, or GKE).
(Optional) To enable observability features like prompt-response logging and content logs, provision the telemetry infrastructure:
```
agents-cli infra single-project
```
For more details, see the Observability Guide.

Once this process completes successfully, you should be able to interact with the agent running on Google Cloud Agent Runtime. For details on testing the deployed agent, see Test deployed agent.

Changes to your ADK project¶

The agents-cli tools add more files to your project for deployment. The procedure below backs up your existing project files before modifying them. This guide uses the multi_tool_agent project as a reference example. The original project has the following file structure to start with:

my_agent/
├─ __init__.py
├─ agent.py
└─ .env

After running the agents-cli scaffold enhance command to add Agent Runtime deployment information, the new structure is as follows:

my-agent/
├─ app/                 # Core application code
│   ├─ agent.py         # Main agent logic
│   ├─ agent_engine_app.py # Agent Runtime application logic
│   └─ utils/           # Utility functions and helpers
├─ .cloudbuild/         # CI/CD pipeline configurations for Google Cloud Build
├─ deployment/          # Infrastructure and deployment scripts
├─ notebooks/           # Jupyter notebooks for prototyping and evaluation
├─ tests/               # Unit, integration, and load tests
├─ Makefile             # Makefile for common commands
├─ GEMINI.md            # AI-assisted development guide
└─ pyproject.toml       # Project dependencies and configuration

See the README.md file in your updated ADK project folder for more information. For more information on using agents-cli, see the agents-cli documentation.

Test deployed agents¶

After completing deployment of your ADK agent you should test the workflow in its new hosted environment. For more information on testing an ADK agent deployed to Agent Runtime, see Test deployed agents in Agent Runtime.