google--adk-python/contributing/samples/context_management/cache_analysis

Cache Analysis Research Assistant

Overview

This sample demonstrates ADK context caching features using 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 following ADK best practices.
• Large Context Instructions: Over 4,200 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 adapting the experiment type.
• Performance Metrics: Detailed token usage tracking, including cached_content_token_count.

Sample Inputs

• Hello, what can you do for me?

  General question that does not trigger function calls, serving as a baseline query.

• What is artificial intelligence and how does it work in modern applications?

  General question exploring domain knowledge without specific tool requests.

• Use benchmark_performance with system_name='E-commerce Platform', metrics=['latency', 'throughput'], duration='standard', load_profile='realistic'.

  Specific request triggering the benchmark_performance tool with explicit parameters.

• Call analyze_user_behavior_patterns with user_segment='premium_customers', time_period='last_30_days', metrics=['engagement', 'conversion'].

  Specific request triggering data analysis tools with required parameters.

Graph

graph TD
    Agent[Agent: cache_analysis_assistant] --> Tool1[Tool: analyze_data_patterns]
    Agent --> Tool2[Tool: research_literature]
    Agent --> Tool3[Tool: generate_test_scenarios]
    Agent --> Tool4[Tool: benchmark_performance]
    Agent --> Tool5[Tool: optimize_system_performance]
    Agent --> Tool6[Tool: analyze_security_vulnerabilities]
    Agent --> Tool7[Tool: design_scalability_architecture]

How To

1. Cache Configuration

Context caching is configured at the App level using ContextCacheConfig. This ensures that the agent's extensive system instructions and tool definitions are cached for repeated invocations.

from google.adk.agents.context_cache_config import ContextCacheConfig
from google.adk.apps.app import App

cache_analysis_app = App(
    name="cache_analysis",
    root_agent=cache_analysis_agent,
    context_cache_config=ContextCacheConfig(
        min_tokens=4096,
        ttl_seconds=600,  # 10 minutes for research sessions
        cache_intervals=3,  # Maximum invocations before cache refresh
    ),
)

2. Run Cache Experiments

The run_cache_experiments.py script automates the execution of prompts and compares caching performance between models:

# 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.5-flash --output gemini_2_5_results.json

# Run multiple iterations for averaged results
python run_cache_experiments.py gemini-2.5-flash --repeat 3 --output averaged_results.json

3. Direct Agent Usage

You can also run or debug the agent directly using the ADK CLI:

# Run the agent directly
adk run contributing/samples/cache_analysis/agent.py

# Web interface for debugging
adk web contributing/samples/cache_analysis

4. Experiment Types

The script automatically adapts the experiment based on the specified 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: The added benefit and performance differences of explicit caching over built-in implicit caching.

Other Models (e.g., gemini-2.0-flash)

• Explicit Caching: ADK explicit caching enabled.
• Uncached: Caching completely disabled.
• Measures: Baseline performance and cost benefits of context caching.

5. Expected Results

• Performance Improvements: Simple text agents typically see a 30-70% latency reduction with caching. Tool-heavy agents may experience slight cache setup overhead but still provide significant cost benefits.
• Cost Savings: Up to 75% reduction in input token costs for cached content (paying only 25% of normal input cost).
• Token Metrics: Successful cache hits are indicated by non-zero cached_content_token_count values.

6. Troubleshooting

Zero Cached Tokens

If cached_content_token_count is always 0:

• Verify model names match exactly (e.g., gemini-2.5-flash).
• Check that the min_tokens threshold (4,096 tokens) is met by the prompt and system instructions.
• Ensure proper App-based configuration is used rather than passing standalone agents without App wrappers.

Session Errors

If you encounter "Session not found" errors:

• Verify runner.app_name is used for session creation.
• Ensure correct initialization of InMemoryRunner with the App object.