refactor: Extract util method from OAuth2 credential fetcher for reuse

PiperOrigin-RevId: 771635844

Author: seanzhougoogle

contributing/samples/oauth_calendar_agent/agent.py

@@ -27,8 +27,6 @@
 from google.adk.auth import AuthCredentialTypes
 from google.adk.auth import OAuth2Auth
 from google.adk.tools import ToolContext
-from google.adk.tools.authenticated_tool.base_authenticated_tool import AuthenticatedFunctionTool
-from google.adk.tools.authenticated_tool.credentials_store import ToolContextCredentialsStore
 from google.adk.tools.google_api_tool import CalendarToolset
 from google.auth.transport.requests import Request
 from google.oauth2.credentials import Credentials
@@ -58,7 +56,6 @@ def list_calendar_events(
     end_time: str,
     limit: int,
     tool_context: ToolContext,
-    credential: AuthCredential,
 ) -> list[dict]:
   """Search for calendar events.
 
@@ -83,11 +80,84 @@ def list_calendar_events(
   Returns:
       list[dict]: A list of events that match the search criteria.
   """
-
-  creds = Credentials(
-      token=credential.oauth2.access_token,
-      refresh_token=credential.oauth2.refresh_token,
-  )
+  creds = None
+
+  # Check if the tokes were already in the session state, which means the user
+  # has already gone through the OAuth flow and successfully authenticated and
+  # authorized the tool to access their calendar.
+  if "calendar_tool_tokens" in tool_context.state:
+    creds = Credentials.from_authorized_user_info(
+        tool_context.state["calendar_tool_tokens"], SCOPES
+    )
+  if not creds or not creds.valid:
+    # If the access token is expired, refresh it with the refresh token.
+    if creds and creds.expired and creds.refresh_token:
+      creds.refresh(Request())
+    else:
+      auth_scheme = OAuth2(
+          flows=OAuthFlows(
+              authorizationCode=OAuthFlowAuthorizationCode(
+                  authorizationUrl="https://accounts.google.com/o/oauth2/auth",
+                  tokenUrl="https://oauth2.googleapis.com/token",
+                  scopes={
+                      "https://www.googleapis.com/auth/calendar": (
+                          "See, edit, share, and permanently delete all the"
+                          " calendars you can access using Google Calendar"
+                      )
+                  },
+              )
+          )
+      )
+      auth_credential = AuthCredential(
+          auth_type=AuthCredentialTypes.OAUTH2,
+          oauth2=OAuth2Auth(
+              client_id=oauth_client_id, client_secret=oauth_client_secret
+          ),
+      )
+      # If the user has not gone through the OAuth flow before, or the refresh
+      # token also expired, we need to ask users to go through the OAuth flow.
+      # First we check whether the user has just gone through the OAuth flow and
+      # Oauth response is just passed back.
+      auth_response = tool_context.get_auth_response(
+          AuthConfig(
+              auth_scheme=auth_scheme, raw_auth_credential=auth_credential
+          )
+      )
+      if auth_response:
+        # ADK exchanged the access token already for us
+        access_token = auth_response.oauth2.access_token
+        refresh_token = auth_response.oauth2.refresh_token
+
+        creds = Credentials(
+            token=access_token,
+            refresh_token=refresh_token,
+            token_uri=auth_scheme.flows.authorizationCode.tokenUrl,
+            client_id=oauth_client_id,
+            client_secret=oauth_client_secret,
+            scopes=list(auth_scheme.flows.authorizationCode.scopes.keys()),
+        )
+      else:
+        # If there are no auth response which means the user has not gone
+        # through the OAuth flow yet, we need to ask users to go through the
+        # OAuth flow.
+        tool_context.request_credential(
+            AuthConfig(
+                auth_scheme=auth_scheme,
+                raw_auth_credential=auth_credential,
+            )
+        )
+        # The return value is optional and could be any dict object. It will be
+        # wrapped in a dict with key as 'result' and value as the return value
+        # if the object returned is not a dict. This response will be passed
+        # to LLM to generate a user friendly message. e.g. LLM will tell user:
+        # "I need your authorization to access your calendar. Please authorize
+        # me so I can check your meetings for today."
+        return "Need User Authorization to access their calendar."
+    # We store the access token and refresh token in the session state for the
+    # next runs. This is just an example. On production, a tool should store
+    # those credentials in some secure store or properly encrypt it before store
+    # it in the session state.
+    tool_context.state["calendar_tool_tokens"] = json.loads(creds.to_json())
 
   service = build("calendar", "v3", credentials=creds)
   events_result = (
@@ -138,38 +208,6 @@ def update_time(callback_context: CallbackContext):
 
       Currnet time: {_time}
 """,
-    tools=[
-        AuthenticatedFunctionTool(
-            func=list_calendar_events,
-            auth_config=AuthConfig(
-                auth_scheme=OAuth2(
-                    flows=OAuthFlows(
-                        authorizationCode=OAuthFlowAuthorizationCode(
-                            authorizationUrl=(
-                                "https://accounts.google.com/o/oauth2/auth"
-                            ),
-                            tokenUrl="https://oauth2.googleapis.com/token",
-                            scopes={
-                                "https://www.googleapis.com/auth/calendar": (
-                                    "See, edit, share, and permanently delete"
-                                    " all the calendars you can access using"
-                                    " Google Calendar"
-                                )
-                            },
-                        )
-                    )
-                ),
-                raw_auth_credential=AuthCredential(
-                    auth_type=AuthCredentialTypes.OAUTH2,
-                    oauth2=OAuth2Auth(
-                        client_id=oauth_client_id,
-                        client_secret=oauth_client_secret,
-                    ),
-                ),
-            ),
-            credential_store=ToolContextCredentialsStore(),
-        ),
-        calendar_toolset,
-    ],
+    tools=[list_calendar_events, calendar_toolset],
     before_agent_callback=update_time,
 )

src/google/adk/agents/invocation_context.py

@@ -22,6 +22,7 @@
 from pydantic import ConfigDict
 
 from ..artifacts.base_artifact_service import BaseArtifactService
+from ..auth.credential_service.base_credential_service import BaseCredentialService
 from ..memory.base_memory_service import BaseMemoryService
 from ..sessions.base_session_service import BaseSessionService
 from ..sessions.session import Session
@@ -115,6 +116,7 @@ class InvocationContext(BaseModel):
   artifact_service: Optional[BaseArtifactService] = None
   session_service: BaseSessionService
   memory_service: Optional[BaseMemoryService] = None
+  credential_service: Optional[BaseCredentialService] = None
 
   invocation_id: str
   """The id of this invocation context. Readonly."""

src/google/adk/auth/credential_service/base_credential_service.py

@@ -19,12 +19,12 @@
 from typing import Optional
 
 from ...tools.tool_context import ToolContext
-from ...utils.feature_decorator import working_in_progress
+from ...utils.feature_decorator import experimental
 from ..auth_credential import AuthCredential
 from ..auth_tool import AuthConfig
 
 
-@working_in_progress("Implementation are in progress. Don't use it for now.")
+@experimental
 class BaseCredentialService(ABC):
   """Abstract class for Service that loads / saves tool credentials from / to
   the backend credential store."""

src/google/adk/auth/credential_service/in_memory_credential_service.py

@@ -0,0 +1,93 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from typing import Optional
+
+from typing_extensions import override
+
+from ...tools.tool_context import ToolContext
+from ...utils.feature_decorator import experimental
+from ..auth_credential import AuthCredential
+from ..auth_tool import AuthConfig
+from .base_credential_service import BaseCredentialService
+
+
+@experimental
+class InMemoryCredentialService(BaseCredentialService):
+  """Class for in memory implementation of credential service(Experimental)"""
+
+  def __init__(self):
+    super().__init__()
+    self._store: dict[str, AuthCredential] = {}
+
+  @override
+  async def load_credential(
+      self,
+      auth_config: AuthConfig,
+      tool_context: ToolContext,
+  ) -> Optional[AuthCredential]:
+    """
+    Loads the credential by auth config and current tool context from the
+    backend credential store.
+
+    Args:
+        auth_config: The auth config which contains the auth scheme and auth
+        credential information. auth_config.get_credential_key will be used to
+        build the key to load the credential.
+
+        tool_context: The context of the current invocation when the tool is
+        trying to load the credential.
+
+    Returns:
+        Optional[AuthCredential]: the credential saved in the store.
+
+    """
+    storage = self._get_storage_for_current_context(tool_context)
+    return storage.get(auth_config.credential_key)
+
+  @override
+  async def save_credential(
+      self,
+      auth_config: AuthConfig,
+      tool_context: ToolContext,
+  ) -> None:
+    """
+    Saves the exchanged_auth_credential in auth config to the backend credential
+    store.
+
+    Args:
+        auth_config: The auth config which contains the auth scheme and auth
+        credential information. auth_config.get_credential_key will be used to
+        build the key to save the credential.
+
+        tool_context: The context of the current invocation when the tool is
+        trying to save the credential.
+
+    Returns:
+        None
+    """
+    storage = self._get_storage_for_current_context(tool_context)
+    storage[auth_config.credential_key] = auth_config.exchanged_auth_credential
+
+  def _get_storage_for_current_context(self, tool_context: ToolContext) -> str:
+    app_name = tool_context._invocation_context.app_name
+    user_id = tool_context._invocation_context.user_id
+
+    if app_name not in self._store:
+      self._store[app_name] = {}
+    if user_id not in self._store[app_name]:
+      self._store[app_name][user_id] = {}
+    return self._store[app_name][user_id]

src/google/adk/auth/exchanger/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Credential exchanger module."""
+
+from .base_credential_exchanger import BaseCredentialExchanger
+from .service_account_credential_exchanger import ServiceAccountCredentialExchanger
+
+__all__ = [
+    "BaseCredentialExchanger",
+    "ServiceAccountCredentialExchanger",
+]

src/google/adk/auth/exchanger/base_credential_exchanger.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Base credential exchanger interface."""
+
+from __future__ import annotations
+
+import abc
+from typing import Optional
+
+from ...utils.feature_decorator import experimental
+from ..auth_credential import AuthCredential
+from ..auth_schemes import AuthScheme
+
+
+@experimental
+class BaseCredentialExchanger(abc.ABC):
+  """Base interface for credential exchangers."""
+
+  @abc.abstractmethod
+  def exchange(
+      self,
+      auth_credential: AuthCredential,
+      auth_scheme: Optional[AuthScheme] = None,
+  ) -> AuthCredential:
+    """Exchange credential if needed.
+
+    Args:
+        auth_credential: The credential to exchange.
+        auth_scheme: The authentication scheme (optional, some exchangers don't need it).
+
+    Returns:
+        The exchanged credential.
+
+    Raises:
+        ValueError: If credential exchange fails.
+    """
+    pass