integration-google-adk (Google ADK Integration)

This example demonstrates how to test Google Agent Development Kit (ADK) agents using promptfoo. It shows both single-turn and multi-turn conversation patterns with automatic session management.

You can run this example with:

npx promptfoo@latest init --example integration-google-adk
cd integration-google-adk

What this example shows

• Real Gemini Integration: Uses Gemini 2.5 Flash for actual AI responses
• Function Tool Usage: Weather agent with get_weather tool
• Single-turn Testing: Independent queries with isolated sessions
• Multi-turn Testing: Conversational memory across multiple queries
• Automatic Session Management: Setup and cleanup handled by promptfoo hooks

Prerequisites

1. Python 3.8+ installed on your system
2. Google API Key for Gemini model access (both agent and LLM grading)
3. ADK Python package installed

Setup Instructions

1. Install the Google Agent Development Kit

pip install google-adk

2. Set up API Authentication

Get a Google API key from the Google AI Studio and set it as an environment variable:

export GOOGLE_API_KEY="your-google-api-key-here"

3. Install Python Dependencies

pip install -r requirements.txt

Note: The session management is now handled entirely in JavaScript using Node.js native fetch, eliminating the need for additional Python HTTP libraries.

Running the Examples

1. Start the ADK API Server

From this directory, run:

export GOOGLE_API_KEY="your-api-key-here"
adk api_server

You should see output like:

INFO:     Started server process [12345]
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:8000

Keep this server running in one terminal.

2. Run Tests

In a new terminal, choose either:

Single-turn testing (isolated sessions):

promptfoo eval -c promptfooconfig-single-turn.yaml

Multi-turn testing (shared conversation):

promptfoo eval -c promptfooconfig-multi-turn.yaml --max-concurrency 1

Both configurations will:

• Automatically create and manage ADK sessions
• Test the weather agent with real Gemini calls
• Clean up sessions after completion

Example Output

Single-turn - Each test uses a separate session:

✅ Weather query for New York
✅ Weather query for London (independent session)
✅ Context isolation test: "I don't have memory of previous conversations"

Pass Rate: 100% (demonstrates session isolation)

Multi-turn - All tests share one session:

✅ Initial weather query
✅ Follow-up weather query
✅ Memory test: "Comparing New York (sunny, 72°F) vs London (cloudy, 58°F)"

Pass Rate: 100% (demonstrates conversation memory)

Understanding the Configuration

This example follows the official ADK pattern:

Agent Structure (weather_agent/agent.py)

from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    # Mock weather function - replace with real API in production
    return {"status": "success", "report": "..."}

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",  # Real Gemini 2.5 Flash model
    description="Agent to answer questions about weather in various cities",
    instruction="You are a helpful weather assistant...",
    tools=[get_weather]
)

Key Integration Files

1. adk-session-hook.js: Session management using Node.js native fetch
2. adk-response-transform.js: Extracts text responses from ADK's event-based format
3. weather_agent/: The actual ADK agent code (Python)

Understanding ADK Sessions

ADK sessions are stateful conversation contexts that maintain memory between interactions. This is crucial for building conversational agents.

Session Structure

Sessions follow this hierarchy:

/apps/{app_name}/users/{user_id}/sessions/{session_id}

• app_name: Your agent (e.g., weather_agent)
• user_id: User identifier (e.g., test_user)
• session_id: Conversation thread (e.g., session_shared)

Session Strategies

Multi-turn (Shared Session):

# promptfooconfig-multi-turn.yaml
body:
  session_id: 'conversation' # Same for all tests

Benefits: Agent remembers context across tests Use case: Testing conversational flow and memory

Single-turn (Separate Sessions):

# promptfooconfig-single-turn.yaml
vars:
  session_id: 'session_ny' # Different per test
body:
  session_id: '{{session_id}}'

Benefits: Complete isolation, no test interference Use case: Independent validation scenarios

Session Management

Our example uses automatic session management:

1. Creation: beforeAll hook creates session before tests
2. Usage: All tests reference the same session
3. Cleanup: afterAll hook removes session after tests

To change session strategy, modify the session hook or use test-specific session IDs.

Troubleshooting

Common Issues

1. Authentication errors:

   bashCopy

   export GOOGLE_API_KEY="your-key-from-ai-google-dev"
   

2. 500 Internal Server Error:

   • Verify your Google API key is valid
   • Check that the ADK server is running
   • Ensure all Python dependencies are installed

3. "Agent not found" error: Make sure the ADK server can find the weather_agent directory

Learn More

• Google ADK Documentation
• Official ADK Samples
• Google AI Studio (get API keys)
• promptfoo HTTP Provider