Google Agent Development Kit (ADK) Tutorial: Build, Test, and Deploy Your First AI Agent

The Agent Development Kit (ADK) is the code-first way to build agents on Google’s stack. It’s open source, it’s what Google uses for many of its own agents, and it’s the framework behind most agents running on Gemini Enterprise Agent Platform (formerly Vertex AI). Google says more than six trillion tokens a month flow through Gemini models via ADK.

This tutorial goes from an empty folder to a deployed agent: install ADK, write an agent with a tool, run it locally, add a second agent, and deploy to Agent Runtime. Along the way it covers the concepts you need to design real agents, and what IT and security teams should check before an ADK agent goes live.

If you’d rather build without code, Agent Studio offers a visual builder whose logic can be exported to ADK. Code-first teams start here.

Finished agents can be published to employees through Gemini Enterprise, next to the Gemini features already in Google Workspace.

Table of contents

Open Table of contents

• What the Agent Development Kit Is (and When to Use It)
• Step 1: Install ADK
• Step 2: Choose How the Agent Reaches Gemini
• Step 3: Write Your First Agent
• Step 4: Run It Locally
• Step 5: Go Multi-Agent
• Step 6: Add Real Tools
• Step 7: Deploy to Agent Runtime
• Step 8: Evaluate Before You Ship
• Security Checklist for ADK Agents
• Common First-Time Errors
• Publishing to Employees
• Conclusion

What the Agent Development Kit Is (and When to Use It)

ADK is a framework for building agents: programs where a model decides which steps to take and which tools to call to reach a goal. Google describes it as a way to build, debug, evaluate, and deploy agents “from simple assistants to multi-agent business workflows.”

ADK 2.0 adds graph-based workflows that combine model reasoning with deterministic code: useful when a compliance step must always run in a fixed order.

ADK vs. Agent Studio vs. Workflow Builder

Choose ADK when the agent needs custom tools, tests in CI, code review, or complex multi-agent logic.

---

Step 1: Install ADK

You need Python 3.10 or later.

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install google-adk

Then scaffold a project:

adk create my_agent

This creates:

my_agent/
├── agent.py      # your agent code
├── .env          # API key or project settings
└── __init__.py

---

Step 2: Choose How the Agent Reaches Gemini

ADK can call Gemini two ways. Put the settings in my_agent/.env.

Option A: Gemini API key (quickest for learning):

GOOGLE_API_KEY="YOUR_API_KEY"

Create the key in Google AI Studio.

Option B: Google Cloud Agent Platform (for company work):

GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_ENTERPRISE=True

Then authenticate:

gcloud auth application-default login

Older tutorials use GOOGLE_GENAI_USE_VERTEXAI=TRUE; current ADK docs use GOOGLE_GENAI_USE_ENTERPRISE. For anything touching company data, use Option B so usage runs under your Google Cloud project’s IAM, logging, and billing.

---

Step 3: Write Your First Agent

Replace agent.py with an agent that has one tool. This follows the structure of Google’s quickstart:

from google.adk.agents.llm_agent import Agent


def get_current_time(city: str) -> dict:
    """Returns the current time in a specified city."""
    # Replace with a real lookup in production.
    return {"status": "success", "city": city, "time": "10:30 AM"}


root_agent = Agent(
    model="gemini-flash-latest",
    name="root_agent",
    description="Tells the current time in a specified city.",
    instruction="You are a helpful assistant that tells the current time in cities. "
                "Use the 'get_current_time' tool for this purpose.",
    tools=[get_current_time],
)

Four things to notice:

1. root_agent is required. ADK looks for this name as the entry point.
2. Tools are plain Python functions. ADK reads the function name, type hints, and docstring to tell the model what the tool does, so write clear docstrings.
3. instruction is the agent’s job description. Be specific about when to use each tool.
4. description matters in multi-agent setups. Other agents use it to decide whether to delegate to this one.

---

Step 4: Run It Locally

From the command line:

adk run my_agent

Or with the development web UI (run from the folder that contains my_agent/):

adk web --port 8000

Open http://localhost:8000, choose your agent in the upper left, and chat with it. The web UI shows each step (model calls, tool calls, and results) which makes debugging much easier. Google is clear that ADK Web is for development only, not production.

---

Step 5: Go Multi-Agent

Real tasks are easier when split between specialists. ADK gives you two patterns.

Model-driven delegation

Give a coordinator agent a list of sub_agents. The model reads each sub-agent’s description and hands work to the right one:

from google.adk.agents.llm_agent import Agent

billing_agent = Agent(
    model="gemini-flash-latest",
    name="billing_agent",
    description="Answers questions about invoices and payment status.",
    instruction="Answer billing questions using the billing tools.",
    tools=[],  # add billing tools here
)

support_agent = Agent(
    model="gemini-flash-latest",
    name="support_agent",
    description="Troubleshoots product issues.",
    instruction="Help users troubleshoot product problems step by step.",
)

root_agent = Agent(
    model="gemini-flash-latest",
    name="root_agent",
    description="Front-door assistant that routes requests.",
    instruction="Route billing questions to billing_agent and product problems "
                "to support_agent. Ask a clarifying question if unsure.",
    sub_agents=[billing_agent, support_agent],
)

Workflow agents for fixed steps

When steps must always happen in order (extract, validate, then write) use ADK’s workflow agents (sequential, parallel, and loop) or, in ADK 2.0, a graph workflow. The model still does the thinking inside each step, but the order is guaranteed by code. That predictability matters for finance, HR, and compliance processes.

---

Step 6: Add Real Tools

Keep tools narrow and well described. A tool called get_invoice_status(invoice_id) is safer and more reliable than a generic run_sql(query).

---

Step 7: Deploy to Agent Runtime

Agent Runtime (formerly Vertex AI Agent Engine) is Google’s managed runtime for agents: fast cold starts, long-running agents that can run for up to seven days, and built-in sessions and memory.

Prerequisites

1. A Google Cloud project. Use the Project ID, not the project number
2. Enable the Agent Platform API (aiplatform.googleapis.com) and Cloud Resource Manager API (cloudresourcemanager.googleapis.com)
3. Install the gcloud CLI and authenticate:

gcloud auth login
gcloud auth application-default login
gcloud config set project MY-PROJECT-ID

Deploy

PROJECT_ID=my-project-id
LOCATION_ID=us-central1

adk deploy agent_engine \
  --project=$PROJECT_ID \
  --region=$LOCATION_ID \
  --display_name="My First Agent" \
  my_agent

Note the subcommand is still agent_engine, even though the product is now called Agent Runtime: product names changed faster than command names.

The output ends with a resource name like:

projects/.../locations/us-central1/reasoningEngines/751619551677906944

Save the numeric resource ID. You query the deployed agent at:

https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query

using the Agent Platform SDK, Python requests, or any REST client. Monitor deployments in the Agent Runtime page of the Google Cloud console.

For Python, the deployment uploads your code and declared dependencies but not the ADK web UI: Agent Runtime provides the API server. For teams that want CI/CD and infrastructure-as-code from the start, Google also offers an accelerated Agents CLI deployment path.

Agent Runtime is a paid service beyond its no-cost tier; check the pricing page before load testing.

---

Step 8: Evaluate Before You Ship

An agent that works in three test chats can still fail on the fourth. Before production:

• Write an evaluation set: 20 to 50 realistic requests with expected outcomes, including edge cases and requests it should refuse
• Check trajectories, not just answers: did it call the right tools, in the right order, with the right arguments?
• Simulate users: ADK’s evaluation supports user and environment simulation
• Re-run the set on every change: prompts, tools, and model versions all change behavior

On Agent Platform, Agent evaluation adds multi-turn autoraters and online monitors that score live traffic for drift.

---

Security Checklist for ADK Agents

Before an ADK agent touches company data, check:

---

Common First-Time Errors

---

Publishing to Employees

Agents built with ADK and deployed to Agent Runtime can be made available to employees through the Gemini Enterprise app, so people use them alongside enterprise search and the Gemini agent. Edition matters: using your own full-code agents requires Gemini Enterprise Standard, Plus, Pay-as-you-go, or Frontline (provisioned agents only), Business doesn’t include it. See our billing guide for how usage is charged.

---

Conclusion

ADK gives developers a straightforward path from idea to production agent: pip install google-adk, write a root_agent with well-described tools, test with adk web, and deploy with adk deploy agent_engine. Multi-agent delegation and workflow agents cover most real business processes, and Agent Runtime handles scaling, sessions, and memory.

The hard part isn’t the code. It’s tool design, evaluation, and governance. Get those right, and your agents can safely work with the same data your people use every day in Google Workspace, Gemini Enterprise, and the rest of your stack.

---

Official Google documentation:

• Agent Development Kit
• ADK Python quickstart
• Deploy ADK agents to Agent Runtime
• ADK on Gemini Enterprise Agent Platform
• Gemini models and authentication in ADK

Related reading:

• Vertex AI Is Now Gemini Enterprise Agent Platform: the name changes behind Agent Runtime and Agent Studio.
• Google’s New Gemini Agent: Gemini at Work 2026: where custom agents meet employees.
• Gemini Enterprise Pay-as-you-go and Overages: how agent usage is billed.