ADK changes

PiperOrigin-RevId: 751099184

.github/workflows/python-unit-tests.yml

@@ -35,5 +35,7 @@ jobs:
       run: |
         source .venv/bin/activate
         pytest tests/unittests \
-          --ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py \
-          --ignore=tests/unittests/artifacts/test_artifact_service.py
+          --ignore=tests/unittests/artifacts/test_artifact_service.py \
+          --ignore=tests/unittests/tools/application_integration_tool/clients/test_connections_client.py \
+          --ignore=tests/unittests/tools/google_api_tool/test_googleapi_to_openapi_converter.py        
+          

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.3.0
+
+### ⚠ BREAKING CHANGES
+
+* Auth: expose `access_token` and `refresh_token` at top level of auth
+  credentails, instead of a `dict`
+  ([commit](https://github.com/google/adk-python/commit/956fb912e8851b139668b1ccb8db10fd252a6990)).
+
+### Features
+
+* Added support for running agents with MCPToolset easily on `adk web`.
+* Added `custom_metadata` field to `LlmResponse`, which can be used to tag
+  LlmResponse via `after_model_callback`.
+* Added `--session_db_url` to `adk deploy cloud_run` option.
+* Many Dev UI improvements:
+  * Better google search result rendering.
+  * Show websocket close reason in Dev UI.
+  * Better error message showing for audio/video.
+
+### Bug Fixes
+
+* Fixed MCP tool json schema parsing issue.
+* Fixed issues in DatabaseSessionService that leads to crash.
+* Fixed functions.py.
+* Fixed `skip_summarization` behavior in `AgentTool`.
+
+### Miscellaneous Chores
+
+* README.md impprovements.
+* Various code improvements.
+* Various typo fixes.
+* Bump min version of google-genai to 1.11.0.
+
 ## 0.2.0
 
 ### ⚠ BREAKING CHANGES
@@ -45,12 +78,12 @@
 * Initial release of the Agent Development Kit (ADK).
 * Multi-agent, agent-as-workflow, and custom agent support
 * Tool authentication support
-* Rich tool support, e.g. bult-in tools, google-cloud tools, third-party tools, and MCP tools
+* Rich tool support, e.g. built-in tools, google-cloud tools, third-party tools, and MCP tools
 * Rich callback support
 * Built-in code execution capability
 * Asynchronous runtime and execution
 * Session, and memory support
 * Built-in evaluation support
-* Development UI that makes local devlopment easy
+* Development UI that makes local development easy
 * Deploy to Google Cloud Run, Agent Engine
 * (Experimental) Live(Bidi) auido/video agent support and Compositional Function Calling(CFC) support

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
@@ -112,10 +127,18 @@ adk eval \
     samples_for_testing/hello_world/hello_world_eval_set_001.evalset.json
 ```
 
+## 🤖 A2A and ADK integration
+
+For remote agent-to-agent communication, ADK integrates with the
+[A2A protocol](https://github.com/google/A2A/).
+See this [example](https://github.com/google/A2A/tree/main/samples/python/agents/google_adk)
+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
 

pylintrc

@@ -45,7 +45,7 @@ confidence=
 # can either give multiple identifiers separated by comma (,) or put this
 # option multiple times (only on the command line, not in the configuration
 # file where it should appear only once).You can also use "--disable=all" to
-# disable everything first and then reenable specific checks. For example, if
+# disable everything first and then re-enable specific checks. For example, if
 # you want to run only the similarities checker, you can use "--disable=all
 # --enable=similarities". If you want to run only the classes checker, but have
 # no Warning level messages displayed, use"--disable=all --enable=classes

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/agents/callback_context.py

@@ -23,7 +23,6 @@ from .readonly_context import ReadonlyContext
 if TYPE_CHECKING:
   from google.genai import types
 
-  from ..events.event import Event
   from ..events.event_actions import EventActions
   from ..sessions.state import State
   from .invocation_context import InvocationContext

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 @@ class AuthHandler:
         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 @@ class AuthHandler:
         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 @@ class AuthHandler:
 
     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 @@ COPY "agents/{app_name}/" "/app/agents/{app_name}/"
 
 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_eval.py

@@ -256,7 +256,7 @@ def run_evals(
         )
 
         if final_eval_status == EvalStatus.PASSED:
-          result = "✅ Passsed"
+          result = "✅ Passed"
         else:
           result = "❌ Failed"
 

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 @@ def cli_web(
 @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 @@ def get_fast_api_app(
     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/evaluation/agent_evaluator.py

@@ -55,7 +55,7 @@ def load_json(file_path: str) -> Union[Dict, List]:
 
 
 class AgentEvaluator:
-  """An evaluator for Agents, mainly intented for helping with test cases."""
+  """An evaluator for Agents, mainly intended for helping with test cases."""
 
   @staticmethod
   def find_config_for_test_file(test_file: str):
@@ -91,7 +91,7 @@ class AgentEvaluator:
         look for 'root_agent' in the loaded module.
       eval_dataset: The eval data set. This can be either a string representing
         full path to the file containing eval dataset, or a directory that is
-        recusively explored for all files that have a `.test.json` suffix.
+        recursively explored for all files that have a `.test.json` suffix.
       num_runs: Number of times all entries in the eval dataset should be
         assessed.
       agent_name: The name of the agent.

src/google/adk/evaluation/response_evaluator.py

@@ -35,7 +35,7 @@ class ResponseEvaluator:
     Args:
       raw_eval_dataset: The dataset that will be evaluated.
       evaluation_criteria: The evaluation criteria to be used. This method
-        support two criterias, `response_evaluation_score` and
+        support two criteria, `response_evaluation_score` and
         `response_match_score`.
       print_detailed_results: Prints detailed results on the console. This is
         usually helpful during debugging.
@@ -56,7 +56,7 @@ class ResponseEvaluator:
         Value range: [0, 5], where 0 means that the agent's response is not
         coherent, while 5 means it is . High values are good.
     A note on raw_eval_dataset:
-      The dataset should be a list session, where each sesssion is represented
+      The dataset should be a list session, where each session is represented
       as a list of interaction that need evaluation. Each evaluation is
       represented as a dictionary that is expected to have values for the
       following keys:

src/google/adk/evaluation/trajectory_evaluator.py

@@ -31,10 +31,9 @@ class TrajectoryEvaluator:
   ):
     r"""Returns the mean tool use accuracy of the eval dataset.
 
-    Tool use accuracy is calculated by comparing the expected and actuall tool
-    use trajectories. An exact match scores a 1, 0 otherwise. The final number
-    is an
-    average of these individual scores.
+    Tool use accuracy is calculated by comparing the expected and the actual
+    tool use trajectories. An exact match scores a 1, 0 otherwise. The final
+    number is an average of these individual scores.
 
     Value range: [0, 1], where 0 is means none of the too use entries aligned,
     and 1 would mean all of them aligned. Higher value is good.
@@ -45,7 +44,7 @@ class TrajectoryEvaluator:
         usually helpful during debugging.
 
     A note on eval_dataset:
-      The dataset should be a list session, where each sesssion is represented
+      The dataset should be a list session, where each session is represented
       as a list of interaction that need evaluation. Each evaluation is
       represented as a dictionary that is expected to have values for the
       following keys:

src/google/adk/flows/llm_flows/agent_transfer.py

@@ -94,7 +94,7 @@ can answer it.
 
 If another agent is better for answering the question according to its
 description, call `{_TRANSFER_TO_AGENT_FUNCTION_NAME}` function to transfer the
-question to that agent. When transfering, do not generate any text other than
+question to that agent. When transferring, do not generate any text other than
 the function call.
 """
 

src/google/adk/flows/llm_flows/base_llm_flow.py

@@ -115,7 +115,7 @@ class BaseLlmFlow(ABC):
           yield event
           # send back the function response
           if event.get_function_responses():
-            logger.debug('Sending back last function resonse event: %s', event)
+            logger.debug('Sending back last function response event: %s', event)
             invocation_context.live_request_queue.send_content(event.content)
           if (
               event.content