ADK Agentic Pattern with Memory & MCP

1. What you will learn

Welcome to the ADK Master Class - Your Journey into Multi-Agent Systems

You're about to step into the exciting world of AI agents. Forget simple chatbots that just answer questions. We're diving deep into the Agent Development Kit (ADK) to build sophisticated, autonomous systems that can reason, plan, and use tools to accomplish complex tasks.

This entire codelab will be a hands-on journey, this 1 GitHub Repo that contain all the code and examples for our sessions. github repo

By the end of this tutorial, you will be able to:

• Build Your First AI Agent: Go from zero to a fully functional agent that can understand a user's needs, use tools like Google Search, and generate detailed, helpful responses.
• Construct Multi-Agent Systems: Learn the "Agent-as-a-Tool" pattern, a revolutionary concept where agents delegate tasks to other specialized agents, creating a team of AI experts that work together.
• Orchestrate Complex Workflows: Go beyond simple delegation and master advanced patterns like Routers, Sequential Chains, Loops, and Parallel Execution to build robust, efficient, and intelligent applications that can handle almost any requests.
• Give Your Agents Memory: Understand the critical role of conversational memory, enabling your agents to handle follow-up questions, learn from feedback, and manage multi-step tasks seamlessly.
• Connect with MCP: Connect wih MCP toolbox.

Let's get started! 🚀

2. Setup: Get Your API Key

Google AI Studio API Key Setup

This codelab runs entirely on a free Google AI Studio API key. No Google Cloud project, billing account, or credits are required — every session, including Memory (Session 6) and MCP (Session 7), runs locally against your key. Each learner uses their own key, so API quota is per-person, not shared.

What you'll need:

• Python 3.9 or higher (python3 --version to check)
• A Google account (to create the AI Studio key)
• A terminal — your local machine or Cloud Shell both work
• ~10 minutes

To power our AI agents, we need a Gemini API key from Google AI Studio. This is the fastest way to get started.

Step 1 — Get Your Gemini API Key from AI Studio (1 min)

1. Open https://aistudio.google.com/app/apikey in a new browser tab.
2. Sign in with your Google account.
3. Click "Create API key" (top-right).
4. A dialog opens with a project dropdown:

• If you already have a Google project created before: Select it and click "Create API key in existing project"
• If NOT in the list: Click "Create Project".

5. Copy the API key that appears. It starts with AIza... and is ~40 characters.

✏️ Paste it somewhere safe — you'll need it in Step 4 below.

Treat the API key like a password. Don't paste it in public chats, screenshots, or commit it to a public GitHub repo.

Step 2 — Clone the Repository (1 min)

👉💻 Open your terminal (or Cloud Shell) and clone the tutorial repo:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Step 3 — Create the Virtual Environment & Install Dependencies

👉💻 Create and activate a virtual environment named .adk_env, then install the dependencies:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

You should see (.adk_env) at the beginning of your terminal prompt.

Step 4 — 🔥 IMPORTANT: Add Your API Key

⚠️ Don't skip this step! Create a .env file in the root of the adk_tutorial folder. This one file powers every session in this codelab — the ADK Web sessions (1–5) and the command-line Memory and MCP sessions (6–7) all read it automatically.

👉💻 Create the .env file with your key (replace your_actual_api_key_here with the key from Step 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Your ~/adk_tutorial/.env should now contain:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRITICAL: Replace your_actual_api_key_here with your actual API key from Step 1 (it starts with AIza...).

⚠️ Make sure GOOGLE_GENAI_USE_VERTEXAI is set to FALSE. This tells the ADK to authenticate with your Google AI Studio API key instead of Vertex AI.

✅ Checkpoint: You have a .env file at ~/adk_tutorial/.env containing your AIza... key, and your terminal prompt shows (.adk_env). You're ready to build agents!

3. Session 1: Your First Agent in ADK Web

Open ADK Web by Running:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

After running the commands, you should see output in your terminal indicating that the ADK Web Server has started, similar to this:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 Next, open your browser to http://localhost:8000 to access the ADK Dev UI.

Running in Cloud Shell instead of locally? Click the Web preview icon in the Cloud Shell toolbar (usually top right), select Change port, set the port to 8000, and click "Change and Preview". Cloud Shell will open the ADK Dev UI in a new browser tab.

👉 Your summoning ritual is complete, and the agent is now running. The ADK Dev UI in your browser is your direct connection to the Familiar.

choose your first agent In the dropdown menu at the top of the UI, choose a_single_agent.

You can select a_single_agent here:

You can see the tracing here:

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Session 2: Workflow Agent: Sequential Agent, Parallel Agent, Loop Agent

Open your ADK Web UI following session 1 steps.

Parallel Agent

choose the parallel workflow agent In the dropdown menu at the top of the UI, choose b2_parallel_agent.

👉 Test Prompt:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

You can select b2_parallel_agent here:

You can see the tracing here:

Sequential Agent

choose the sequential workflow agent In the dropdown menu at the top of the UI, choose b1_sequential_agent.

👉 Test Prompt:

Find a good sushi near Standford and tell me how to get there.

You can select b1_sequential_agent here:

You can see the tracing here:

Loop Agent

choose the loop workflow agent In the dropdown menu at the top of the UI, choose b3_loop_agent.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco today.

You can select b3_loop_agent here:

You can see the tracing here:

5. Session 3: Custom Agent

Open your ADK Web UI following session 1 steps.

Once your ADK Web UI is open, choose c_custom_agent from the dropdown.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

You can select c_custom_agent here:

You can see the tracing here:

6. Session 4: Orchestrator Pattern - Routing Agent

Open your ADK Web UI following session 1 steps.

Once your ADK Web UI is open, choose d_routing_agent from the dropdown.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

You can select d_routing_agent here:

You can see the tracing here:

7. Session 5: Agent as tool

Open your ADK Web UI following session 1 steps.

Once your ADK Web UI is open, choose e_agent_as_tool from the dropdown.

👉 Test Prompt:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

You can select e_agent_as_tool here:

You can see the tracing here:

8. Session 6: Agent With Long Term Memory

Runs fully locally. This session stores conversation memory in a local SQLite database (under ~/.adk/), so your preferences persist across restarts with no Google Cloud, billing, or credits required. The agent reads your AI Studio key from the ~/adk_tutorial/.env you created in Setup.

👉💻 Test your long term memory by go to the folder and use the runner to power up the agent:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test Prompt:

I like Art and Italian food.

Then end the session by pressing Ctrl+C. Restart the session:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Test Prompt:

Plan a trip to San Francisco based on my preference.

✅ The agent should recall "Art and Italian food" from the previous run — that's the long-term memory working across sessions.

9. Session 7: Empower your agent with MCP

Runs fully locally. This session starts a local MCP Toolbox server that reads a local SQLite database (destinations.db) — no Google Cloud, billing, or credits required. The only external download is the open-source MCP Toolbox binary.

Step 1: Prepare the Local Database

👉💻 From the repo root, create the sample database:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

This creates destinations.db in ~/adk_tutorial/.

⚠️ The sample database only contains four cities — Paris, Rome, New York, and Tokyo (attraction types: Landmark, Museum, Park). Prompts that reference other cities (e.g. San Francisco or Sunnyvale) will correctly return no results, because those rows don't exist. Use the four cities above when testing this session.

Step 2: Install and Run the MCP Toolbox Server

👉💻 Download the MCP Toolbox binary for your operating system:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

once finishing downloading, and then run

chmod +x toolbox

Not sure which Mac you have? Run uname -m — arm64 = Apple Silicon, x86_64 = Intel. On Windows, download .../windows/amd64/toolbox.exe and run it from PowerShell.

Step 3

In one terminal Run the following command (leave it running — the agent connects to it at http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

In another terminal Run the following command

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Test Prompts (use the cities that exist in the sample database — Paris, Rome, New York, or Tokyo):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Session 7 troubleshooting

• "Connection refused" / the agent finds no tools: the Toolbox server in the first terminal isn't running — restart it and confirm it's listening on port 7001.
• Every query returns empty results: confirm you ran Step 1 so ~/adk_tutorial/destinations.db exists, and that your prompt uses one of the four cities (Paris, Rome, New York, Tokyo).
• toolbox: cannot execute binary file on macOS: you downloaded the Linux build — re-run Step 2 with OS=darwin/arm64 (Apple Silicon) or OS=darwin/amd64 (Intel).