Develop and deploy agents on Agent Runtime with Agent Development Kit

Develop and deploy agents on Agent Runtime with Agent Development Kit

Agent Runtime lets you host agents developed with the Agent Development Kit (ADK). This document explains how to create, deploy, and test an agent using ADK.

This quickstart guides you through the following steps:

• Set up your Google Cloud project.
• Install the Agent Platform SDK for Python and ADK.
• Develop a currency exchange agent.
• Deploy the agent to Agent Runtime.
• Test the deployed agent.

You can also use the following alternative quickstarts for ADK:

• ADK quickstart: The ADK quickstart runs entirely on your machine and assumes you're using a local IDE and terminal access.
• Agent Starter Pack: A collection of production-ready generative AI agent templates built for Agent Platform.

For the quickstart using supported frameworks other than Agent Development Kit, see Develop and deploy agents on Agent Runtime.

Before you begin

Note: To enable APIs, you need the serviceusage.services.enable permission. If you don't have this permission, ask your administrator to grant you the Service Usage Admin (roles/serviceusage.serviceUsageAdmin) role.

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Agent Platform and Cloud Storage APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

To get the permissions that you need to use Agent Runtime, ask your administrator to grant you the following IAM roles on your project:

• Agent Platform User (roles/aiplatform.user)
• Storage Admin (roles/storage.admin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Install and initialize the Agent Platform SDK for Python

1. Run the following command to install the Agent Platform SDK for Python and other required packages:

   pip install --upgrade --quiet google-cloud-aiplatform[agent_engines,adk]>=1.112

2. Authenticate as a user

   Local Shell

   Run the following command:

   gcloud auth application-default login

   Colab

   Run the following code:

   from google.colab import auth
   
   auth.authenticate_user(project_id="PROJECT_ID")
   

   Cloud Shell

   No action required.

3. Run the following code to import Agent Platform and initialize the SDK:

   Google Cloud project

   import vertexai
   
   client = vertexai.Client(
       project="PROJECT_ID",               # Your project ID.
       location="LOCATION",                # Your cloud region.
   )
   

   Where:

   • PROJECT_ID is the Google Cloud project ID under which you develop and deploy agents

   • LOCATION is one of the supported regions.

Develop an agent

1. Develop a currency exchange tool for your agent:

   def get_exchange_rate(
       currency_from: str = "USD",
       currency_to: str = "EUR",
       currency_date: str = "latest",
   ):
       """Retrieves the exchange rate between two currencies on a specified date."""
       import requests
   
       response = requests.get(
           f"https://api.frankfurter.app/{currency_date}",
           params={"from": currency_from, "to": currency_to},
       )
       return response.json()
   

2. Instantiate an agent:

   from google.adk.agents import Agent
   from vertexai import agent_engines
   
   agent = Agent(
       model="gemini-2.0-flash",
       name='currency_exchange_agent',
       tools=[get_exchange_rate],
   )
   
   app = agent_engines.AdkApp(agent=agent)
   

3. Test the agent locally:

   Note: Testing an ADK agent locally uses in-memory sessions.

   async for event in app.async_stream_query(
       user_id="USER_ID",
       message="What is the exchange rate from US dollars to SEK today?",
   ):
       print(event)
   

   where USER_ID is a user-defined ID with a character limit of 128.

Deploy an agent

Deploy the agent by creating a reasoningEngine resource in Agent Platform:

Note: Deploying an ADK agent to Agent Platform automatically generates a managed session resource. You can delete the managed session resource along with the agent in the Clean-up section.

remote_agent = client.agent_engines.create(
    agent=app,
    config={
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"],
        "staging_bucket": "STAGING_BUCKET",
        "identity_type": types.IdentityType.AGENT_IDENTITY,
    }
)

where STAGING_BUCKET is a Cloud Storage bucket prefixed by gs://.

Use an agent

Test the deployed agent by sending a query:

async for event in remote_agent.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

Clean up

To avoid incurring charges to your Google Cloud account for the resources used on this page, follow these steps.

remote_agent.delete(force=True)

What's next

Guide

Agent Platform Runtime setup

Set up your environment to use Agent Platform Runtime.

Guide

Deploy agents

Learn the five ways to deploy an agent on Agent Platform Runtime based on your development needs.

Guide

Manage deployed agents

Learn how to manage agents that have been deployed to the Agent Platform managed runtime.

Guide

Use an agent

Use an agent with Agent Platform Runtime.

Resource

Get support

Find resources and support for Google Agent Platform.