Google Agent Development Kit (ADK) - Python Samples

This repository contains a collection of sample agents built using the Google Agent Development Kit (ADK). Each sample is a self-contained application demonstrating different use cases and integrations.

Table of Contents

• General Prerequisites
• Available Agents
  • 1. GCP Release Notes Agent
  • 2. Shop Search Agent
  • 3. Restaurant Finder Agent
  • 4. Shopper's Concierge Agent
  • 5. Agentic RAG
    • QnA Agent with AlloyDB
    • QnA Agent with BigQuery
    • QnA Agent with BigQuery Hybrid Search
    • DEO Negation-Aware RAG with BigQuery
    • QnA Agent with Spanner
    • QnA Agent with Vector Search 2.0
    • QnA Agent with Gemini File Search
    • More RAG Agents
  • 6. Graph RAG
    • Graph RAG with Spanner
    • Graph RAG with BigQuery
    • PathRAG with Spanner
    • PathRAG with BigQuery
    • LightRAG with Spanner
    • LightRAG with BigQuery
  • 7. ADK BigQuery Logging Plugin Example
  • 8. Agent Memory
    • ADK Redis Session Service
    • ADK Redis Memory Service
    • BigQuery Data Agent with Agent Engine Memory Bank
  • 9. Dynamic MCP Agent
• References

General Prerequisites

• Python 3.x
• Google Cloud SDK
• Google Agent Development Kit (ADK)

Please refer to the individual agent directories for specific dependencies and configuration steps.

Available Agents

1. GCP Release Notes Agent

• Directory: gcp-releasenotes-agent-app/
• Description: An agent designed to answer questions about Google Cloud release notes. It connects to a MCP Toolbox for Databases service that queries a public BigQuery dataset.
• Features:
  • Demonstrates integration with a BigQuery-backed MCP Toolbox.
  • Includes instructions for deploying the toolbox service to Cloud Run.

For detailed setup and execution instructions, please see the GCP Release Notes Agent README.

2. Shop Search Agent

• Directory: shop-agent-app/
• Description: An agent that acts as a shopping assistant, using a tool to search for products in a catalog. It connects to a separate MCP server backed by Vertex AI Search for Retail.
• Features:
  • Illustrates how to connect an agent to a custom MCP server.
  • Provides a clear example of a retail or e-commerce use case.

For detailed setup and execution instructions, please see the Shop Search Agent README.

3. Restaurant Finder Agent

• Directory: restaurant-finder/
• Description: A conversational AI agent that helps users find restaurants based on a specific dish or ingredient, leveraging the Google Maps Platform API.
• Features:
  • Demonstrates how an agent can use external tools (Google Maps API) to answer user queries.
  • Provides real-time restaurant information.

For detailed setup and execution instructions, please see the Restaurant Finder Agent README.

4. Shopper's Concierge Agent

• Directory: shopper-concierge-demo/
• Description: An advanced shopping assistant that uses a sub-agent for research to provide more relevant product recommendations.
• Features:
  • Showcases a multi-agent architecture where a primary agent delegates tasks to a specialized sub-agent.
  • Includes a Gradio web interface for a complete user experience.

For detailed setup and execution instructions, please see the Shopper's Concierge Agent README.

5. Agentic RAG

This section includes agents that implement the Retrieval-Augmented Generation (RAG) pattern using different Google Cloud database services for vector search.

QnA Agent with AlloyDB

• Directory: RAG/rag-with-alloydb/
• Description: An agent that implements the RAG pattern using AlloyDB for PostgreSQL for vector search.
• Features:
  • Demonstrates using AlloyDB as a vector store for RAG.
  • Includes data ingestion scripts for populating the vector database.
  • Provides instructions for local execution and deployment to Vertex AI Agent Engine.

For detailed setup and execution instructions, please see the RAG with AlloyDB Agent README.

QnA Agent with BigQuery

• Directory: RAG/rag-with-bigquery/
• Description: An agent that implements the RAG pattern using BigQuery for vector search.
• Features:
  • Demonstrates using BigQuery as a vector store for RAG.
  • Includes data ingestion scripts.
  • Provides instructions for local execution and deployment to Vertex AI Agent Engine.

For detailed setup and execution instructions, please see the RAG with BigQuery Agent README.

QnA Agent with BigQuery Hybrid Search

• Directory: RAG/rag-with-bigquery-hybridsearch/
• Description: An agent that implements the RAG pattern using BigQuery Hybrid Search — a single retrieval step that combines BigQuery VECTOR_SEARCH() (semantic similarity) with SEARCH() (full-text keyword matching).
• Features:
  • Hybrid Search: Combines semantic and full-text keyword search using Reciprocal Rank Fusion (RRF).
  • Two Modes: Supports rrf (default balance) and pre_filter (keyword-strict) modes.
  • langchain-bigquery-hybridsearch: Uses an extension of BigQueryVectorStore for hybrid retrieval.
  • Data Ingestion: Includes scripts to populate the BigQuery vector store.

For detailed setup and execution instructions, please see the RAG with BigQuery Hybrid Search Agent README.

DEO Negation-Aware RAG with BigQuery

• Directory: RAG/deo-rag-with-bigquery/
• Description: An agent that implements DEO (Direct Embedding Optimization) for negation-aware retrieval using BigQuery as the vector store.
• Features:
  • Negation-Aware Retrieval: Handles queries with exclusion intent using gradient-based embedding optimization.
  • BigQuery Vector Search: Uses BigQuery for efficient vector search on optimized embeddings.
  • Query Decomposition: Automatically decomposes complex queries into positive and negative intents.

For detailed setup and execution instructions, please see the DEO RAG with BigQuery README.

QnA Agent with Spanner

• Directory: RAG/rag-with-spanner/
• Description: An agent that implements the RAG pattern using Google Cloud Spanner for vector search.
• Features:
  • Demonstrates using Spanner as a vector store for RAG.
  • Includes data ingestion scripts.
  • Provides instructions for local execution and deployment to Vertex AI Agent Engine.

For detailed setup and execution instructions, please see the RAG with Spanner Agent README.

QnA Agent with Vector Search 2.0

• Directory: RAG/rag-with-vectorsearch-2.0/
• Description: An agent that implements the RAG pattern using Vertex AI Vector Search 2.0 as a unified vector and document store, eliminating the need for a separate database like Firestore or AlloyDB.
• Features:
  • Unified Architecture: Simplifies RAG by storing embeddings and source data together.
  • Auto-Embeddings: Automatically generates embeddings using Vertex AI models during ingestion.
  • Hybrid Search: Combines semantic and keyword search with Reciprocal Rank Fusion (RRF).
  • Integrated Testing: Includes a Jupyter notebook for verifying the deployed agent on Agent Engine.

For detailed setup and execution instructions, please see the RAG with Vector Search 2.0 README.

QnA Agent with Gemini File Search

• Directory: RAG/rag-with-file-search/
• Description: An agent that implements the RAG pattern using Gemini File Search, a fully managed RAG system within the Gemini API ecosystem.
• Features:
  • Fully Managed RAG: Hands-off file search store management (chunking, embedding, storage).
  • Auto-Ingestion: Automatically indexes files uploaded through the ADK Web UI.
  • Session Isolation: Supports data isolation between users via session-based metadata filters.
  • MIME Type Patching: Robust handling of various file types with automated MIME type correction.

For detailed setup and execution instructions, please see the RAG with Gemini File Search README.

More RAG Agents

This repository contains additional RAG agent implementations that demonstrate integration with various Google Cloud services. Below is a list of other available RAG agents:

• RAG Engine with Managed DB:

  • Directory: RAG/rag-engine-with-managed-db/
  • Description: An agent that leverages the managed Vertex AI RAG Engine with its own fully managed database, eliminating the need to manage a separate Vector Search index.
  • README: RAG Engine with Managed DB README

• RAG Engine with Vector Search:

  • Directory: RAG/rag-engine-with-vectorsearch/
  • Description: An agent that uses the managed Vertex AI RAG Engine with a Vertex AI Vector Search index as its backend for efficient, scalable document retrieval.
  • README: RAG Engine with Vector Search README

• RAG with Vector Search and Datastore:

  • Directory: RAG/rag-with-vectorsearch-ds/
  • Description: An agent that uses Vertex AI Vector Search as the vector store and Firestore in Datastore mode as the document store.
  • README: RAG with Vector Search and Datastore README

• RAG with Vector Search and GCS:

  • Directory: RAG/rag-with-vectorsearch-gcs/
  • Description: An agent that uses Vertex AI Vector Search as the vector store and Google Cloud Storage (GCS) as the document store.
  • README: RAG with Vector Search and GCS README

6. Graph RAG

This section includes agents that implement the Graph Retrieval-Augmented Generation (Graph RAG) pattern.

Graph RAG with Spanner

• Directory: Graph-RAG/graph-rag-with-spanner/
• Description: An agent that implements the Graph RAG pattern using Google Cloud Spanner Graph for knowledge graph storage and retrieval.
• Features:
  • Demonstrates using Spanner Graph as a knowledge graph store.
  • Includes data ingestion scripts using LLMGraphTransformer to extract nodes and relationships from documents.
  • Leverages concise retrieval using SpannerGraphStore.
• README: Graph RAG with Spanner README

Graph RAG with BigQuery

• Directory: Graph-RAG/graph-rag-with-bigquery/
• Description: An agent that implements the Graph RAG pattern using Google Cloud BigQuery Graph for knowledge graph storage and retrieval.
• Features:
  • Demonstrates using BigQuery Graph as a knowledge graph store.
  • Performs hybrid search using both vector similarity and graph traversal.
  • Leverages BigQueryGraphStore and BigQueryGraphVectorContextRetriever.
• README: Graph RAG with BigQuery README

PathRAG with Spanner

• Directory: Graph-RAG/pathrag-with-spanner/
• Description: An agent that implements the PathRAG (Path-based Retrieval Augmented Generation) pattern using the PathRAG library with configurable storage backends.
• Features:
  • Supports two storage backends: Google Cloud Spanner (production) and local file-based storage (development).
  • Uses QueryParam(only_need_context=True) to avoid double LLM calls — PathRAG returns raw context, ADK agent generates the final answer.
  • Includes sample document ingestion for quick testing.
• README: PathRAG with Spanner README

PathRAG with BigQuery

• Directory: Graph-RAG/pathrag-with-bigquery/
• Description: An agent that implements the PathRAG (Path-based Retrieval Augmented Generation) pattern using the Agent Development Kit (ADK) with Google Cloud BigQuery as the storage backend. It leverages the PathRAG library with the pathrag-bigquery storage plugin.
• Features:
  • Full BigQuery Integration: Uses BigQuery for all storage components (KV, Vector, Graph) via pathrag-bigquery.
  • Relational Path Retrieval: Searches BigQuery Property Graph and Vector Store to combine results into structured context.
  • Optimized LLM Usage: Uses QueryParam(only_need_context=True) to extract structured context from PathRAG and lets the ADK Agent generate the final answer, avoiding redundant LLM calls.
• README: PathRAG with BigQuery README

LightRAG with Spanner

• Directory: Graph-RAG/lightrag-with-spanner/
• Description: An agent that implements the LightRAG (Light Retrieval Augmented Generation) pattern using the Agent Development Kit (ADK) with Google Cloud Spanner as the storage backend. It leverages the LightRAG library with the lightrag-spanner storage plugin and Gemini models for LLM and embedding.
• Features:
  • Full Spanner Integration: Uses Spanner for all storage components (KV, Vector, Graph, DocStatus), eliminating the need for local file storage.
  • Hybrid Retrieval: Combines Knowledge Graph traversal and vector similarity search via Spanner.
  • Optimized LLM Usage: Uses QueryParam(only_need_context=True) to extract structured context from LightRAG and lets the ADK Agent generate the final answer, avoiding redundant LLM calls.
• README: LightRAG with Spanner README

LightRAG with BigQuery

• Directory: Graph-RAG/lightrag-with-bigquery/
• Description: An agent that implements the LightRAG (Light Retrieval Augmented Generation) pattern using the Agent Development Kit (ADK) with Google Cloud BigQuery as the storage backend. It leverages the LightRAG library with the lightrag-bigquery storage plugin and Gemini models for LLM and embedding.
• Features:
  • Full BigQuery Integration: Uses BigQuery for all storage components (KV, Vector, Graph, DocStatus) via lightrag-bigquery.
  • Hybrid Retrieval: Combines Knowledge Graph traversal and vector similarity search via BigQuery.
  • Optimized LLM Usage: Uses QueryParam(only_need_context=True) to extract structured context from LightRAG and lets the ADK Agent generate the final answer, avoiding redundant LLM calls.
• README: LightRAG with BigQuery README

7. ADK BigQuery Logging Plugin Example

• Directory: plugins/bigquery-logging-plugin/
• Description: A sample agent demonstrating how to use the BigQueryAgentAnalyticsPlugin to log agent interactions and analytics to Google BigQuery. This enables monitoring agent performance, debugging issues, and gaining insights into user interactions.
• Features:
  • Captures events such as tool calls, agent responses, and errors.
  • Stores analytics data in a structured BigQuery table.

For detailed setup and execution instructions, please see the ADK BigQuery Logging Plugin Example README.

8. Agent Memory

This section includes agents that demonstrate how to manage agent memory and session state.

ADK Redis Session Service

• Directory: agent-memory/redis-session-service/
• Description: An agent that demonstrates how to use Redis for session state management, allowing for scalable and persistent user sessions.
• Features:
  • Integrates a custom session service with ADK.
  • Persists conversation state in a Redis database.
  • Includes instructions for local execution and deployment to Cloud Run.

For detailed setup and execution instructions, please see the ADK Redis Session Service README.

ADK Redis Memory Service

• Directory: agent-memory/redis-memory-service/
• Description: An agent demonstrating a custom long-term memory service using Redis. It leverages Redis's Vector Search for searchable, personalized memories, enhancing continuity across user conversations.
• Features:
  • Demonstrates implementing a custom long-term memory service using Redis.
  • Leverages Redis's Vector Search for searchable, long-term knowledge storage.
  • Enhances personalization and continuity across user conversations.

For detailed setup and execution instructions, please see the ADK Redis Memory Service README.

BigQuery Data Agent with Agent Engine Memory Bank

• Directory: agent-memory/bigquery-data-agent-with-dynamic-context/
• Description: A self-learning BigQuery agent that converts natural language to SQL and improves over time by saving successful queries to the Vertex AI Agent Engine Memory Bank.
• Features:
  • Natural Language to SQL: Converts user questions into syntactically correct BigQuery SQL.
  • Dynamic Context: Automatically searches for relevant past queries to improve accuracy.
  • Scoped Memory: Supports user (private) and team (shared) memory scopes for personalized and collaborative analysis.
  • Agent Engine Integration: Leverages the managed Memory Bank service for scalable and secure memory storage.

For detailed setup and execution instructions, please see the BigQuery Data Agent README.

9. Dynamic MCP Agent

• Directory: dynamic-tool-search-tool/
• Description: An advanced agent that demonstrates dynamic discovery and loading of tools from Google Managed MCP servers. It uses a "Search & Load" pattern to support vast tool libraries efficiently.
• Features:
  • Dynamic tool injection via the after_tool_callback mechanism.
  • High scalability, supporting hundreds of tools with minimal overhead.
  • Uses BM25 search to find relevant tools based on user intent.

For detailed setup and execution instructions, please see the Dynamic MCP Agent README.

References

• ADK Official Docs
  • ADK Python Repository
  • ADK Crash Course - From Beginner To Expert
  • Google ADK Masterclass
• ADK Python Community Contributions
• ADK Samples Repo
• Agentic Design Patterns
• ADK Web Book by Amulya Bhatia