Build production-ready AI agents with Google's official Agent Development Kit powered by Gemini.

Getting Started with Google ADK

Overview

Google ADK (Agent Development Kit) is Google's official framework for building AI agents powered by Gemini models. This tutorial walks you through setting up your first agent, adding tools, and deploying a production-ready AI application.

By the end of this tutorial, you'll have built a multi-step agent that can research topics, analyze data, and generate reports—all using Google's enterprise-grade agent framework.

Prerequisites

Python 3.10+ or Node.js 18+
Google Cloud Platform account (free tier available)
Basic understanding of Python or TypeScript
Gemini API access enabled

Step 1: Set Up Google Cloud

Create a GCP Project

Go to Google Cloud Console
Click Select a Project → New Project
Name it (e.g., my-adk-agent) and click Create

Enable Gemini API

In the Cloud Console, go to APIs & Services → Library
Search for "Gemini API"
Click Enable

Get API Credentials

Go to APIs & Services → Credentials
Click Create Credentials → API Key
Copy your API key

Set Environment Variables

export GOOGLE_API_KEY="your-api-key-here"
export GOOGLE_CLOUD_PROJECT="your-project-id"

Step 2: Install the ADK

Python

pip install google-adk

Node.js

npm install @google/adk

Step 3: Create Your First Agent

Python Example

from google_adk import Agent, GeminiModel

# Create a simple agent
agent = Agent(
    name="research-assistant",
    model=GeminiModel("gemini-2.0-flash"),
    instructions="You are a helpful research assistant. Provide clear, accurate, and well-structured answers."
)

# Run a simple query
response = agent.run("What are the main differences between CrewAI and AutoGen?")
print(response.text)

Node.js Example

import { Agent, GeminiModel } from '@google/adk';

const agent = new Agent({
  name: 'research-assistant',
  model: new GeminiModel('gemini-2.0-flash'),
  instructions: 'You are a helpful research assistant.',
});

const response = await agent.run('What are the main differences between CrewAI and AutoGen?');
console.log(response.text);

Step 4: Add Tools to Your Agent

Tools extend your agent's capabilities. Here's how to add custom tools:

Python: Custom Tools

from google_adk import Agent, GeminiModel, tool
import requests

@tool
def search_web(query: str, num_results: int = 5) -> str:
    """Search the web for information."""
    # Using Serper API (get free key at serper.dev)
    url = "https://google.serper.dev/search"
    headers = {
        "X-API-KEY": "your-serper-api-key",
        "Content-Type": "application/json"
    }
    data = {"q": query, "num": num_results}
    response = requests.post(url, headers=headers, json=data)
    return str(response.json())

@tool
def calculate(expression: str) -> float:
    """Calculate a mathematical expression."""
    try:
        return eval(expression)
    except:
        return -1

# Create agent with tools
agent = Agent(
    name="research-calculator",
    model=GeminiModel("gemini-2.0-flash"),
    tools=[search_web, calculate]
)

# The agent can now use these tools automatically
response = agent.run("What's the population of Tokyo and calculate 25 * 4?")
print(response.text)

Node.js: Custom Tools

import { Agent, GeminiModel, tool } from '@google/adk';
import axios from 'axios';

const searchWeb = tool({
  name: 'search_web',
  description: 'Search the web for information',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' },
      numResults: { type: 'number', description: 'Number of results' }
    },
    required: ['query']
  },
  execute: async ({ query, numResults = 5 }) => {
    const response = await axios.post(
      'https://google.serper.dev/search',
      { q: query, num: numResults },
      { headers: { 'X-API-KEY': 'your-serper-api-key' } }
    );
    return JSON.stringify(response.data);
  }
});

const agent = new Agent({
  name: 'research-calculator',
  model: new GeminiModel('gemini-2.0-flash'),
  tools: [searchWeb]
});

const response = await agent.run('What are trending AI news today?');
console.log(response.text);

Step 5: Build a Multi-Agent System

The ADK supports multi-agent orchestration for complex tasks:

Python: Multi-Agent Workflow

from google_adk import Agent, GeminiModel, MultiAgentOrchestrator

# Define specialized agents
researcher = Agent(
    name="researcher",
    model=GeminiModel("gemini-2.0-flash"),
    instructions="You are a research specialist. Gather comprehensive information on topics."
)

analyst = Agent(
    name="analyst",
    model=GeminiModel("gemini-2.0-flash"),
    instructions="You are a data analyst. Analyze information and identify key insights."
)

writer = Agent(
    name="writer",
    model=GeminiModel("gemini-2.0-flash"),
    instructions="You are a technical writer. Write clear, well-structured reports."
)

# Create orchestrator
orchestrator = MultiAgentOrchestrator(
    agents=[researcher, analyst, writer],
    strategy="sequential"  # Options: "sequential", "parallel", "hierarchical"
)

# Run a complex task
result = orchestrator.run("Research and write a report on the state of AI agent frameworks in 2025")
print(result)

Step 6: Add Memory for Long Conversations

from google_adk import Agent, GeminiModel, ConversationMemory

# Create agent with conversation memory
agent = Agent(
    name="conversation-agent",
    model=GeminiModel("gemini-2.0-flash"),
    memory=ConversationMemory(max_messages=20)
)

# First message
response1 = agent.run("Hello, my name is John. I'm interested in AI agents.")
print(response1.text)

# Follow-up (agent remembers context)
response2 = agent.run("What can you tell me about them?")
print(response2.text)  # Will reference John's interest

Step 7: Stream Responses

# Stream tokens as they're generated
for chunk in agent.run_stream("Explain quantum computing in simple terms"):
    print(chunk.text, end="", flush=True)

Step 8: Get Structured Outputs

from google_adk import Agent, GeminiModel
from pydantic import BaseModel, Field

class ArticleSummary(BaseModel):
    title: str = Field(description="The article title")
    main_points: list[str] = Field(description="Key points from the article")
    sentiment: str = Field(description="Overall sentiment: positive, neutral, or negative")
    confidence: float = Field(description="Confidence score 0-1")

# Create agent
agent = Agent(
    name="summary-agent",
    model=GeminiModel("gemini-2.0-flash")
)

# Get structured output
response = agent.run(
    "Summarize this article: [article text here]",
    output_schema=ArticleSummary
)

print(response.parsed.main_points)

Step 9: Integrate with Google Cloud Services

BigQuery Integration

from google_adk import Agent, GeminiModel, BigQueryTool

agent = Agent(
    model=GeminiModel("gemini-2.0-flash"),
    tools=[
        BigQueryTool(
            project="your-project-id",
            dataset="analytics"
        )
    ]
)

response = agent.run("""
    Query our analytics database to find:
    1. Top 5 products by revenue in Q4
    2. Customer retention rate
    3. Average order value
    
    Summarize the findings in a report format.
""")

Cloud Storage Integration

from google_adk import Agent, GeminiModel, CloudStorageTool

agent = Agent(
    model=GeminiModel("gemini-2.0-flash"),
    tools=[
        CloudStorageTool(bucket="my-documents")
    ]
)

response = agent.run("Read the file 'report-2025.md' from the bucket and summarize it")

Step 10: Deploy to Production

Cloud Run Deployment

# Containerize your application
docker build -t gcr.io/your-project/adk-agent .

# Push to Container Registry
docker push gcr.io/your-project/adk-agent

# Deploy to Cloud Run
gcloud run deploy adk-agent \
  --image gcr.io/your-project/adk-agent \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 8080

CMD exec gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Best Practices

Start with Flash: Use gemini-2.0-flash for most tasks—it's fast and cost-effective
Use Pro for Complex Tasks: Switch to gemini-2.0-pro for reasoning-heavy work
Implement Retry Logic: Handle API failures gracefully
Monitor Costs: Set up budget alerts in GCP
Use Memory Wisely: Don't store unnecessary context
Test Tools Independently: Verify tools work before adding to agents

Troubleshooting

Issue: API Key Not Working

Solution: Verify the API key has Gemini API enabled:

gcloud services enable generativelanguage.googleapis.com

Issue: Tool Not Being Used

Solution: Make sure the tool description is clear and the agent instructions encourage tool use:

instructions="You have access to tools. Use them when helpful."

Issue: Memory Not Persisting

Solution: Use session-based memory for multi-turn conversations:

memory=ConversationMemory(session_id="user-123")

Next Steps

Explore Google ADK Documentation
Try advanced features like multi-modal agents
Build a production deployment with Cloud Run
Contribute tools to the ADK ecosystem