chore: Add sample agent for content cache and basic profiling

PiperOrigin-RevId: 809166922

Author: seanzhougoogle

contributing/samples/cache_analysis/README.md

@@ -0,0 +1,114 @@
+# Cache Analysis Research Assistant
+
+This sample demonstrates ADK context caching features with a comprehensive research assistant agent designed to test both Gemini 2.0 Flash and 2.5 Flash context caching capabilities. The sample showcases the difference between explicit ADK caching and Google's built-in implicit caching.
+
+## Key Features
+
+- **App-Level Cache Configuration**: Context cache settings applied at the App level
+- **Large Context Instructions**: Over 4200 tokens in system instructions to trigger context caching thresholds
+- **Comprehensive Tool Suite**: 7 specialized research and analysis tools
+- **Multi-Model Support**: Compatible with any Gemini model, automatically adapts experiment type
+- **Performance Metrics**: Detailed token usage tracking including `cached_content_token_count`
+
+## Cache Configuration
+
+```python
+ContextCacheConfig(
+     min_tokens=4096,
+        ttl_seconds=600,  # 10 mins for research sessions
+        cache_intervals=3,  # Maximum invocations before cache invalidation
+```
+
+## Usage
+
+### Run Cache Experiments
+
+The `run_cache_experiments.py` script compares caching performance between models:
+
+```bash
+# Test any Gemini model - script automatically determines experiment type
+python run_cache_experiments.py <model_name> --output results.json
+
+# Examples:
+python run_cache_experiments.py gemini-2.0-flash-001 --output gemini_2_0_results.json
+python run_cache_experiments.py gemini-2.5-flash --output gemini_2_5_results.json
+python run_cache_experiments.py gemini-1.5-flash --output gemini_1_5_results.json
+
+# Run multiple iterations for averaged results
+python run_cache_experiments.py <model_name> --repeat 3 --output averaged_results.json
+```
+
+### Direct Agent Usage
+
+```bash
+# Run the agent directly
+adk run contributing/samples/cache_analysis/agent.py
+
+# Web interface for debugging
+adk web contributing/samples/cache_analysis
+```
+
+## Experiment Types
+
+The script automatically determines the experiment type based on the model name:
+
+### Models with "2.5" (e.g., gemini-2.5-flash)
+- **Explicit Caching**: ADK explicit caching + Google's implicit caching
+- **Implicit Only**: Google's built-in implicit caching alone
+- **Measures**: Added benefit of explicit caching over Google's built-in implicit caching
+
+### Other Models (e.g., gemini-2.0-flash-001, gemini-1.5-flash)
+- **Cached**: ADK explicit context caching enabled
+- **Uncached**: No caching (baseline comparison)
+- **Measures**: Raw performance improvement from explicit caching vs no caching
+
+## Tools Included
+
+1. **analyze_data_patterns** - Statistical analysis and pattern recognition in datasets
+2. **research_literature** - Academic and professional literature research with citations
+3. **generate_test_scenarios** - Comprehensive test case generation and validation strategies
+4. **benchmark_performance** - System performance measurement and bottleneck analysis
+5. **optimize_system_performance** - Performance optimization recommendations and strategies
+6. **analyze_security_vulnerabilities** - Security risk assessment and vulnerability analysis
+7. **design_scalability_architecture** - Scalable system architecture design and planning
+
+## Expected Results
+
+### Performance vs Cost Trade-offs
+
+**Note**: This sample uses a tool-heavy agent that may show different performance characteristics than simple text-based agents.
+
+### Performance Improvements
+- **Simple Text Agents**: Typically see 30-70% latency reduction with caching
+- **Tool-Heavy Agents**: May experience higher latency due to cache setup overhead, but still provide cost benefits
+- **Gemini 2.5 Flash**: Compares explicit ADK caching against Google's built-in implicit caching
+
+### Cost Savings
+- **Input Token Cost**: 75% reduction for cached content (25% of normal cost)
+- **Typical Savings**: 30-60% on input costs for multi-turn conversations
+- **Tool-Heavy Workloads**: Cost savings often outweigh latency trade-offs
+
+### Token Metrics
+- **Cached Content Token Count**: Non-zero values indicating successful cache hits
+- **Cache Hit Ratio**: Proportion of tokens served from cache vs fresh computation
+
+## Troubleshooting
+
+### Zero Cached Tokens
+If `cached_content_token_count` is always 0:
+- Verify model names match exactly (e.g., `gemini-2.0-flash-001`)
+- Check that cache configuration `min_tokens` threshold is met
+- Ensure proper App-based configuration is used
+
+### Session Errors
+If seeing "Session not found" errors:
+- Verify `runner.app_name` is used for session creation
+- Check App vs Agent object usage in InMemoryRunner initialization
+
+## Technical Implementation
+
+This sample demonstrates:
+- **Modern App Architecture**: App-level cache configuration following ADK best practices
+- **Integration Testing**: Comprehensive cache functionality validation
+- **Performance Analysis**: Detailed metrics collection and comparison methodology
+- **Error Handling**: Robust session management and cache invalidation handling

contributing/samples/cache_analysis/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2025 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
+
+__all__ = ['agent']