feat: Add user_id property to ReadonlyContext

[ammmr]

related: #2876

Reason for this change:

Currently, there is no direct way to access the user_id from within agent contexts, plugins, or callbacks. This limitation prevents several important use cases:

1. User-specific logging and tracing: When debugging or monitoring agent behavior, it's crucial to associate actions with specific users for better observability.
2. User-scoped operations: Plugins and callbacks often need to perform user-specific operations, such as accessing user-specific resources or applying user-level configurations.
3. Session management: The user_id is a key component of session identification, but it's not accessible through the ReadonlyContext interface, requiring workarounds to access it.

Changes made:

• Added a user_id property to the ReadonlyContext class in src/google/adk/agents/readonly_context.py
• The property exposes the user_id from the underlying invocation context as a readonly field

Impact:

This change will:

• Enable plugins and callbacks to access the current user's ID directly through the context
• Improve logging and tracing capabilities by allowing user-specific tracking
• Simplify code that needs to perform user-scoped operations without requiring access to internal implementation details
• Maintain backward compatibility as this is an additive change

Before:

• No direct way to access user_id from ReadonlyContext

After:

@property
def user_id(self) -> str:
    """The id of the user. READONLY field."""
    return self._invocation_context.user_id

This is a non-breaking change that adds a new readonly property to the existing ReadonlyContext interface.

[gemini-code-assist]

Summary of Changes

Hello @ammmr, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the ReadonlyContext by adding a user_id property. This provides a direct and standardized way for agents, plugins, and callbacks to access the current user's identifier, which is crucial for implementing user-specific functionalities, improving logging, and streamlining session management. The change is additive and maintains backward compatibility.

Highlights

• Direct User ID Access: Introduces a user_id property to the ReadonlyContext class, enabling direct access to the user's ID from within agent contexts, plugins, and callbacks. This addresses current limitations where user_id was not easily accessible.
• Enhanced Observability and User-Scoped Operations: This change facilitates user-specific logging, tracing, and operations, improving debugging and monitoring capabilities. It also simplifies the implementation of features requiring user-level configurations or resources.
• Non-Breaking and Backward Compatible: The addition of the user_id property is an additive change, ensuring backward compatibility and a smooth integration without impacting existing functionalities.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @ammmr, thank you for creating this PR!

To help us review this PR, could you please create and associate a GitHub issue with this PR?

Also, could you please add a testing plan section to your PR description to talk about how you will test this change?

This information will help reviewers to review your PR more efficiently. Thanks!

[gemini-code-assist]

Code Review

This pull request introduces a user_id property to the ReadonlyContext, which is a valuable addition for user-specific logging and operations. The change is well-motivated and includes a corresponding unit test. My review includes a suggestion to enhance the robustness of this new property by handling cases where a user_id might not be present, which is a common scenario in user-based systems. By typing the return value as Optional[str] and expanding the test coverage, we can ensure the new API is more resilient and prevent potential runtime errors.

[gemini-code-assist]

The user_id property is typed to return a str. While the underlying InvocationContext also types it as str, it's common for user identifiers to be optional (e.g., for anonymous sessions). If _invocation_context.user_id were to return None, this property would violate its type hint, potentially leading to runtime errors in client code.

To make the API more robust, I suggest changing the return type to Optional[str]. This makes it explicit that user_id can be missing and requires consumers to handle this case.

Suggested change

	def user_id(self) -> str:
	def user_id(self) -> Optional[str]:

[ammmr]

Thank you for the feedback. I understand your concern about the robustness of the API. However, I believe the current implementation with str return type is correct based on the codebase design.

Looking at the Session base class and its implementations (specifically InMemorySessionService), the user_id is a required field that cannot be None:

1. The Session base class defines user_id as a non-optional str field
2. In InMemorySessionService, sessions are created with a required user_id parameter (line 106 in src/google/adk/sessions/in_memory_session_service.py)
3. The InvocationContext that wraps the session also treats user_id as a required str

This architectural decision means that anonymous sessions are not supported in the current design - every session must have an associated user_id. Making it Optional[str] would imply that anonymous sessions are possible, which would be misleading given the current implementation constraints.

If anonymous sessions become a requirement in the future, it would need to be a broader architectural change affecting the Session base class and all its implementations, not just this readonly accessor.

Therefore, keeping the return type as str accurately reflects the current API contract and ensures type consistency throughout the codebase.