Merge branch 'main' into feat-Add-early-exit-mechanism-to-SequentialAgent-using-escalate-action

Author: tommyhutcheson

contributing/samples/oauth_calendar_agent/README.md

@@ -4,37 +4,45 @@
 
 This sample tests and demos the OAuth support in ADK via two tools:
 
-* 1. list_calendar_events
+*   1. list_calendar_events
 
-  This is a customized tool that calls Google Calendar API to list calendar events.
-  It pass in the client id and client secrete to ADK and then get back the access token from ADK.
-  And then it uses the access token to call calendar api.
+    This is a customized tool that calls Google Calendar API to list calendar
+    events. It pass in the client id and client secrete to ADK and then get back
+    the access token from ADK. And then it uses the access token to call
+    calendar api.
 
-* 2. get_calendar_events
+*   2. get_calendar_events
 
-  This is an google calendar tool that calls Google Calendar API to get the details of a specific calendar.
-  This tool is from the ADK built-in Google Calendar ToolSet.
-  Everything is wrapped and the tool user just needs to pass in the client id and client secret.
+    This is an google calendar tool that calls Google Calendar API to get the
+    details of a specific calendar. This tool is from the ADK built-in Google
+    Calendar ToolSet. Everything is wrapped and the tool user just needs to pass
+    in the client id and client secret.
 
 ## How to use
 
-* 1. Follow https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name. to get your client id and client secret.
-  Be sure to choose "web" as your client type.
+*   1. Follow
+    https://developers.google.com/identity/protocols/oauth2#1.-obtain-oauth-2.0-credentials-from-the-dynamic_data.setvar.console_name.
+    to get your client id and client secret. Be sure to choose "web" as your
+    client type.
 
-* 2. Configure your `.env` file to add two variables:
+*   2. Configure your `.env` file to add two variables:
 
-  * OAUTH_CLIENT_ID={your client id}
-  * OAUTH_CLIENT_SECRET={your client secret}
+    *   OAUTH_CLIENT_ID={your client id}
+    *   OAUTH_CLIENT_SECRET={your client secret}
 
-  Note: don't create a separate `.env` file , instead put it to the same `.env` file that stores your Vertex AI or Dev ML credentials
+    Note: don't create a separate `.env` file , instead put it to the same
+        `.env` file that stores your Vertex AI or Dev ML credentials
 
-* 3. Follow https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred to add http://localhost/dev-ui/ to "Authorized redirect URIs".
+*   3. Follow
+    https://developers.google.com/identity/protocols/oauth2/web-server#creatingcred
+    to add http://localhost/dev-ui/ to "Authorized redirect URIs".
 
-  Note: localhost here is just a hostname that you use to access the dev ui, replace it with the actual hostname you use to access the dev ui.
+    Note: localhost here is just a hostname that you use to access the dev ui,
+    replace it with the actual hostname you use to access the dev ui.
 
-* 4. For 1st run, allow popup for localhost in Chrome.
+*   4. For 1st run, allow popup for localhost in Chrome.
 
 ## Sample prompt
 
-* `List all my today's meeting from 7am to 7pm.`
-* `Get the details of the first event.`
+*   `List all my today's meeting from 7am to 7pm.`
+*   `Get the details of the first event.`

contributing/samples/output_schema_with_tools/README.md

@@ -1,22 +1,32 @@
 # Output Schema with Tools Sample Agent
 
-This sample demonstrates how to use structured output (`output_schema`) alongside other tools in an ADK agent. Previously, this combination was not allowed, but now it's supported through a special processor that handles the interaction.
+This sample demonstrates how to use structured output (`output_schema`)
+alongside other tools in an ADK agent. Previously, this combination was not
+allowed, but now it's supported through a special processor that handles the
+interaction.
 
 ## How it Works
 
 The agent combines:
-- **Tools**: `search_wikipedia` and `get_current_year` for gathering information
-- **Structured Output**: `PersonInfo` schema to ensure consistent response format
+
+-   **Tools**: `search_wikipedia` and `get_current_year` for gathering
+    information
+-   **Structured Output**: `PersonInfo` schema to ensure consistent response
+    format
 
 When both `output_schema` and `tools` are specified:
-1. ADK automatically adds a special `set_model_response` tool
-2. The model can use the regular tools for information gathering
-3. For the final response, the model uses `set_model_response` with structured data
-4. ADK extracts and validates the structured response
+
+1.  ADK automatically adds a special `set_model_response` tool
+2.  The model can use the regular tools for information gathering
+3.  For the final response, the model uses `set_model_response` with structured
+    data
+4.  ADK extracts and validates the structured response
 
 ## Expected Response Format
 
-The agent will return information in this structured format for user query "Tell me about Albert Einstein":
+The agent will return information in this structured format for user query
+
+> Tell me about Albert Einstein.
 
 ```json
 {
@@ -30,7 +40,7 @@ The agent will return information in this structured format for user query "Tell
 
 ## Key Features Demonstrated
 
-1. **Tool Usage**: Agent can search Wikipedia and get current year
-2. **Structured Output**: Response follows strict PersonInfo schema
-3. **Validation**: ADK validates the response matches the schema
-4. **Flexibility**: Works with any combination of tools and output schemas
+1.  **Tool Usage**: Agent can search Wikipedia and get current year
+2.  **Structured Output**: Response follows strict PersonInfo schema
+3.  **Validation**: ADK validates the response matches the schema
+4.  **Flexibility**: Works with any combination of tools and output schemas

src/google/adk/sessions/vertex_ai_session_service.py

@@ -73,7 +73,23 @@ async def create_session(
       user_id: str,
       state: Optional[dict[str, Any]] = None,
       session_id: Optional[str] = None,
+      **kwargs: Any,
   ) -> Session:
+    """Creates a new session.
+
+    Args:
+      app_name: The name of the application.
+      user_id: The ID of the user.
+      state: The initial state of the session.
+      session_id: The ID of the session.
+      **kwargs: Additional arguments to pass to the session creation. E.g. set
+        expire_time='2025-10-01T00:00:00Z' to set the session expiration time.
+        See https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1beta1/projects.locations.reasoningEngines.sessions
+        for more details.
+    Returns:
+      The created session.
+    """
+
     if session_id:
       raise ValueError(
           'User-provided Session id is not supported for'
@@ -84,6 +100,7 @@ async def create_session(
     api_client = self._get_api_client()
 
     config = {'session_state': state} if state else {}
+    config.update(kwargs)
 
     if _is_vertex_express_mode(self._project, self._location):
       config['wait_for_completion'] = False

tests/unittests/sessions/test_vertex_ai_session_service.py

@@ -242,6 +242,7 @@ def __init__(self) -> None:
     self.agent_engines.sessions.create.side_effect = self._create_session
     self.agent_engines.sessions.events.list.side_effect = self._list_events
     self.agent_engines.sessions.events.append.side_effect = self._append_event
+    self.last_create_session_config: dict[str, Any] = {}
 
   def _get_session(self, name: str):
     session_id = name.split('/')[-1]
@@ -275,6 +276,7 @@ def _delete_session(self, name: str):
     self.session_dict.pop(session_id)
 
   def _create_session(self, name: str, user_id: str, config: dict[str, Any]):
+    self.last_create_session_config = config
     new_session_id = '4'
     self.session_dict[new_session_id] = {
         'name': (
@@ -360,7 +362,8 @@ def mock_vertex_ai_session_service(agent_engine_id: Optional[str] = None):
 
 
 @pytest.fixture
-def mock_get_api_client():
+def mock_api_client_instance():
+  """Creates a mock API client instance for testing."""
   api_client = MockApiClient()
   api_client.session_dict = {
       '1': MOCK_SESSION_JSON_1,
@@ -373,9 +376,15 @@ def mock_get_api_client():
       '1': (copy.deepcopy(MOCK_EVENT_JSON), None),
       '2': (copy.deepcopy(MOCK_EVENT_JSON_2), 'my_token'),
   }
+  return api_client
+
+
+@pytest.fixture
+def mock_get_api_client(mock_api_client_instance):
+  """Mocks the _get_api_client method to return a mock API client."""
   with mock.patch(
       'google.adk.sessions.vertex_ai_session_service.VertexAiSessionService._get_api_client',
-      return_value=api_client,
+      return_value=mock_api_client_instance,
   ):
     yield
 
@@ -521,6 +530,21 @@ async def test_create_session_with_custom_session_id():
   )
 
 
+@pytest.mark.asyncio
+@pytest.mark.usefixtures('mock_get_api_client')
+async def test_create_session_with_custom_config(mock_api_client_instance):
+  session_service = mock_vertex_ai_session_service()
+
+  expire_time = '2025-12-12T12:12:12.123456Z'
+  await session_service.create_session(
+      app_name='123', user_id='user', expire_time=expire_time
+  )
+  assert (
+      mock_api_client_instance.last_create_session_config['expire_time']
+      == expire_time
+  )
+
+
 @pytest.mark.asyncio
 @pytest.mark.usefixtures('mock_get_api_client')
 async def test_append_event():