Merge branch 'main' into fix-dep-session.send

Author: hangfei

contributing/samples/mcp_service_account_agent/README.md

@@ -0,0 +1,55 @@
+# MCP Service Account Agent Sample
+
+This agent demonstrates how to connect to a remote MCP server using a gcloud service account for authentication. It uses Streamable HTTP for communication.
+
+## Setup
+
+Before running the agent, you need to configure the MCP server URL and your service account credentials in `agent.py`.
+
+1.  **Configure MCP Server URL:**
+    Update the `MCP_SERVER_URL` variable with the URL of your MCP server instance.
+
+    ```python
+    # agent.py
+    # TODO: Update this to the production MCP server url and scopes.
+    MCP_SERVER_URL = "https://test.sandbox.googleapis.com/mcp"
+    ```
+
+2.  **Set up Service Account Credentials:**
+    -   Obtain the JSON key file for your gcloud service account.
+    -   In `agent.py`, find the `ServiceAccountCredential` object and populate its parameters (e.g., `project_id`, `private_key`, `client_email`, etc.) with the corresponding values from your JSON key file.
+
+    ```python
+    # agent.py
+    # TODO: Update this to the user's service account credentials.
+    auth_credential=AuthCredential(
+        auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
+        service_account=ServiceAccount(
+            service_account_credential=ServiceAccountCredential(
+                type_="service_account",
+                project_id="example",
+                private_key_id="123",
+                private_key="123",
+                client_email="test@example.iam.gserviceaccount.com",
+                client_id="123",
+                auth_uri="https://accounts.google.com/o/oauth2/auth",
+                token_uri="https://oauth2.googleapis.com/token",
+                auth_provider_x509_cert_url=(
+                    "https://www.googleapis.com/oauth2/v1/certs"
+                ),
+                client_x509_cert_url="https://www.googleapis.com/robot/v1/metadata/x509/example.iam.gserviceaccount.com",
+                universe_domain="googleapis.com",
+            ),
+            scopes=SCOPES.keys(),
+        ),
+    ),
+    ```
+
+## Running the Agent
+
+Once configured, you can run the agent.
+
+For example:
+```bash
+adk web
+```

contributing/samples/mcp_service_account_agent/__init__.py

@@ -0,0 +1,15 @@
+# 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 . import agent

contributing/samples/mcp_service_account_agent/agent.py

@@ -0,0 +1,74 @@
+# 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 fastapi.openapi.models import OAuth2
+from fastapi.openapi.models import OAuthFlowClientCredentials
+from fastapi.openapi.models import OAuthFlows
+from google.adk.agents.llm_agent import LlmAgent
+from google.adk.auth.auth_credential import AuthCredential
+from google.adk.auth.auth_credential import AuthCredentialTypes
+from google.adk.auth.auth_credential import ServiceAccount
+from google.adk.auth.auth_credential import ServiceAccountCredential
+from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPServerParams
+from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset
+
+# TODO: Update this to the production MCP server url and scopes.
+MCP_SERVER_URL = "https://test.sandbox.googleapis.com/mcp"
+SCOPES = {"https://www.googleapis.com/auth/cloud-platform": ""}
+
+root_agent = LlmAgent(
+    model="gemini-2.0-flash",
+    name="enterprise_assistant",
+    instruction="""
+Help the user with the tools available to you.
+    """,
+    tools=[
+        MCPToolset(
+            connection_params=StreamableHTTPServerParams(
+                url=MCP_SERVER_URL,
+            ),
+            auth_scheme=OAuth2(
+                flows=OAuthFlows(
+                    clientCredentials=OAuthFlowClientCredentials(
+                        tokenUrl="https://oauth2.googleapis.com/token",
+                        scopes=SCOPES,
+                    )
+                )
+            ),
+            # TODO: Update this to the user's service account credentials.
+            auth_credential=AuthCredential(
+                auth_type=AuthCredentialTypes.SERVICE_ACCOUNT,
+                service_account=ServiceAccount(
+                    service_account_credential=ServiceAccountCredential(
+                        type_="service_account",
+                        project_id="example",
+                        private_key_id="123",
+                        private_key="123",
+                        client_email="test@example.iam.gserviceaccount.com",
+                        client_id="123",
+                        auth_uri="https://accounts.google.com/o/oauth2/auth",
+                        token_uri="https://oauth2.googleapis.com/token",
+                        auth_provider_x509_cert_url=(
+                            "https://www.googleapis.com/oauth2/v1/certs"
+                        ),
+                        client_x509_cert_url="https://www.googleapis.com/robot/v1/metadata/x509/example.iam.gserviceaccount.com",
+                        universe_domain="googleapis.com",
+                    ),
+                    scopes=SCOPES.keys(),
+                ),
+            ),
+        )
+    ],
+)

contributing/samples/migrate_session_db/README.md

@@ -0,0 +1,55 @@
+# Loading and Upgrading Old Session Databases
+
+This example demonstrates how to upgrade a session database created with an older version of ADK to be compatible with the current version.
+
+## Sample Database
+
+This sample includes `dnd_sessions.db`, a database created with ADK v1.15.0. The following steps show how to run into a schema error and then resolve it using the migration script.
+
+## 1. Reproduce the Error
+
+First, copy the old database to `sessions.db`, which is the file the sample application expects.
+
+```bash
+cp dnd_sessions.db sessions.db
+python main.py
+```
+
+Running the application against the old database will fail with a schema mismatch error, as the `events` table is missing a column required by newer ADK versions:
+
+```
+sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) no such column: events.usage_metadata
+```
+
+## 2. Upgrade the Database Schema
+
+ADK provides a migration script to update the database schema. Run the following command to download and execute it.
+
+```bash
+# Clean up the previous run before executing the migration
+cp dnd_sessions.db sessions.db
+
+# Download and run the migration script
+curl -fsSL https://raw.githubusercontent.com/google/adk-python/main/scripts/db_migration.sh | sh -s -- "sqlite:///%(here)s/sessions.db" "google.adk.sessions.database_session_service"
+```
+
+This script uses `alembic` to compare the existing schema against the current model definition and automatically generates and applies the necessary migrations.
+
+**Note on generated files:**
+*   The script will create an `alembic.ini` file and an `alembic/` directory. You must delete these before re-running the script.
+*   The `sample-output` directory in this example contains a reference of the generated files for your inspection.
+*   The `%(here)s` variable in the database URL is an `alembic` placeholder that refers to the current directory.
+
+## 3. Run the Agent Successfully
+
+With the database schema updated, the application can now load the session correctly.
+
+```bash
+python main.py
+```
+
+You should see output indicating that the old session was successfully loaded.
+
+## Limitations
+
+The migration script is designed to add new columns that have been introduced in newer ADK versions. It does not handle more complex schema changes, such as modifying a column's data type (e.g., from `int` to `string`) or altering the internal structure of stored data.

contributing/samples/migrate_session_db/__init__.py

@@ -0,0 +1,16 @@
+# 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 . import agent

contributing/samples/migrate_session_db/agent.py

@@ -0,0 +1,89 @@
+# 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.
+
+
+import random
+
+from google.adk.agents.llm_agent import Agent
+
+
+def roll_die(sides: int) -> int:
+  """Roll a die and return the rolled result.
+
+  Args:
+    sides: The integer number of sides the die has.
+
+  Returns:
+    An integer of the result of rolling the die.
+  """
+  return random.randint(1, sides)
+
+
+async def check_prime(nums: list[int]) -> str:
+  """Check if a given list of numbers are prime.
+
+  Args:
+    nums: The list of numbers to check.
+
+  Returns:
+    A str indicating which number is prime.
+  """
+  primes = set()
+  for number in nums:
+    number = int(number)
+    if number <= 1:
+      continue
+    is_prime = True
+    for i in range(2, int(number**0.5) + 1):
+      if number % i == 0:
+        is_prime = False
+        break
+    if is_prime:
+      primes.add(number)
+  return (
+      "No prime numbers found."
+      if not primes
+      else f"{', '.join(str(num) for num in primes)} are prime numbers."
+  )
+
+
+root_agent = Agent(
+    model="gemini-2.0-flash",
+    name="migrate_session_db_agent",
+    description=(
+        "hello world agent that can roll a dice of 8 sides and check prime"
+        " numbers."
+    ),
+    instruction="""
+      You roll dice and answer questions about the outcome of the dice rolls.
+      You can roll dice of different sizes.
+      You can use multiple tools in parallel by calling functions in parallel(in one request and in one round).
+      It is ok to discuss previous dice roles, and comment on the dice rolls.
+      When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
+      You should never roll a die on your own.
+      When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
+      You should not check prime numbers before calling the tool.
+      When you are asked to roll a die and check prime numbers, you should always make the following two function calls:
+      1. You should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.
+      2. After you get the function response from roll_die tool, you should call the check_prime tool with the roll_die result.
+        2.1 If user asks you to check primes based on previous rolls, make sure you include the previous rolls in the list.
+      3. When you respond, you must include the roll_die result from step 1.
+      You should always perform the previous 3 steps when asking for a roll and checking prime numbers.
+      You should not rely on the previous history on prime results.
+    """,
+    tools=[
+        roll_die,
+        check_prime,
+    ],
+)

contributing/samples/migrate_session_db/dnd_sessions.db

@@ -0,0 +1,79 @@
+# 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.
+
+
+import asyncio
+import time
+
+import agent
+from dotenv import load_dotenv
+from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
+from google.adk.cli.utils import logs
+from google.adk.runners import Runner
+from google.adk.sessions.database_session_service import DatabaseSessionService
+from google.adk.sessions.session import Session
+from google.genai import types
+
+load_dotenv(override=True)
+logs.log_to_tmp_folder()
+
+
+async def main():
+  app_name = 'migrate_session_db_app'
+  user_id_1 = 'user1'
+  session_service = DatabaseSessionService('sqlite:///./sessions.db')
+  artifact_service = InMemoryArtifactService()
+  runner = Runner(
+      app_name=app_name,
+      agent=agent.root_agent,
+      artifact_service=artifact_service,
+      session_service=session_service,
+  )
+  session_11 = await session_service.get_session(
+      app_name=app_name,
+      user_id=user_id_1,
+      session_id='aee03f34-32ef-432b-b1bb-e66a3a79dd5b',
+  )
+  print('Session 11 loaded:', session_11.id)
+
+  async def run_prompt(session: Session, new_message: str):
+    content = types.Content(
+        role='user', parts=[types.Part.from_text(text=new_message)]
+    )
+    print('** User says:', content.model_dump(exclude_none=True))
+    async for event in runner.run_async(
+        user_id=user_id_1,
+        session_id=session.id,
+        new_message=content,
+    ):
+      if event.content.parts and event.content.parts[0].text:
+        print(f'** {event.author}: {event.content.parts[0].text}')
+
+  start_time = time.time()
+  print('Start time:', start_time)
+  print('------------------------------------')
+  await run_prompt(session_11, 'Hi, introduce yourself.')
+  await run_prompt(
+      session_11, 'Roll a die with 100 sides and check if it is prime'
+  )
+  await run_prompt(session_11, 'Roll it again.')
+  await run_prompt(session_11, 'What numbers did I got?')
+  end_time = time.time()
+  print('------------------------------------')
+  print('End time:', end_time)
+  print('Total time:', end_time - start_time)
+
+
+if __name__ == '__main__':
+  asyncio.run(main())