feat: ADK Web Async Agent Compatibility

[fbiebl]

ADK Web Async Agent Compatibility - Pull Request Documentation

Overview

This pull request adds comprehensive support for async agents in ADK Web, solving two critical compatibility issues that prevented full functionality in the ADK Web interface.

Problems Solved

1. MCP Tools Event Loop Conflicts

• Issue: "Event loop is closed" errors when MCP tools were called in ADK Web
• Root Cause: uvloop compatibility issues between ADK Web's event loop and MCP client libraries
• Impact: MCP tools would timeout or crash, breaking agent functionality

2. Session State Customization Limitations

• Issue: No mechanism to load custom data before template processing
• Root Cause: ADK Web had no callback system for session state preprocessing
• Impact: Template variables like {user_name} couldn't be populated from databases

Solution Implementation

1. Session State Preprocessor Callback Mechanism

How it works:

1. ADK Web now looks for a session_state_preprocessor function in agent modules
2. This function is called before template processing with the current session state
3. Agents can load database data, set defaults, or add custom variables
4. Enhanced state becomes available for ADK template variables {variable}

Example:

# In your agent module
async def session_state_preprocessor(state):
    """Called before template processing"""
    user_id = state.get("user_id")
    if user_id:
        user_data = await load_from_database(user_id)
        state["user_name"] = user_data["name"]
        state["user_role"] = user_data["role"]
    return state

2. MCP uvloop Compatibility Fix

Files Modified:

• src/google/adk/tools/mcp_tool/mcp_tool.py

How it works:

1. Automatic detection of uvloop event loops
2. When uvloop is detected, MCP operations run in isolated standard asyncio threads
3. Prevents "Event loop is closed" errors
4. Maintains full MCP functionality in ADK Web

Technical Details:

• Uses thread pool executor for event loop isolation
• Creates fresh asyncio event loops for MCP operations
• Handles timeout and error propagation correctly
• Zero performance impact for non-uvloop environments

Usage Examples

Minimal Implementation

# agent.py
from google.adk.agents.llm_agent import LlmAgent
from google.adk.models.lite_llm import LiteLlm

async def session_state_preprocessor(state):
    """Optional: enhance session state before template processing"""
    user_id = state.get("user_id", "1")  # ADK Web provides "1" as default
    state["user_name"] = f"User {user_id}"
    state["app_name"] = "My ADK App"
    return state

def create_adk_web_agent():
    """Required: ADK Web entry point"""
    return LlmAgent(
        name="my_agent",
        model=LiteLlm(model="openai/gpt-4o"),
        instruction="Hello {user_name}! Welcome to {app_name}.",
        tools=[...]  # MCP tools work automatically
    )

Template Usage

# Templates now support custom variables
instruction = """
Hello {user_name}!

User Info:
- ID: {user_id}
- Role: {user_role}
- App: {app_name}

Your MCP tools are ready to use.
"""

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.