adk-python/contributing/samples/runner_debug_example/README.md

Runner Debug Helper Example

This example demonstrates the run_debug() helper method that simplifies agent interaction for debugging and experimentation in ADK.

Overview

The run_debug() method reduces agent interaction boilerplate from 7-8 lines to just 2 lines, making it ideal for:

• Quick debugging sessions
• Jupyter notebooks
• REPL experimentation
• Writing examples
• Initial agent development

Files Included

• agent.py - Agent with 2 tools: weather and calculate
• main.py - 8 examples demonstrating all features
• README.md - This documentation

Setup

Prerequisites

Set your Google API key:

export GOOGLE_API_KEY="your-api-key"

Running the Example

python -m contributing.samples.runner_debug_example.main

Features Demonstrated

1. Minimal Usage: Simple 2-line agent interaction
2. Multiple Messages: Processing multiple messages in sequence
3. Session Persistence: Maintaining conversation context
4. Separate Sessions: Managing multiple user sessions
5. Tool Calls: Displaying tool invocations and results
6. Event Capture: Collecting events for programmatic inspection
7. Advanced Configuration: Using RunConfig for custom settings
8. Comparison: Before/after boilerplate reduction

Part Types Supported

The run_debug() method properly displays all ADK part types:

Part Type	Display Format	Use Case
text	agent > {text}	Regular text responses
function_call	agent > [Calling tool: {name}({args})]	Tool invocations
function_response	agent > [Tool result: {response}]	Tool results
executable_code	agent > [Executing {language} code...]	Code blocks
code_execution_result	agent > [Code output: {output}]	Code execution results
inline_data	agent > [Inline data: {mime_type}]	Images, files, etc.
file_data	agent > [File: {uri}]	File references

Tools Available in Example

The example agent includes 2 tools to demonstrate tool handling:

1. get_weather(city) - Returns mock weather data for major cities
2. calculate(expression) - Evaluates mathematical expressions safely

Key Benefits

Before (7-8 lines)

from google.adk.sessions import InMemorySessionService
from google.genai import types

APP_NAME = "default"
USER_ID = "default"
session_service = InMemorySessionService()
runner = Runner(agent=agent, app_name=APP_NAME, session_service=session_service)
session = await session_service.create_session(
    app_name=APP_NAME, user_id=USER_ID, session_id="default"
)
content = types.Content(role="user", parts=[types.Part.from_text("Hi")])
async for event in runner.run_async(
    user_id=USER_ID, session_id=session.id, new_message=content
):
    if event.content and event.content.parts:
        print(event.content.parts[0].text)

After (2 lines)

runner = InMemoryRunner(agent=agent)
await runner.run_debug("Hi")

API Reference

async def run_debug(
    self,
    user_messages: str | list[str],
    *,
    user_id: str = 'debug_user_id',
    session_id: str = 'debug_session_id',
    run_config: Optional[RunConfig] = None,
    quiet: bool = False,
    verbose: bool = False,
) -> List[Event]:

Parameters

• user_messages: Single message string or list of messages (required)
• user_id: User identifier for session tracking (default: 'debug_user_id')
• session_id: Session identifier for conversation continuity (default: 'debug_session_id')
• run_config: Optional advanced configuration
• quiet: Whether to suppress output to console (default: False)
• verbose: Whether to show detailed tool calls and responses (default: False)

Usage Examples

# Minimal usage
runner = InMemoryRunner(agent=agent)
await runner.run_debug("What's the weather?")

# Multiple queries
await runner.run_debug(["Query 1", "Query 2", "Query 3"])

# Custom session
await runner.run_debug(
    "Hello",
    user_id="alice",
    session_id="debug_session"
)

# Capture events without printing
events = await runner.run_debug(
    "Process this",
    quiet=True
)

# Show tool calls with verbose mode
await runner.run_debug(
    "What's the weather?",
    verbose=True  # Shows [Calling tool: ...] and [Tool result: ...]
)

# With custom configuration
from google.adk.agents.run_config import RunConfig
config = RunConfig(support_cfc=False)
await runner.run_debug("Query", run_config=config)

Troubleshooting

Common Issues and Solutions

1. Tool calls not showing in output

   • Issue: Tool invocations and responses are not displayed

   • Solution: Set verbose=True to see detailed tool interactions:

     await runner.run_debug("Query", verbose=True)
     

2. Import errors when running tests

   • Issue: ModuleNotFoundError: No module named 'google.adk'

   • Solution: Ensure you're using the virtual environment:

     source .venv/bin/activate
     python -m pytest tests/
     

3. Session state not persisting between calls

   • Issue: Agent doesn't remember previous interactions

   • Solution: Use the same user_id and session_id across calls:

     await runner.run_debug("First query", user_id="alice", session_id="debug")
     await runner.run_debug("Follow-up", user_id="alice", session_id="debug")
     

4. Output truncation issues

   • Issue: Long tool responses are truncated with "..."

   • Solution: This is by design to keep debug output readable. For full responses, use:

     events = await runner.run_debug("Query", quiet=True)
     # Process events programmatically for full content
     

5. API key errors

   • Issue: Authentication failures or missing API key

   • Solution: Ensure your Google API key is set:

     export GOOGLE_API_KEY="your-api-key"
     

Important Notes

run_debug() is designed for debugging and experimentation only. For production use requiring:

• Custom session/memory services (Spanner, Cloud SQL)
• Fine-grained event processing
• Error recovery and resumability
• Performance optimization

Use the standard run_async() method instead.