google-adk 1.4.2__py3-none-any.whl → 1.5.0__py3-none-any.whl

google/adk/a2a/converters/request_converter.py

@@ -0,0 +1,90 @@
+# 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
+
+import sys
+from typing import Any
+
+try:
+  from a2a.server.agent_execution import RequestContext
+except ImportError as e:
+  if sys.version_info < (3, 10):
+    raise ImportError(
+        'A2A Tool requires Python 3.10 or above. Please upgrade your Python'
+        ' version.'
+    ) from e
+  else:
+    raise e
+
+from google.genai import types as genai_types
+
+from ...runners import RunConfig
+from ...utils.feature_decorator import working_in_progress
+from .part_converter import convert_a2a_part_to_genai_part
+from .utils import _from_a2a_context_id
+from .utils import _get_adk_metadata_key
+
+
+def _get_user_id(request: RequestContext, user_id_from_context: str) -> str:
+  # Get user from call context if available (auth is enabled on a2a server)
+  if request.call_context and request.call_context.user:
+    return request.call_context.user.user_name
+
+  # Get user from context id if available
+  if user_id_from_context:
+    return user_id_from_context
+
+  # Get user from message metadata if available (client is an ADK agent)
+  if request.message.metadata:
+    user_id = request.message.metadata.get(_get_adk_metadata_key('user_id'))
+    if user_id:
+      return f'ADK_USER_{user_id}'
+
+  # Get user from task if available (client is a an ADK agent)
+  if request.current_task:
+    user_id = request.current_task.metadata.get(
+        _get_adk_metadata_key('user_id')
+    )
+    if user_id:
+      return f'ADK_USER_{user_id}'
+  return (
+      f'temp_user_{request.task_id}'
+      if request.task_id
+      else f'TEMP_USER_{request.message.messageId}'
+  )
+
+
+@working_in_progress
+def convert_a2a_request_to_adk_run_args(
+    request: RequestContext,
+) -> dict[str, Any]:
+
+  if not request.message:
+    raise ValueError('Request message cannot be None')
+
+  _, user_id, session_id = _from_a2a_context_id(request.context_id)
+
+  return {
+      'user_id': _get_user_id(request, user_id),
+      'session_id': session_id,
+      'new_message': genai_types.Content(
+          role='user',
+          parts=[
+              convert_a2a_part_to_genai_part(part)
+              for part in request.message.parts
+          ],
+      ),
+      'run_config': RunConfig(),
+  }

google/adk/a2a/converters/utils.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 ADK_METADATA_KEY_PREFIX = "adk_"
+ADK_CONTEXT_ID_PREFIX = "ADK"
 
 
 def _get_adk_metadata_key(key: str) -> str:
@@ -32,3 +33,39 @@ def _get_adk_metadata_key(key: str) -> str:
   if not key:
     raise ValueError("Metadata key cannot be empty or None")
   return f"{ADK_METADATA_KEY_PREFIX}{key}"
+
+
+def _to_a2a_context_id(app_name: str, user_id: str, session_id: str) -> str:
+  """Converts app name, user id and session id to an A2A context id.
+
+  Args:
+    app_name: The app name.
+    user_id: The user id.
+    session_id: The session id.
+
+  Returns:
+    The A2A context id.
+  """
+  return [ADK_CONTEXT_ID_PREFIX, app_name, user_id, session_id].join("$")
+
+
+def _from_a2a_context_id(context_id: str) -> tuple[str, str, str]:
+  """Converts an A2A context id to app name, user id and session id.
+  if context_id is None, return None, None, None
+  if context_id is not None, but not in the format of
+  ADK$app_name$user_id$session_id, return None, None, None
+
+  Args:
+    context_id: The A2A context id.
+
+  Returns:
+    The app name, user id and session id.
+  """
+  if not context_id:
+    return None, None, None
+
+  prefix, app_name, user_id, session_id = context_id.split("$")
+  if prefix == "ADK" and app_name and user_id and session_id:
+    return app_name, user_id, session_id
+
+  return None, None, None

google/adk/agents/llm_agent.py

@@ -161,10 +161,12 @@ class LlmAgent(BaseAgent):
   # LLM-based agent transfer configs - End
 
   include_contents: Literal['default', 'none'] = 'default'
-  """Whether to include contents in the model request.
+  """Controls content inclusion in model requests.
 
-  When set to 'none', the model request will not include any contents, such as
-  user messages, tool results, etc.
+  Options:
+      default: Model receives relevant conversation history
+      none: Model receives no prior history, operates solely on current
+            instruction and input
   """
 
   # Controlled input/output configurations - Start

google/adk/artifacts/gcs_artifact_service.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 """An artifact service implementation using Google Cloud Storage (GCS)."""
+from __future__ import annotations
 
 import logging
 from typing import Optional
@@ -151,7 +152,7 @@ class GcsArtifactService(BaseArtifactService):
         self.bucket, prefix=session_prefix
     )
     for blob in session_blobs:
-      _, _, _, filename, _ = blob.name.split("/")
+      *_, filename, _ = blob.name.split("/")
       filenames.add(filename)
 
     user_namespace_prefix = f"{app_name}/{user_id}/user/"
@@ -159,7 +160,7 @@ class GcsArtifactService(BaseArtifactService):
         self.bucket, prefix=user_namespace_prefix
     )
     for blob in user_namespace_blobs:
-      _, _, _, filename, _ = blob.name.split("/")
+      *_, filename, _ = blob.name.split("/")
       filenames.add(filename)
 
     return sorted(list(filenames))

google/adk/auth/auth_tool.py

@@ -31,12 +31,12 @@ class AuthConfig(BaseModelWithConfig):
 
   auth_scheme: AuthScheme
   """The auth scheme used to collect credentials"""
-  raw_auth_credential: AuthCredential = None
+  raw_auth_credential: Optional[AuthCredential] = None
   """The raw auth credential used to collect credentials. The raw auth
   credentials are used in some auth scheme that needs to exchange auth
   credentials. e.g. OAuth2 and OIDC. For other auth scheme, it could be None.
   """
-  exchanged_auth_credential: AuthCredential = None
+  exchanged_auth_credential: Optional[AuthCredential] = None
   """The exchanged auth credential used to collect credentials. adk and client
   will work together to fill it. For those auth scheme that doesn't need to
   exchange auth credentials, e.g. API key, service account etc. It's filled by

google/adk/auth/credential_service/session_state_credential_service.py

@@ -0,0 +1,83 @@
+# 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 SessionStateCredentialService(BaseCredentialService):
+  """Class for implementation of credential service using session state as the
+  store.
+  Note: store credential in session may not be secure, use at your own risk.
+  """
+
+  @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.
+
+    """
+    return tool_context.state.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
+    """
+
+    tool_context.state[auth_config.credential_key] = (
+        auth_config.exchanged_auth_credential
+    )

google/adk/cli/cli_deploy.py

@@ -55,7 +55,7 @@ COPY "agents/{app_name}/" "/app/agents/{app_name}/"
 
 EXPOSE {port}
 
-CMD adk {command} --port={port} {host_option} {service_option} {trace_to_cloud_option} "/app/agents"
+CMD adk {command} --port={port} {host_option} {service_option} {trace_to_cloud_option} {allow_origins_option} "/app/agents"
 """
 
 _AGENT_ENGINE_APP_TEMPLATE = """
@@ -121,8 +121,10 @@ def to_cloud_run(
     port: int,
     trace_to_cloud: bool,
     with_ui: bool,
+    log_level: str,
     verbosity: str,
     adk_version: str,
+    allow_origins: Optional[list[str]] = None,
     session_service_uri: Optional[str] = None,
     artifact_service_uri: Optional[str] = None,
     memory_service_uri: Optional[str] = None,
@@ -150,6 +152,7 @@ def to_cloud_run(
     app_name: The name of the app, by default, it's basename of `agent_folder`.
     temp_folder: The temp folder for the generated Cloud Run source files.
     port: The port of the ADK api server.
+    allow_origins: The list of allowed origins for the ADK api server.
     trace_to_cloud: Whether to enable Cloud Trace.
     with_ui: Whether to deploy with UI.
     verbosity: The verbosity level of the CLI.
@@ -183,6 +186,9 @@ def to_cloud_run(
     # create Dockerfile
     click.echo('Creating Dockerfile...')
     host_option = '--host=0.0.0.0' if adk_version > '0.5.0' else ''
+    allow_origins_option = (
+        f'--allow_origins={",".join(allow_origins)}' if allow_origins else ''
+    )
     dockerfile_content = _DOCKERFILE_TEMPLATE.format(
         gcp_project_id=project,
         gcp_region=region,
@@ -197,6 +203,7 @@ def to_cloud_run(
             memory_service_uri,
         ),
         trace_to_cloud_option='--trace_to_cloud' if trace_to_cloud else '',
+        allow_origins_option=allow_origins_option,
         adk_version=adk_version,
         host_option=host_option,
     )
@@ -226,7 +233,7 @@ def to_cloud_run(
             '--port',
             str(port),
             '--verbosity',
-            verbosity,
+            log_level.lower() if log_level else verbosity,
             '--labels',
             'created-by=adk',
         ],

google/adk/cli/cli_tools_click.py

@@ -31,14 +31,22 @@ import uvicorn
 from . import cli_create
 from . import cli_deploy
 from .. import version
+from ..evaluation.gcs_eval_set_results_manager import GcsEvalSetResultsManager
+from ..evaluation.gcs_eval_sets_manager import GcsEvalSetsManager
 from ..evaluation.local_eval_set_results_manager import LocalEvalSetResultsManager
 from ..sessions.in_memory_session_service import InMemorySessionService
 from .cli import run_cli
 from .cli_eval import MISSING_EVAL_DEPENDENCIES_MESSAGE
 from .fast_api import get_fast_api_app
 from .utils import envs
+from .utils import evals
 from .utils import logs
 
+LOG_LEVELS = click.Choice(
+    ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+    case_sensitive=False,
+)
+
 
 class HelpfulCommand(click.Command):
   """Command that shows full help on error instead of just the error message.
@@ -277,11 +285,21 @@ def cli_run(
     default=False,
     help="Optional. Whether to print detailed results on console or not.",
 )
+@click.option(
+    "--eval_storage_uri",
+    type=str,
+    help=(
+        "Optional. The evals storage URI to store agent evals,"
+        " supported URIs: gs://<bucket name>."
+    ),
+    default=None,
+)
 def cli_eval(
     agent_module_file_path: str,
-    eval_set_file_path: tuple[str],
+    eval_set_file_path: list[str],
     config_file_path: str,
     print_detailed_results: bool,
+    eval_storage_uri: Optional[str] = None,
 ):
   """Evaluates an agent given the eval sets.
 
@@ -333,12 +351,33 @@ def cli_eval(
   root_agent = get_root_agent(agent_module_file_path)
   reset_func = try_get_reset_func(agent_module_file_path)
 
+  gcs_eval_sets_manager = None
+  eval_set_results_manager = None
+  if eval_storage_uri:
+    gcs_eval_managers = evals.create_gcs_eval_managers_from_uri(
+        eval_storage_uri
+    )
+    gcs_eval_sets_manager = gcs_eval_managers.eval_sets_manager
+    eval_set_results_manager = gcs_eval_managers.eval_set_results_manager
+  else:
+    eval_set_results_manager = LocalEvalSetResultsManager(
+        agents_dir=os.path.dirname(agent_module_file_path)
+    )
   eval_set_file_path_to_evals = parse_and_get_evals_to_run(eval_set_file_path)
   eval_set_id_to_eval_cases = {}
 
   # Read the eval_set files and get the cases.
   for eval_set_file_path, eval_case_ids in eval_set_file_path_to_evals.items():
-    eval_set = load_eval_set_from_file(eval_set_file_path, eval_set_file_path)
+    if gcs_eval_sets_manager:
+      eval_set = gcs_eval_sets_manager._load_eval_set_from_blob(
+          eval_set_file_path
+      )
+      if not eval_set:
+        raise click.ClickException(
+            f"Eval set {eval_set_file_path} not found in GCS."
+        )
+    else:
+      eval_set = load_eval_set_from_file(eval_set_file_path, eval_set_file_path)
     eval_cases = eval_set.eval_cases
 
     if eval_case_ids:
@@ -373,16 +412,13 @@ def cli_eval(
     raise click.ClickException(MISSING_EVAL_DEPENDENCIES_MESSAGE)
 
   # Write eval set results.
-  local_eval_set_results_manager = LocalEvalSetResultsManager(
-      agents_dir=os.path.dirname(agent_module_file_path)
-  )
   eval_set_id_to_eval_results = collections.defaultdict(list)
   for eval_case_result in eval_results:
     eval_set_id = eval_case_result.eval_set_id
     eval_set_id_to_eval_results[eval_set_id].append(eval_case_result)
 
   for eval_set_id, eval_case_results in eval_set_id_to_eval_results.items():
-    local_eval_set_results_manager.save_eval_set_result(
+    eval_set_results_manager.save_eval_set_result(
         app_name=os.path.basename(agent_module_file_path),
         eval_set_id=eval_set_id,
         eval_case_results=eval_case_results,
@@ -439,12 +475,22 @@ def adk_services_options():
         ),
         default=None,
     )
+    @click.option(
+        "--eval_storage_uri",
+        type=str,
+        help=(
+            "Optional. The evals storage URI to store agent evals,"
+            " supported URIs: gs://<bucket name>."
+        ),
+        default=None,
+    )
     @click.option(
         "--memory_service_uri",
         type=str,
         help=(
             """Optional. The URI of the memory service.
-            - Use 'rag://<rag_corpus_id>' to connect to Vertex AI Rag Memory Service."""
+            - Use 'rag://<rag_corpus_id>' to connect to Vertex AI Rag Memory Service.
+            - Use 'agentengine://<agent_engine_resource_id>' to connect to Vertex AI Memory Bank Service. e.g. agentengine://12345"""
         ),
         default=None,
     )
@@ -498,13 +544,6 @@ def fast_api_common_options():
   """Decorator to add common fast api options to click commands."""
 
   def decorator(func):
-    @click.option(
-        "--host",
-        type=str,
-        help="Optional. The binding host of the server",
-        default="127.0.0.1",
-        show_default=True,
-    )
     @click.option(
         "--port",
         type=int,
@@ -518,10 +557,7 @@ def fast_api_common_options():
     )
     @click.option(
         "--log_level",
-        type=click.Choice(
-            ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
-            case_sensitive=False,
-        ),
+        type=LOG_LEVELS,
         default="INFO",
         help="Optional. Set the logging level",
     )
@@ -535,7 +571,10 @@ def fast_api_common_options():
     @click.option(
         "--reload/--no-reload",
         default=True,
-        help="Optional. Whether to enable auto reload for server.",
+        help=(
+            "Optional. Whether to enable auto reload for server. Not supported"
+            " for Cloud Run."
+        ),
     )
     @functools.wraps(func)
     def wrapper(*args, **kwargs):
@@ -547,6 +586,13 @@ def fast_api_common_options():
 
 
 @main.command("web")
+@click.option(
+    "--host",
+    type=str,
+    help="Optional. The binding host of the server",
+    default="127.0.0.1",
+    show_default=True,
+)
 @fast_api_common_options()
 @adk_services_options()
 @deprecated_adk_services_options()
@@ -559,6 +605,7 @@ def fast_api_common_options():
 )
 def cli_web(
     agents_dir: str,
+    eval_storage_uri: Optional[str] = None,
     log_level: str = "INFO",
     allow_origins: Optional[list[str]] = None,
     host: str = "127.0.0.1",
@@ -578,7 +625,7 @@ def cli_web(
 
   Example:
 
-    adk web --session_service_uri=[uri] --port=[port] path/to/agents_dir
+    adk web --port=[port] path/to/agents_dir
   """
   logs.setup_adk_logger(getattr(logging, log_level.upper()))
 
@@ -611,6 +658,7 @@ def cli_web(
       session_service_uri=session_service_uri,
       artifact_service_uri=artifact_service_uri,
       memory_service_uri=memory_service_uri,
+      eval_storage_uri=eval_storage_uri,
       allow_origins=allow_origins,
       web=True,
       trace_to_cloud=trace_to_cloud,
@@ -628,6 +676,16 @@ def cli_web(
 
 
 @main.command("api_server")
+@click.option(
+    "--host",
+    type=str,
+    help="Optional. The binding host of the server",
+    default="127.0.0.1",
+    show_default=True,
+)
+@fast_api_common_options()
+@adk_services_options()
+@deprecated_adk_services_options()
 # The directory of agents, where each sub-directory is a single agent.
 # By default, it is the current working directory
 @click.argument(
@@ -637,11 +695,9 @@ def cli_web(
     ),
     default=os.getcwd(),
 )
-@fast_api_common_options()
-@adk_services_options()
-@deprecated_adk_services_options()
 def cli_api_server(
     agents_dir: str,
+    eval_storage_uri: Optional[str] = None,
     log_level: str = "INFO",
     allow_origins: Optional[list[str]] = None,
     host: str = "127.0.0.1",
@@ -661,7 +717,7 @@ def cli_api_server(
 
   Example:
 
-    adk api_server --session_service_uri=[uri] --port=[port] path/to/agents_dir
+    adk api_server --port=[port] path/to/agents_dir
   """
   logs.setup_adk_logger(getattr(logging, log_level.upper()))
 
@@ -673,6 +729,7 @@ def cli_api_server(
           session_service_uri=session_service_uri,
           artifact_service_uri=artifact_service_uri,
           memory_service_uri=memory_service_uri,
+          eval_storage_uri=eval_storage_uri,
           allow_origins=allow_origins,
           web=False,
           trace_to_cloud=trace_to_cloud,
@@ -720,19 +777,7 @@ def cli_api_server(
         " of the AGENT source code)."
     ),
 )
-@click.option(
-    "--port",
-    type=int,
-    default=8000,
-    help="Optional. The port of the ADK API server (default: 8000).",
-)
-@click.option(
-    "--trace_to_cloud",
-    is_flag=True,
-    show_default=True,
-    default=False,
-    help="Optional. Whether to enable Cloud Trace for cloud run.",
-)
+@fast_api_common_options()
 @click.option(
     "--with_ui",
     is_flag=True,
@@ -743,6 +788,11 @@ def cli_api_server(
         " only)"
     ),
 )
+@click.option(
+    "--verbosity",
+    type=LOG_LEVELS,
+    help="Deprecated. Use --log_level instead.",
+)
 @click.option(
     "--temp_folder",
     type=str,
@@ -756,20 +806,6 @@ def cli_api_server(
         " (default: a timestamped folder in the system temp directory)."
     ),
 )
-@click.option(
-    "--verbosity",
-    type=click.Choice(
-        ["debug", "info", "warning", "error", "critical"], case_sensitive=False
-    ),
-    default="WARNING",
-    help="Optional. Override the default verbosity level.",
-)
-@click.argument(
-    "agent",
-    type=click.Path(
-        exists=True, dir_okay=True, file_okay=False, resolve_path=True
-    ),
-)
 @click.option(
     "--adk_version",
     type=str,
@@ -780,8 +816,23 @@ def cli_api_server(
         " version in the dev environment)"
     ),
 )
+@click.option(
+    "--eval_storage_uri",
+    type=str,
+    help=(
+        "Optional. The evals storage URI to store agent evals,"
+        " supported URIs: gs://<bucket name>."
+    ),
+    default=None,
+)
 @adk_services_options()
 @deprecated_adk_services_options()
+@click.argument(
+    "agent",
+    type=click.Path(
+        exists=True, dir_okay=True, file_okay=False, resolve_path=True
+    ),
+)
 def cli_deploy_cloud_run(
     agent: str,
     project: Optional[str],
@@ -792,11 +843,15 @@ def cli_deploy_cloud_run(
     port: int,
     trace_to_cloud: bool,
     with_ui: bool,
-    verbosity: str,
     adk_version: str,
+    log_level: Optional[str] = None,
+    verbosity: str = "WARNING",
+    reload: bool = True,
+    allow_origins: Optional[list[str]] = None,
     session_service_uri: Optional[str] = None,
     artifact_service_uri: Optional[str] = None,
     memory_service_uri: Optional[str] = None,
+    eval_storage_uri: Optional[str] = None,
     session_db_url: Optional[str] = None,  # Deprecated
     artifact_storage_uri: Optional[str] = None,  # Deprecated
 ):
@@ -808,6 +863,7 @@ def cli_deploy_cloud_run(
 
     adk deploy cloud_run --project=[project] --region=[region] path/to/my_agent
   """
+  log_level = log_level or verbosity
   session_service_uri = session_service_uri or session_db_url
   artifact_service_uri = artifact_service_uri or artifact_storage_uri
   try:
@@ -820,7 +876,9 @@ def cli_deploy_cloud_run(
         temp_folder=temp_folder,
         port=port,
         trace_to_cloud=trace_to_cloud,
+        allow_origins=allow_origins,
         with_ui=with_ui,
+        log_level=log_level,
         verbosity=verbosity,
         adk_version=adk_version,
         session_service_uri=session_service_uri,