Merge branch 'main' into live-error-toast

Author: wyf7107

CONTRIBUTING.md

@@ -25,9 +25,22 @@ This project follows
 
 ## Contribution process
 
+### Requirement for PRs
+
+- All PRs, other than small documentation or typo fixes, should have a Issue assoicated. If not, please create one. 
+- Small, focused PRs. Keep changes minimal—one concern per PR.
+- For bug fixes or features, please provide logs or screenshot after the fix is applied to help reviewers better understand the fix.
+- Please add corresponding testing for your code change if it's not covered by existing tests.
+
+### Large or Complex Changes
+For substantial features or architectural revisions:
+
+- Open an Issue First: Outline your proposal, including design considerations and impact.
+- Gather Feedback: Discuss with maintainers and the community to ensure alignment and avoid duplicate work
+
 ### Code reviews
 
 All submissions, including submissions by project members, require review. We
 use GitHub pull requests for this purpose. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
-information on using pull requests.
+information on using pull requests.

README.md

@@ -45,12 +45,27 @@ debugging, versioning, and deployment anywhere – from your laptop to the cloud
 
 ## 🚀 Installation
 
-You can install the ADK using `pip`:
+### Stable Release (Recommended)
+
+You can install the latest stable version of ADK using `pip`:
 
 ```bash
 pip install google-adk
 ```
 
+The release cadence is weekly.
+
+This version is recommended for most users as it represents the most recent official release.
+
+### Development Version
+Bug fixes and new features are merged into the main branch on GitHub first. If you need access to changes that haven't been included in an official PyPI release yet, you can install directly from the main branch:
+
+```bash
+pip install git+https://github.com/google/adk-python.git@main
+```
+
+Note: The development version is built directly from the latest code commits. While it includes the newest fixes and features, it may also contain experimental changes or bugs not present in the stable release. Use it primarily for testing upcoming changes or accessing critical fixes before they are officially released.
+
 ## 📚 Documentation
 
 Explore the full documentation for detailed guides on building, evaluating, and
@@ -121,7 +136,9 @@ for how they can work together.
 
 ## 🤝 Contributing
 
-We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please see our [**Contributing Guidelines**](./CONTRIBUTING.md) to get started.
+We welcome contributions from the community! Whether it's bug reports, feature requests, documentation improvements, or code contributions, please see our 
+- [General contribution guideline and flow](https://google.github.io/adk-docs/contributing-guide/#questions).
+- Then if you want to contribute code, please read [Code Contributing Guidelines](./CONTRIBUTING.md) to get started.
 
 ## 📄 License
 

pyproject.toml

@@ -33,7 +33,7 @@ dependencies = [
   "google-cloud-secret-manager>=2.22.0",     # Fetching secrets in RestAPI Tool
   "google-cloud-speech>=2.30.0",             # For Audo Transcription
   "google-cloud-storage>=2.18.0, <3.0.0",    # For GCS Artifact service
-  "google-genai>=1.9.0",                     # Google GenAI SDK
+  "google-genai>=1.11.0",                    # Google GenAI SDK
   "graphviz>=0.20.2",                        # Graphviz for graph rendering
   "mcp>=1.5.0;python_version>='3.10'",       # For MCP Toolset
   "opentelemetry-api>=1.31.0",               # OpenTelemetry

src/google/adk/auth/auth_credential.py

@@ -66,7 +66,8 @@ class OAuth2Auth(BaseModelWithConfig):
   redirect_uri: Optional[str] = None
   auth_response_uri: Optional[str] = None
   auth_code: Optional[str] = None
-  token: Optional[Dict[str, Any]] = None
+  access_token: Optional[str] = None
+  refresh_token: Optional[str] = None
 
 
 class ServiceAccountCredential(BaseModelWithConfig):

src/google/adk/auth/auth_handler.py

@@ -82,7 +82,8 @@ def exchange_auth_token(
         or not auth_credential.oauth2
         or not auth_credential.oauth2.client_id
         or not auth_credential.oauth2.client_secret
-        or auth_credential.oauth2.token
+        or auth_credential.oauth2.access_token
+        or auth_credential.oauth2.refresh_token
     ):
       return self.auth_config.exchanged_auth_credential
 
@@ -93,7 +94,7 @@ def exchange_auth_token(
         redirect_uri=auth_credential.oauth2.redirect_uri,
         state=auth_credential.oauth2.state,
     )
-    token = client.fetch_token(
+    tokens = client.fetch_token(
         token_endpoint,
         authorization_response=auth_credential.oauth2.auth_response_uri,
         code=auth_credential.oauth2.auth_code,
@@ -102,7 +103,10 @@ def exchange_auth_token(
 
     updated_credential = AuthCredential(
         auth_type=AuthCredentialTypes.OAUTH2,
-        oauth2=OAuth2Auth(token=dict(token)),
+        oauth2=OAuth2Auth(
+            access_token=tokens.get("access_token"),
+            refresh_token=tokens.get("refresh_token"),
+        ),
     )
     return updated_credential
 

src/google/adk/cli/cli_deploy.py

@@ -54,7 +54,7 @@
 
 EXPOSE {port}
 
-CMD adk {command} --port={port} {trace_to_cloud_option} "/app/agents"
+CMD adk {command} --port={port} {session_db_option} {trace_to_cloud_option} "/app/agents"
 """
 
 
@@ -85,6 +85,7 @@ def to_cloud_run(
     trace_to_cloud: bool,
     with_ui: bool,
     verbosity: str,
+    session_db_url: str,
 ):
   """Deploys an agent to Google Cloud Run.
 
@@ -112,6 +113,7 @@ def to_cloud_run(
     trace_to_cloud: Whether to enable Cloud Trace.
     with_ui: Whether to deploy with UI.
     verbosity: The verbosity level of the CLI.
+    session_db_url: The database URL to connect the session.
   """
   app_name = app_name or os.path.basename(agent_folder)
 
@@ -144,6 +146,9 @@ def to_cloud_run(
         port=port,
         command='web' if with_ui else 'api_server',
         install_agent_deps=install_agent_deps,
+        session_db_option=f'--session_db_url={session_db_url}'
+        if session_db_url
+        else '',
         trace_to_cloud_option='--trace_to_cloud' if trace_to_cloud else '',
     )
     dockerfile_path = os.path.join(temp_folder, 'Dockerfile')

src/google/adk/cli/cli_tools_click.py

@@ -245,12 +245,13 @@ def cli_eval(
 @click.option(
     "--session_db_url",
     help=(
-        "Optional. The database URL to store the session.\n\n  - Use"
-        " 'agentengine://<agent_engine_resource_id>' to connect to Vertex"
-        " managed session service.\n\n  - Use 'sqlite://<path_to_sqlite_file>'"
-        " to connect to a SQLite DB.\n\n  - See"
-        " https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls"
-        " for more details on supported DB URLs."
+        """Optional. The database URL to store the session.
+
+  - Use 'agentengine://<agent_engine_resource_id>' to connect to Agent Engine sessions.
+
+  - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
+
+  - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
     ),
 )
 @click.option(
@@ -366,12 +367,13 @@ async def _lifespan(app: FastAPI):
 @click.option(
     "--session_db_url",
     help=(
-        "Optional. The database URL to store the session.\n\n  - Use"
-        " 'agentengine://<agent_engine_resource_id>' to connect to Vertex"
-        " managed session service.\n\n  - Use 'sqlite://<path_to_sqlite_file>'"
-        " to connect to a SQLite DB.\n\n  - See"
-        " https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls"
-        " for more details on supported DB URLs."
+        """Optional. The database URL to store the session.
+
+  - Use 'agentengine://<agent_engine_resource_id>' to connect to Agent Engine sessions.
+
+  - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
+
+  - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
     ),
 )
 @click.option(
@@ -541,6 +543,18 @@ def cli_api_server(
     default="WARNING",
     help="Optional. Override the default verbosity level.",
 )
+@click.option(
+    "--session_db_url",
+    help=(
+        """Optional. The database URL to store the session.
+
+  - Use 'agentengine://<agent_engine_resource_id>' to connect to Agent Engine sessions.
+
+  - Use 'sqlite://<path_to_sqlite_file>' to connect to a SQLite DB.
+
+  - See https://docs.sqlalchemy.org/en/20/core/engines.html#backend-specific-urls for more details on supported DB URLs."""
+    ),
+)
 @click.argument(
     "agent",
     type=click.Path(
@@ -558,6 +572,7 @@ def cli_deploy_cloud_run(
     trace_to_cloud: bool,
     with_ui: bool,
     verbosity: str,
+    session_db_url: str,
 ):
   """Deploys an agent to Cloud Run.
 
@@ -579,6 +594,7 @@ def cli_deploy_cloud_run(
         trace_to_cloud=trace_to_cloud,
         with_ui=with_ui,
         verbosity=verbosity,
+        session_db_url=session_db_url,
     )
   except Exception as e:
     click.secho(f"Deploy failed: {e}", fg="red", err=True)

src/google/adk/cli/fast_api.py

@@ -756,6 +756,12 @@ async def process_messages():
     except Exception as e:
       logger.exception("Error during live websocket communication: %s", e)
       traceback.print_exc()
+      WEBSOCKET_INTERNAL_ERROR_CODE = 1011
+      WEBSOCKET_MAX_BYTES_FOR_REASON = 123
+      await websocket.close(
+          code=WEBSOCKET_INTERNAL_ERROR_CODE,
+          reason=str(e)[:WEBSOCKET_MAX_BYTES_FOR_REASON],
+      )
     finally:
       for task in pending:
         task.cancel()

src/google/adk/tools/openapi_tool/auth/credential_exchangers/oauth2_exchanger.py

@@ -69,7 +69,7 @@ def generate_auth_token(
         HTTP bearer token cannot be generated, return the original credential.
     """
 
-    if "access_token" not in auth_credential.oauth2.token:
+    if not auth_credential.oauth2.access_token:
       return auth_credential
 
     # Return the access token as a bearer token.
@@ -78,7 +78,7 @@ def generate_auth_token(
         http=HttpAuth(
             scheme="bearer",
             credentials=HttpCredentials(
-                token=auth_credential.oauth2.token["access_token"]
+                token=auth_credential.oauth2.access_token
             ),
         ),
     )
@@ -111,7 +111,7 @@ def exchange_credential(
       return auth_credential
 
     # If access token is exchanged, exchange a HTTPBearer token.
-    if auth_credential.oauth2.token:
+    if auth_credential.oauth2.access_token:
       return self.generate_auth_token(auth_credential)
 
     return None

tests/unittests/auth/test_auth_handler.py

@@ -126,12 +126,8 @@ def oauth2_credentials_with_token():
           client_id="mock_client_id",
           client_secret="mock_client_secret",
           redirect_uri="https://example.com/callback",
-          token={
-              "access_token": "mock_access_token",
-              "token_type": "bearer",
-              "expires_in": 3600,
-              "refresh_token": "mock_refresh_token",
-          },
+          access_token="mock_access_token",
+          refresh_token="mock_refresh_token",
       ),
   )
 
@@ -458,7 +454,7 @@ def test_oauth_scheme(self, mock_exchange_token, auth_config_with_exchanged):
     """Test with an OAuth auth scheme."""
     mock_exchange_token.return_value = AuthCredential(
         auth_type=AuthCredentialTypes.OAUTH2,
-        oauth2=OAuth2Auth(token={"access_token": "exchanged_token"}),
+        oauth2=OAuth2Auth(access_token="exchanged_token"),
     )
 
     handler = AuthHandler(auth_config_with_exchanged)
@@ -573,6 +569,6 @@ def test_successful_token_exchange(self, auth_config_with_auth_code):
     handler = AuthHandler(auth_config_with_auth_code)
     result = handler.exchange_auth_token()
 
-    assert result.oauth2.token["access_token"] == "mock_access_token"
-    assert result.oauth2.token["refresh_token"] == "mock_refresh_token"
+    assert result.oauth2.access_token == "mock_access_token"
+    assert result.oauth2.refresh_token == "mock_refresh_token"
     assert result.auth_type == AuthCredentialTypes.OAUTH2