{"id":48810097,"url":"https://github.com/ksmin23/my-adk-python-samples","last_synced_at":"2026-04-14T06:34:51.142Z","repository":{"id":304976712,"uuid":"1018359890","full_name":"ksmin23/my-adk-python-samples","owner":"ksmin23","description":"A collection of Python agent samples built with the Google Agent Development Kit (ADK), demonstrating integrations   with services like BigQuery and Vertex AI Search.","archived":false,"fork":false,"pushed_at":"2026-04-10T08:24:03.000Z","size":12768,"stargazers_count":15,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-10T10:29:57.448Z","etag":null,"topics":["adk-python","ai-agents","generative-ai","google-cloud","mcp-tool-box-for-databases","vertex-ai-search-for-commerce"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ksmin23.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-12T05:17:08.000Z","updated_at":"2026-04-08T01:03:57.000Z","dependencies_parsed_at":"2025-08-20T09:15:00.926Z","dependency_job_id":"910aca44-53cd-4d2f-b7f2-f23cbed8eca1","html_url":"https://github.com/ksmin23/my-adk-python-samples","commit_stats":null,"previous_names":["ksmin23/my-adk-python-samples"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ksmin23/my-adk-python-samples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksmin23%2Fmy-adk-python-samples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksmin23%2Fmy-adk-python-samples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksmin23%2Fmy-adk-python-samples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksmin23%2Fmy-adk-python-samples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ksmin23","download_url":"https://codeload.github.com/ksmin23/my-adk-python-samples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ksmin23%2Fmy-adk-python-samples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31785677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T02:24:21.117Z","status":"ssl_error","status_checked_at":"2026-04-14T02:24:20.627Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adk-python","ai-agents","generative-ai","google-cloud","mcp-tool-box-for-databases","vertex-ai-search-for-commerce"],"created_at":"2026-04-14T06:34:51.080Z","updated_at":"2026-04-14T06:34:51.134Z","avatar_url":"https://github.com/ksmin23.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Google Agent Development Kit (ADK) - Python Samples\n\nThis repository contains a collection of sample agents built using the [Google Agent Development Kit (ADK)](https://developers.google.com/agent-development-kit). Each sample is a self-contained application demonstrating different use cases and integrations.\n\n## Table of Contents\n\n- [General Prerequisites](#general-prerequisites)\n- [Available Agents](#available-agents)\n  - [1. GCP Release Notes Agent](#1-gcp-release-notes-agent)\n  - [2. Shop Search Agent](#2-shop-search-agent)\n  - [3. Restaurant Finder Agent](#3-restaurant-finder-agent)\n  - [4. Shopper's Concierge Agent](#4-shoppers-concierge-agent)\n  - [5. Agentic RAG](#5-agentic-rag)\n    - [QnA Agent with AlloyDB](#qna-agent-with-alloydb)\n    - [QnA Agent with BigQuery](#qna-agent-with-bigquery)\n    - [DEO Negation-Aware RAG with BigQuery](#deo-negation-aware-rag-with-bigquery)\n    - [QnA Agent with Spanner](#qna-agent-with-spanner)\n    - [QnA Agent with Vector Search 2.0](#qna-agent-with-vector-search-20)\n    - [QnA Agent with Gemini File Search](#qna-agent-with-gemini-file-search)\n    - [More RAG Agents](#more-rag-agents)\n  - [6. Graph RAG](#6-graph-rag)\n    - [Graph RAG with Spanner](#graph-rag-with-spanner)\n    - [PathRAG with Spanner](#pathrag-with-spanner)\n    - [LightRAG with Spanner](#lightrag-with-spanner)\n  - [7. ADK BigQuery Logging Plugin Example](#7-adk-bigquery-logging-plugin-example)\n  - [8. Agent Memory](#8-agent-memory)\n    - [ADK Redis Session Service](#adk-redis-session-service)\n    - [ADK Redis Memory Service](#adk-redis-memory-service)\n    - [BigQuery Data Agent with Agent Engine Memory Bank](#bigquery-data-agent-with-agent-engine-memory-bank)\n  - [9. Dynamic MCP Agent](#9-dynamic-mcp-agent)\n- [References](#references)\n\n## General Prerequisites\n\n-   [Python 3.x](https://www.python.org/)\n-   [Google Cloud SDK](https://cloud.google.com/sdk/docs/install)\n-   [Google Agent Development Kit (ADK)](https://developers.google.com/agent-development-kit/docs)\n\nPlease refer to the individual agent directories for specific dependencies and configuration steps.\n\n## Available Agents\n\n### 1. GCP Release Notes Agent\n\n-   **Directory**: [`gcp-releasenotes-agent-app/`](./gcp-releasenotes-agent-app/)\n-   **Description**: An agent designed to answer questions about Google Cloud release notes. It connects to a [MCP Toolbox for Databases](https://googleapis.github.io/genai-toolbox/getting-started/) service that queries a public BigQuery dataset.\n-   **Features**:\n    -   Demonstrates integration with a BigQuery-backed MCP Toolbox.\n    -   Includes instructions for deploying the toolbox service to Cloud Run.\n\nFor detailed setup and execution instructions, please see the [GCP Release Notes Agent README](./gcp-releasenotes-agent-app/README.md).\n\n### 2. Shop Search Agent\n\n-   **Directory**: [`shop-agent-app/`](./shop-agent-app/)\n-   **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.\n-   **Features**:\n    -   Illustrates how to connect an agent to a custom MCP server.\n    -   Provides a clear example of a retail or e-commerce use case.\n\nFor detailed setup and execution instructions, please see the [Shop Search Agent README](./shop-agent-app/README.md).\n\n### 3. Restaurant Finder Agent\n\n-   **Directory**: [`restaurant-finder/`](./restaurant-finder/)\n-   **Description**: A conversational AI agent that helps users find restaurants based on a specific dish or ingredient, leveraging the Google Maps Platform API.\n-   **Features**:\n    -   Demonstrates how an agent can use external tools (Google Maps API) to answer user queries.\n    -   Provides real-time restaurant information.\n\nFor detailed setup and execution instructions, please see the [Restaurant Finder Agent README](./restaurant-finder/README.md).\n\n### 4. Shopper's Concierge Agent\n\n-   **Directory**: [`shopper-concierge-demo/`](./shopper-concierge-demo/)\n-   **Description**: An advanced shopping assistant that uses a sub-agent for research to provide more relevant product recommendations.\n-   **Features**:\n    -   Showcases a multi-agent architecture where a primary agent delegates tasks to a specialized sub-agent.\n    -   Includes a Gradio web interface for a complete user experience.\n\nFor detailed setup and execution instructions, please see the [Shopper's Concierge Agent README](./shopper-concierge-demo/README.md).\n\n### 5. Agentic RAG\n\nThis section includes agents that implement the Retrieval-Augmented Generation (RAG) pattern using different Google Cloud database services for vector search.\n\n#### QnA Agent with AlloyDB\n\n-   **Directory**: [`RAG/rag-with-alloydb/`](./RAG/rag-with-alloydb/)\n-   **Description**: An agent that implements the RAG pattern using AlloyDB for PostgreSQL for vector search.\n-   **Features**:\n    -   Demonstrates using AlloyDB as a vector store for RAG.\n    -   Includes data ingestion scripts for populating the vector database.\n    -   Provides instructions for local execution and deployment to Vertex AI Agent Engine.\n\nFor detailed setup and execution instructions, please see the [RAG with AlloyDB Agent README](./RAG/rag-with-alloydb/README.md).\n\n#### QnA Agent with BigQuery\n\n-   **Directory**: [`RAG/rag-with-bigquery/`](./RAG/rag-with-bigquery/)\n-   **Description**: An agent that implements the RAG pattern using BigQuery for vector search.\n-   **Features**:\n    -   Demonstrates using BigQuery as a vector store for RAG.\n    -   Includes data ingestion scripts.\n    -   Provides instructions for local execution and deployment to Vertex AI Agent Engine.\n\nFor detailed setup and execution instructions, please see the [RAG with BigQuery Agent README](./RAG/rag-with-bigquery/README.md).\n\n#### DEO Negation-Aware RAG with BigQuery\n\n-   **Directory**: [`RAG/deo-rag-with-bigquery/`](./RAG/deo-rag-with-bigquery/)\n-   **Description**: An agent that implements **DEO (Direct Embedding Optimization)** for negation-aware retrieval using BigQuery as the vector store.\n-   **Features**:\n    -   **Negation-Aware Retrieval**: Handles queries with exclusion intent using gradient-based embedding optimization.\n    -   **BigQuery Vector Search**: Uses BigQuery for efficient vector search on optimized embeddings.\n    -   **Query Decomposition**: Automatically decomposes complex queries into positive and negative intents.\n\nFor detailed setup and execution instructions, please see the [DEO RAG with BigQuery README](./RAG/deo-rag-with-bigquery/README.md).\n\n#### QnA Agent with Spanner\n\n-   **Directory**: [`RAG/rag-with-spanner/`](./RAG/rag-with-spanner/)\n-   **Description**: An agent that implements the RAG pattern using Google Cloud Spanner for vector search.\n-   **Features**:\n    -   Demonstrates using Spanner as a vector store for RAG.\n    -   Includes data ingestion scripts.\n    -   Provides instructions for local execution and deployment to Vertex AI Agent Engine.\n\nFor detailed setup and execution instructions, please see the [RAG with Spanner Agent README](./RAG/rag-with-spanner/README.md).\n\n#### QnA Agent with Vector Search 2.0\n\n-   **Directory**: [`RAG/rag-with-vectorsearch-2.0/`](./RAG/rag-with-vectorsearch-2.0/)\n-   **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.\n-   **Features**:\n    -   **Unified Architecture**: Simplifies RAG by storing embeddings and source data together.\n    -   **Auto-Embeddings**: Automatically generates embeddings using Vertex AI models during ingestion.\n    -   **Hybrid Search**: Combines semantic and keyword search with Reciprocal Rank Fusion (RRF).\n    -   **Integrated Testing**: Includes a Jupyter notebook for verifying the deployed agent on Agent Engine.\n\nFor detailed setup and execution instructions, please see the [RAG with Vector Search 2.0 README](./RAG/rag-with-vectorsearch-2.0/README.md).\n\n#### QnA Agent with Gemini File Search\n\n-   **Directory**: [`RAG/rag-with-file-search/`](./RAG/rag-with-file-search/)\n-   **Description**: An agent that implements the RAG pattern using **Gemini File Search**, a fully managed RAG system within the Gemini API ecosystem.\n-   **Features**:\n    -   **Fully Managed RAG**: Hands-off file search store management (chunking, embedding, storage).\n    -   **Auto-Ingestion**: Automatically indexes files uploaded through the ADK Web UI.\n    -   **Session Isolation**: Supports data isolation between users via session-based metadata filters.\n    -   **MIME Type Patching**: Robust handling of various file types with automated MIME type correction.\n\nFor detailed setup and execution instructions, please see the [RAG with Gemini File Search README](./RAG/rag-with-file-search/README.md).\n\n#### More RAG Agents\n\nThis repository contains additional RAG agent implementations that demonstrate integration with various Google Cloud services. Below is a list of other available RAG agents:\n\n-   **RAG Engine with Managed DB**:\n    -   **Directory**: [`RAG/rag-engine-with-managed-db/`](./RAG/rag-engine-with-managed-db/)\n    -   **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.\n    -   **README**: [RAG Engine with Managed DB README](./RAG/rag-engine-with-managed-db/README.md)\n\n-   **RAG Engine with Vector Search**:\n    -   **Directory**: [`RAG/rag-engine-with-vectorsearch/`](./RAG/rag-engine-with-vectorsearch/)\n    -   **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.\n    -   **README**: [RAG Engine with Vector Search README](./RAG/rag-engine-with-vectorsearch/README.md)\n\n-   **RAG with Vector Search and Datastore**:\n    -   **Directory**: [`RAG/rag-with-vectorsearch-ds/`](./RAG/rag-with-vectorsearch-ds/)\n    -   **Description**: An agent that uses Vertex AI Vector Search as the vector store and Firestore in Datastore mode as the document store.\n    -   **README**: [RAG with Vector Search and Datastore README](./RAG/rag-with-vectorsearch-ds/README.md)\n\n-   **RAG with Vector Search and GCS**:\n    -   **Directory**: [`RAG/rag-with-vectorsearch-gcs/`](./RAG/rag-with-vectorsearch-gcs/)\n    -   **Description**: An agent that uses Vertex AI Vector Search as the vector store and Google Cloud Storage (GCS) as the document store.\n    -   **README**: [RAG with Vector Search and GCS README](./RAG/rag-with-vectorsearch-gcs/README.md)\n\n### 6. Graph RAG\n\nThis section includes agents that implement the Graph Retrieval-Augmented Generation (Graph RAG) pattern.\n\n#### Graph RAG with Spanner\n\n-   **Directory**: [`Graph-RAG/graph-rag-with-spanner/`](./Graph-RAG/graph-rag-with-spanner/)\n-   **Description**: An agent that implements the Graph RAG pattern using Google Cloud Spanner Graph for knowledge graph storage and retrieval.\n-   **Features**:\n    -   Demonstrates using Spanner Graph as a knowledge graph store.\n    -   Includes data ingestion scripts using `LLMGraphTransformer` to extract nodes and relationships from documents.\n    -   Leverages concise retrieval using `SpannerGraphStore`.\n-   **README**: [Graph RAG with Spanner README](./Graph-RAG/graph-rag-with-spanner/README.md)\n\n#### PathRAG with Spanner\n\n-   **Directory**: [`Graph-RAG/pathrag-with-spanner/`](./Graph-RAG/pathrag-with-spanner/)\n-   **Description**: An agent that implements the PathRAG (Path-based Retrieval Augmented Generation) pattern using the [PathRAG](https://github.com/ksmin23/PathRAG) library with configurable storage backends.\n-   **Features**:\n    -   Supports two storage backends: Google Cloud Spanner (production) and local file-based storage (development).\n    -   Uses `QueryParam(only_need_context=True)` to avoid double LLM calls — PathRAG returns raw context, ADK agent generates the final answer.\n    -   Includes sample document ingestion for quick testing.\n-   **README**: [PathRAG with Spanner README](./Graph-RAG/pathrag-with-spanner/README.md)\n\n#### LightRAG with Spanner\n\n-   **Directory**: [`Graph-RAG/lightrag-with-spanner/`](./Graph-RAG/lightrag-with-spanner/)\n-   **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](https://github.com/HKUDS/LightRAG) library with the [lightrag-spanner](https://github.com/ksmin23/lightrag-spanner) storage plugin and Gemini models for LLM and embedding.\n-   **Features**:\n    -   **Full Spanner Integration**: Uses Spanner for all storage components (KV, Vector, Graph, DocStatus), eliminating the need for local file storage.\n    -   **Hybrid Retrieval**: Combines Knowledge Graph traversal and vector similarity search via Spanner.\n    -   **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.\n-   **README**: [LightRAG with Spanner README](./Graph-RAG/lightrag-with-spanner/README.md)\n\n### 7. ADK BigQuery Logging Plugin Example\n\n-   **Directory**: [`plugins/bigquery-logging-plugin/`](./plugins/bigquery-logging-plugin/)\n-   **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.\n-   **Features**:\n    -   Captures events such as tool calls, agent responses, and errors.\n    -   Stores analytics data in a structured BigQuery table.\n\nFor detailed setup and execution instructions, please see the [ADK BigQuery Logging Plugin Example README](./plugins/bigquery-logging-plugin/README.md).\n\n### 8. Agent Memory\n\nThis section includes agents that demonstrate how to manage agent memory and session state.\n\n#### ADK Redis Session Service\n\n-   **Directory**: [`agent-memory/redis-session-service/`](./agent-memory/redis-session-service/)\n-   **Description**: An agent that demonstrates how to use Redis for session state management, allowing for scalable and persistent user sessions.\n-   **Features**:\n    -   Integrates a custom session service with ADK.\n    -   Persists conversation state in a Redis database.\n    -   Includes instructions for local execution and deployment to Cloud Run.\n\nFor detailed setup and execution instructions, please see the [ADK Redis Session Service README](./agent-memory/redis-session-service/README.md).\n\n#### ADK Redis Memory Service\n\n-   **Directory**: [`agent-memory/redis-memory-service/`](./agent-memory/redis-memory-service/)\n-   **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.\n-   **Features**:\n    -   Demonstrates implementing a custom long-term memory service using Redis.\n    -   Leverages Redis's Vector Search for searchable, long-term knowledge storage.\n    -   Enhances personalization and continuity across user conversations.\n\nFor detailed setup and execution instructions, please see the [ADK Redis Memory Service README](./agent-memory/redis-memory-service/README.md).\n\n#### BigQuery Data Agent with Agent Engine Memory Bank\n\n-   **Directory**: [`agent-memory/bigquery-data-agent-with-dynamic-context/`](./agent-memory/bigquery-data-agent-with-dynamic-context/)\n-   **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](https://docs.cloud.google.com/agent-builder/agent-engine/memory-bank/overview).\n-   **Features**:\n    -   **Natural Language to SQL**: Converts user questions into syntactically correct BigQuery SQL.\n    -   **Dynamic Context**: Automatically searches for relevant past queries to improve accuracy.\n    -   **Scoped Memory**: Supports `user` (private) and `team` (shared) memory scopes for personalized and collaborative analysis.\n    -   **Agent Engine Integration**: Leverages the managed Memory Bank service for scalable and secure memory storage.\n\nFor detailed setup and execution instructions, please see the [BigQuery Data Agent README](./agent-memory/bigquery-data-agent-with-dynamic-context/README.md).\n\n### 9. Dynamic MCP Agent\n\n-   **Directory**: [`dynamic-tool-search-tool/`](./dynamic-tool-search-tool/)\n-   **Description**: An advanced agent that demonstrates dynamic discovery and loading of tools from Google Managed MCP servers. It uses a \"Search \u0026 Load\" pattern to support vast tool libraries efficiently.\n-   **Features**:\n    -   Dynamic tool injection via the `after_tool_callback` mechanism.\n    -   High scalability, supporting hundreds of tools with minimal overhead.\n    -   Uses BM25 search to find relevant tools based on user intent.\n\nFor detailed setup and execution instructions, please see the [Dynamic MCP Agent README](./dynamic-tool-search-tool/README.md).\n\n## References\n\n-   [ADK Official Docs](https://google.github.io/adk-docs/)\n    -   [ADK Python Repository](https://github.com/google/adk-python)\n    - [ADK Crash Course - From Beginner To Expert](https://codelabs.developers.google.com/onramp/instructions#0)\n    - [Google ADK Masterclass](https://github.com/arjunprabhulal/google-adk-masterclass)\n-   [ADK Python Community Contributions](https://github.com/google/adk-python-community)\n-   [ADK Samples Repo](https://github.com/google/adk-samples)\n-   [Agentic Design Patterns](https://docs.google.com/document/d/1rsaK53T3Lg5KoGwvf8ukOUvbELRtH-V0LnOIFDxBryE/preview?tab=t.0#heading=h.pxcur8v2qagu)\n-   [ADK Web Book by Amulya Bhatia](https://iamulya.one/tags/agent-development-kit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksmin23%2Fmy-adk-python-samples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fksmin23%2Fmy-adk-python-samples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fksmin23%2Fmy-adk-python-samples/lists"}