From 4752f3f993e59aac2df24e9f5d283174dfd9ca24 Mon Sep 17 00:00:00 2001
From: "Xiang (Sean) Zhou" <seanzhougoogle@google.com>
Date: Mon, 16 Mar 2026 12:11:30 -0700
Subject: [PATCH] chore: Add a sample agent for files_retrieval tool

this sample can be used to test the latest gemini embedding model

Co-authored-by: Xiang (Sean) Zhou <seanzhougoogle@google.com>
PiperOrigin-RevId: 884574396
---
 .../samples/files_retrieval_agent/README.md   | 76 +++++++++++++++++++
 .../samples/files_retrieval_agent/__init__.py | 15 ++++
 .../samples/files_retrieval_agent/agent.py    | 54 +++++++++++++
 .../data/adk_overview.txt                     | 23 ++++++
 .../data/tools_guide.txt                      | 28 +++++++
 5 files changed, 196 insertions(+)
 create mode 100644 contributing/samples/files_retrieval_agent/README.md
 create mode 100644 contributing/samples/files_retrieval_agent/__init__.py
 create mode 100644 contributing/samples/files_retrieval_agent/agent.py
 create mode 100644 contributing/samples/files_retrieval_agent/data/adk_overview.txt
 create mode 100644 contributing/samples/files_retrieval_agent/data/tools_guide.txt

diff --git a/contributing/samples/files_retrieval_agent/README.md b/contributing/samples/files_retrieval_agent/README.md
new file mode 100644
index 00000000..57b16e74
--- /dev/null
+++ b/contributing/samples/files_retrieval_agent/README.md
@@ -0,0 +1,76 @@
+# Files Retrieval Agent
+
+A sample agent that demonstrates using `FilesRetrieval` with the
+`gemini-embedding-2-preview` embedding model for retrieval-augmented
+generation (RAG) over local files.
+
+## What it does
+
+This agent indexes local text files from the `data/` directory using
+`FilesRetrieval` (backed by LlamaIndex's `VectorStoreIndex` and Google's
+`gemini-embedding-2-preview` embedding model), then answers user questions
+by retrieving relevant documents before generating a response.
+
+## Prerequisites
+
+- Python 3.11+
+- `google-genai >= 1.64.0` (required for `gemini-embedding-2-preview`
+  support via the Vertex AI `embedContent` endpoint)
+- `llama-index-embeddings-google-genai >= 0.3.0`
+
+Install dependencies:
+
+```bash
+uv sync --all-extras
+```
+
+## Authentication
+
+Configure one of the following:
+
+**Google AI API:**
+
+```bash
+export GOOGLE_API_KEY="your-api-key"
+```
+
+**Vertex AI:**
+
+```bash
+export GOOGLE_GENAI_USE_VERTEXAI=1
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+export GOOGLE_CLOUD_LOCATION="us-central1"
+```
+
+Note: `gemini-embedding-2-preview` is currently only available in
+`us-central1`.
+
+## Usage
+
+```bash
+cd contributing/samples
+
+# Interactive CLI
+adk run files_retrieval_agent
+
+# Web UI
+adk web .
+```
+
+## Example queries
+
+- "What agent types does ADK support?"
+- "How does FilesRetrieval work?"
+- "What tools are available in ADK?"
+
+## File structure
+
+```
+files_retrieval_agent/
+├── __init__.py
+├── agent.py           # Agent definition with FilesRetrieval tool
+├── data/
+│   ├── adk_overview.txt   # ADK architecture overview
+│   └── tools_guide.txt    # ADK tools documentation
+└── README.md
+```
diff --git a/contributing/samples/files_retrieval_agent/__init__.py b/contributing/samples/files_retrieval_agent/__init__.py
new file mode 100644
index 00000000..4015e47d
--- /dev/null
+++ b/contributing/samples/files_retrieval_agent/__init__.py
@@ -0,0 +1,15 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from . import agent
diff --git a/contributing/samples/files_retrieval_agent/agent.py b/contributing/samples/files_retrieval_agent/agent.py
new file mode 100644
index 00000000..7b1209b8
--- /dev/null
+++ b/contributing/samples/files_retrieval_agent/agent.py
@@ -0,0 +1,54 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Sample agent using FilesRetrieval with gemini-embedding-2-preview.
+
+This agent indexes local text files and answers questions about them
+using retrieval-augmented generation.
+
+Usage:
+  cd contributing/samples
+  adk run files_retrieval_agent
+  # or
+  adk web .
+"""
+
+import os
+
+from google.adk.agents.llm_agent import Agent
+from google.adk.tools.retrieval.files_retrieval import FilesRetrieval
+
+DATA_DIR = os.path.join(os.path.dirname(__file__), "data")
+
+files_retrieval = FilesRetrieval(
+    name="search_documents",
+    description=(
+        "Search through local ADK documentation files to find relevant"
+        " information. Use this tool when the user asks questions about ADK"
+        " features, architecture, or tools."
+    ),
+    input_dir=DATA_DIR,
+)
+
+root_agent = Agent(
+    model="gemini-2.0-flash",
+    name="files_retrieval_agent",
+    instruction=(
+        "You are a helpful assistant that answers questions about the Agent"
+        " Development Kit (ADK). Use the search_documents tool to find"
+        " relevant information before answering. Always base your answers"
+        " on the retrieved documents."
+    ),
+    tools=[files_retrieval],
+)
diff --git a/contributing/samples/files_retrieval_agent/data/adk_overview.txt b/contributing/samples/files_retrieval_agent/data/adk_overview.txt
new file mode 100644
index 00000000..5e2f08e3
--- /dev/null
+++ b/contributing/samples/files_retrieval_agent/data/adk_overview.txt
@@ -0,0 +1,23 @@
+Agent Development Kit (ADK) Overview
+
+ADK is a Python framework for building AI agents powered by large language models.
+It provides a structured way to create agents that can reason, use tools, and
+collaborate with other agents.
+
+Key Features:
+- Multi-agent orchestration with sequential, parallel, and loop patterns
+- Built-in tool support including function tools, retrieval, and code execution
+- Session management for maintaining conversation state
+- Memory services for long-term recall across sessions
+- Support for multiple LLM backends including Gemini, Anthropic, and Ollama
+
+Architecture:
+The core abstractions are Agent, Runner, Tool, Session, and Memory.
+The Runner orchestrates the reason-act loop, processing user turns and
+streaming events back to the caller.
+
+Agent Types:
+- LlmAgent: Main agent with LLM integration
+- SequentialAgent: Runs sub-agents in sequence
+- ParallelAgent: Runs sub-agents in parallel
+- LoopAgent: Runs sub-agents in a loop
diff --git a/contributing/samples/files_retrieval_agent/data/tools_guide.txt b/contributing/samples/files_retrieval_agent/data/tools_guide.txt
new file mode 100644
index 00000000..487e2f5e
--- /dev/null
+++ b/contributing/samples/files_retrieval_agent/data/tools_guide.txt
@@ -0,0 +1,28 @@
+ADK Tools Guide
+
+Tools are capabilities that agents can invoke during their reasoning process.
+ADK supports several types of tools:
+
+1. Function Tools
+   Define Python functions and pass them directly to an agent.
+   The function signature and docstring become the tool schema.
+
+2. Retrieval Tools
+   - FilesRetrieval: Index and search local files using embeddings.
+     Uses gemini-embedding-2-preview by default.
+   - VertexAiRagRetrieval: Search Vertex AI RAG corpora.
+
+3. Code Execution
+   Agents can generate and execute code in a sandboxed environment.
+
+4. Third-Party Tool Integration
+   - LangchainTool: Wraps LangChain tools for use in ADK.
+   - CrewaiTool: Wraps CrewAI tools for use in ADK.
+
+5. MCP Tools
+   Connect to Model Context Protocol servers for external tool access.
+
+Tool Configuration:
+Tools can be configured with authentication, rate limiting, and custom
+schemas. The ToolContext provides access to session state, artifacts,
+and other contextual information during tool execution.