How to inject ToolContext (user session) when testing locally with adk web?

[this-dave]

I'm developing a multi-agent system where specialist agents need access to the current user's context (specifically their email) for authorization checks. The tools use ToolContext to access context.session.user_id.
When deployed to production (Vertex AI), the ToolContext works perfectly. However, during local development with adk web, the ToolContext appears to be empty or not properly initialized, making it impossible to test authorization flows locally.

Current Setup:

pythonfrom typing import TypedDict
from google.adk.tools import ToolContext

class ProjectOutput(TypedDict):
    status: str
    message: str

async def update_project(
    project_key: str, 
    context: ToolContext
) -> ProjectOutput:
    """Update project settings (requires authorization)"""
    
    # Need user email for permission check
    user_email = context.session.user_id  # This is None in adk web
    
    # Check if user has permission
    if not await check_user_permission(project_key, user_email):
        return {"status": "error", "message": "Permission denied"}
    
    # ... actual update logic

Problem:
When running adk web src/agents/, the ToolContext doesn't contain any session information, causing the authorization logic to fail.
Question:

Is there a way to inject or mock session data into ToolContext for local testing with adk web?
What's the recommended pattern for handling user context in tools that works both in production and local development?
Should we avoid ToolContext for user authentication and use a different approach?

Environment:

Google ADK version: latest
Python 3.13
Testing with: adk web

Any guidance on best practices for local development with user context would be appreciated!

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: For local testing with adk web, the ToolContext is not populated with user session data as it is in a production environment. The recommended approach is to implement a fallback for local development within your tool and use mocked ToolContext objects in your unit tests for robust authorization testing.

---

Hello! That's a great question, and it touches on a common challenge when developing locally versus in a deployed environment.

Here’s a breakdown of the recommended patterns for handling user context with ADK:

1. Handling ToolContext in Local Development (adk web)

You are correct that when using adk web, the ToolContext does not automatically get populated with user_id because the local development server uses an in-memory session manager that doesn't have the full authentication context of a production environment like Vertex AI. [1]

While there isn't a direct way to inject session data via the adk web command line, the recommended pattern is to add a fallback in your tool code for local development. This allows you to test your tool's logic without the authorization part getting in the way.

Here’s how you can modify your update_project tool:

import os
from typing import TypedDict
from google.adk.tools import ToolContext

# A simple way to check if running in the local `adk web` environment
IS_LOCAL = os.environ.get("ADK_LOCAL_DEV", "false").lower() == "true"

class ProjectOutput(TypedDict):
    status: str
    message: str

async def update_project(
    project_key: str, 
    context: ToolContext
) -> ProjectOutput:
    """Update project settings (requires authorization)"""
    
    user_email = context.session.user_id
    
    # Use a mock user for local development if no user_id is present
    if IS_LOCAL and not user_email:
        user_email = "local-dev-user@example.com"
        print(f"Running in local mode, using mock user: {user_email}")

    if not user_email:
        return {"status": "error", "message": "Permission denied: User not authenticated."}

    # Check if user has permission
    if not await check_user_permission(project_key, user_email):
        return {"status": "error", "message": "Permission denied"}
    
    return {"status": "success", "message": "Project updated"}

To make this work, you can set the environment variable when you run the local server:
ADK_LOCAL_DEV=true adk web src/agents/

2. Recommended Pattern for Authorization Testing

For robustly testing your authorization logic, the best practice is to write unit tests using a framework like pytest. In your tests, you can create a mock or a temporary ToolContext and set the user_id to simulate different scenarios (e.g., authorized user, unauthorized user).

This approach is used extensively in the ADK's own test suite. [2, 3] Here is an example of how you could write a test for your tool:

import pytest
from unittest.mock import MagicMock, AsyncMock
from google.adk.services.test_utils import InMemorySessionService
from google.adk.tools import ToolContext, InvocationContext

# Assuming your tool is in a file named `my_tool.py`
from my_tool import update_project

@pytest.fixture
async def tool_context_factory():
    session_service = InMemorySessionService()
    
    async def _factory(user_id: str | None):
        session = await session_service.create_session(app_name="test_app", user_id=user_id)
        invocation_context = InvocationContext(session, session_service)
        return ToolContext(invocation_context)
    
    return _factory

@pytest.mark.asyncio
async def test_update_project_permission_denied(tool_context_factory, monkeypatch):
    """Test that an unauthorized user is denied."""
    # Create a context with a specific user ID
    unauth_user_context = await tool_context_factory("unauthorized-user@example.com")
    
    # Mock the permission check to return False
    monkeypatch.setattr("my_tool.check_user_permission", AsyncMock(return_value=False))
    
    result = await update_project(project_key="test-project", context=unauth_user_context)
    
    assert result["status"] == "error"
    assert result["message"] == "Permission denied"

@pytest.mark.asyncio
async def test_update_project_permission_granted(tool_context_factory, monkeypatch):
    """Test that an authorized user is granted access."""
    # Create a context with a different user ID
    auth_user_context = await tool_context_factory("authorized-user@example.com")
    
    # Mock the permission check to return True
    monkeypatch.setattr("my_tool.check_user_permission", AsyncMock(return_value=True))
    
    result = await update_project(project_key="test-project", context=auth_user_context)
    
    assert result["status"] == "success"

3. Should You Avoid ToolContext?

No, you should definitely not avoid ToolContext. It is a core feature of the ADK designed to handle session state, authentication, and other contextual information. [4, 5] The key is to adopt a development and testing workflow that accounts for the differences between the local and production environments, as described above.

By combining a local development fallback with robust unit tests, you can ensure your tools are both easy to test interactively and secure in production.

[1] https://google.github.io/adk-docs/sessions/
[2] https://github.com/google/adk-python/blob/main/tests/unittests/tools/test_url_context_tool.py
[3] https://github.com/google/adk-python/blob/main/tests/unittests/tools/test_base_google_credentials_manager.py
[4] https://google.github.io/adk-docs/context/
[5] https://google.github.io/adk-docs/tools/

[seanzhou1023]

@this-dave thank you for your questions :) You don't have a way to change user_id on ADK Web, as it's hard coded, because adk web is mainly targeted for development / testing tool https://github.com/google/adk-web/blob/3ddf6fabf4da669092e1329d92f6f4a855804d5a/src/app/components/chat/chat.component.ts#L174

but you are able to change user context , i.e. session state by calling the API server to inject some session state yourself:

1. you can get the session ID from the Web UI
2. call this run API to change session state :

   adk-python/src/google/adk/cli/adk_web_server.py

   Line 1190 in 2595824

   @app.post("/run", response_model_exclude_none=True)

   
   with empty message but state_delta

as suggested by bot answer above, you should have some fallback logic to check permission via session state. BTW on local how do you check permission ? you still connect to a remote DB / server to check permission ?

[wyf7107]

Hi, as Sean point out, user_id is not something users can override at the moment. However, if you wish to change the state, you can also click the three dots next to the attachment buton in the chat input field.

There you can specify what state you want to alter and sending the message along with this will update the state