google-adk 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

google/adk/cli/utils/agent_loader.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import importlib
 import logging
 import sys
+from typing import Optional
 
 from . import envs
 from ...agents.base_agent import BaseAgent
@@ -27,9 +28,13 @@ logger = logging.getLogger("google_adk." + __name__)
 class AgentLoader:
   """Centralized agent loading with proper isolation, caching, and .env loading.
   Support loading agents from below folder/file structures:
-  a) agents_dir/agent_name.py (with root_agent or agent.root_agent in it)
-  b) agents_dir/agent_name_folder/__init__.py (with root_agent or agent.root_agent in the package)
-  c) agents_dir/agent_name_folder/agent.py (where agent.py has root_agent)
+  a)  {agent_name}.agent as a module name:
+      agents_dir/{agent_name}/agent.py (with root_agent defined in the module)
+  b)  {agent_name} as a module name
+      agents_dir/{agent_name}.py (with root_agent defined in the module)
+  c)  {agent_name} as a package name
+      agents_dir/{agent_name}/__init__.py (with root_agent in the package)
+
   """
 
   def __init__(self, agents_dir: str):
@@ -37,48 +42,52 @@ class AgentLoader:
     self._original_sys_path = None
     self._agent_cache: dict[str, BaseAgent] = {}
 
-  def _load_from_module_or_package(self, agent_name: str) -> BaseAgent:
-    # Load for case: Import "<agent_name>" (as a package or module)
+  def _load_from_module_or_package(
+      self, agent_name: str
+  ) -> Optional[BaseAgent]:
+    # Load for case: Import "{agent_name}" (as a package or module)
     # Covers structures:
-    #   a) agents_dir/agent_name.py (with root_agent or agent.root_agent in it)
-    #   b) agents_dir/agent_name_folder/__init__.py (with root_agent or agent.root_agent in the package)
+    #   a) agents_dir/{agent_name}.py (with root_agent in the module)
+    #   b) agents_dir/{agent_name}/__init__.py (with root_agent in the package)
     try:
       module_candidate = importlib.import_module(agent_name)
-      # Check for "root_agent" directly in "<agent_name>" module/package
+      # Check for "root_agent" directly in "{agent_name}" module/package
       if hasattr(module_candidate, "root_agent"):
         logger.debug("Found root_agent directly in %s", agent_name)
-        return module_candidate.root_agent
-      # Check for "<agent_name>.agent.root_agent" structure (e.g. agent_name is a package,
-      # and it has an 'agent' submodule/attribute which in turn has 'root_agent')
-      if hasattr(module_candidate, "agent") and hasattr(
-          module_candidate.agent, "root_agent"
-      ):
-        logger.debug("Found root_agent in %s.agent attribute", agent_name)
-        if isinstance(module_candidate.agent, BaseAgent):
-          return module_candidate.agent.root_agent
+        if isinstance(module_candidate.root_agent, BaseAgent):
+          return module_candidate.root_agent
         else:
           logger.warning(
               "Root agent found is not an instance of BaseAgent. But a type %s",
-              type(module_candidate.agent),
+              type(module_candidate.root_agent),
           )
-    except ModuleNotFoundError:
-      logger.debug("Module %s itself not found.", agent_name)
-      # Re-raise as ValueError to be caught by the final error message construction
-      raise ValueError(
-          f"Module {agent_name} not found during import attempts."
-      ) from None
-    except ImportError as e:
-      logger.warning("Error importing %s: %s", agent_name, e)
+      else:
+        logger.debug(
+            "Module %s has no root_agent. Trying next pattern.",
+            agent_name,
+        )
+
+    except ModuleNotFoundError as e:
+      if e.name == agent_name:
+        logger.debug("Module %s itself not found.", agent_name)
+      else:
+        # it's the case the module imported by {agent_name}.agent module is not
+        # found
+        e.msg = f"Fail to load '{agent_name}' module. " + e.msg
+        raise e
+    except Exception as e:
+      e.msg = f"Fail to load '{agent_name}' module. " + e.msg
+      raise e
 
     return None
 
-  def _load_from_submodule(self, agent_name: str) -> BaseAgent:
-    # Load for case: Import "<agent_name>.agent" and look for "root_agent"
-    # Covers structure: agents_dir/agent_name_folder/agent.py (where agent.py has root_agent)
+  def _load_from_submodule(self, agent_name: str) -> Optional[BaseAgent]:
+    # Load for case: Import "{agent_name}.agent" and look for "root_agent"
+    # Covers structure: agents_dir/{agent_name}/agent.py (with root_agent defined in the module)
     try:
       module_candidate = importlib.import_module(f"{agent_name}.agent")
       if hasattr(module_candidate, "root_agent"):
-        logger.debug("Found root_agent in %s.agent", agent_name)
+        logger.info("Found root_agent in %s.agent", agent_name)
         if isinstance(module_candidate.root_agent, BaseAgent):
           return module_candidate.root_agent
         else:
@@ -86,12 +95,23 @@ class AgentLoader:
               "Root agent found is not an instance of BaseAgent. But a type %s",
               type(module_candidate.root_agent),
           )
-    except ModuleNotFoundError:
-      logger.debug(
-          "Module %s.agent not found, trying next pattern.", agent_name
-      )
-    except ImportError as e:
-      logger.warning("Error importing %s.agent: %s", agent_name, e)
+      else:
+        logger.debug(
+            "Module %s.agent has no root_agent.",
+            agent_name,
+        )
+    except ModuleNotFoundError as e:
+      # if it's agent module not found, it's fine, search for next pattern
+      if e.name == f"{agent_name}.agent" or e.name == agent_name:
+        logger.debug("Module %s.agent not found.", agent_name)
+      else:
+        # it's the case the module imported by {agent_name}.agent module is not
+        # found
+        e.msg = f"Fail to load '{agent_name}.agent' module. " + e.msg
+        raise e
+    except Exception as e:
+      e.msg = f"Fail to load '{agent_name}.agent' module. " + e.msg
+      raise e
 
     return None
 
@@ -106,32 +126,28 @@ class AgentLoader:
     )
     envs.load_dotenv_for_agent(agent_name, str(self.agents_dir))
 
-    root_agent = self._load_from_module_or_package(agent_name)
-    if root_agent:
+    if root_agent := self._load_from_module_or_package(agent_name):
       return root_agent
 
-    root_agent = self._load_from_submodule(agent_name)
-    if root_agent:
+    if root_agent := self._load_from_submodule(agent_name):
       return root_agent
 
     # If no root_agent was found by any pattern
     raise ValueError(
         f"No root_agent found for '{agent_name}'. Searched in"
-        f" '{agent_name}.agent.root_agent', '{agent_name}.root_agent', and"
-        f" via an 'agent' attribute within the '{agent_name}' module/package."
+        f" '{agent_name}.agent.root_agent', '{agent_name}.root_agent'."
         f" Ensure '{self.agents_dir}/{agent_name}' is structured correctly,"
         " an .env file can be loaded if present, and a root_agent is"
         " exposed."
     )
 
   def load_agent(self, agent_name: str) -> BaseAgent:
-    """Load an agent module (with caching & .env) and return its root_agent (asynchronously)."""
+    """Load an agent module (with caching & .env) and return its root_agent."""
     if agent_name in self._agent_cache:
       logger.debug("Returning cached agent for %s (async)", agent_name)
       return self._agent_cache[agent_name]
 
     logger.debug("Loading agent %s - not in cache.", agent_name)
-    # Assumes this method is called when the context manager (`with self:`) is active
     agent = self._perform_load(agent_name)
     self._agent_cache[agent_name] = agent
     return agent

google/adk/cli/utils/envs.py

@@ -35,7 +35,7 @@ def _walk_to_root_until_found(folder, filename) -> str:
 def load_dotenv_for_agent(
     agent_name: str, agent_parent_folder: str, filename: str = '.env'
 ):
-  """Lods the .env file for the agent module."""
+  """Loads the .env file for the agent module."""
 
   # Gets the folder of agent_module as starting_folder
   starting_folder = os.path.abspath(

google/adk/code_executors/unsafe_local_code_executor.py

@@ -12,8 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from contextlib import redirect_stdout
 import io
+import re
+from typing import Any
 
 from pydantic import Field
 from typing_extensions import override
@@ -24,6 +28,12 @@ from .code_execution_utils import CodeExecutionInput
 from .code_execution_utils import CodeExecutionResult
 
 
+def _prepare_globals(code: str, globals_: dict[str, Any]) -> None:
+  """Prepare globals for code execution, injecting __name__ if needed."""
+  if re.search(r"if\s+__name__\s*==\s*['\"]__main__['\"]", code):
+    globals_['__name__'] = '__main__'
+
+
 class UnsafeLocalCodeExecutor(BaseCodeExecutor):
   """A code executor that unsafely execute code in the current local context."""
 
@@ -55,6 +65,7 @@ class UnsafeLocalCodeExecutor(BaseCodeExecutor):
     error = ''
     try:
       globals_ = {}
+      _prepare_globals(code_execution_input.code, globals_)
       locals_ = {}
       stdout = io.StringIO()
       with redirect_stdout(stdout):

google/adk/errors/__init__.py

@@ -0,0 +1,13 @@
+# 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.

google/adk/errors/not_found_error.py

@@ -0,0 +1,28 @@
+# 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
+
+
+class NotFoundError(Exception):
+  """Represents an error that occurs when an entity is not found."""
+
+  def __init__(self, message="The requested item was not found."):
+    """Initializes the NotFoundError exception.
+
+    Args:
+        message (str): An optional custom message to describe the error.
+    """
+    self.message = message
+    super().__init__(self.message)

google/adk/evaluation/agent_evaluator.py

@@ -158,7 +158,7 @@ class AgentEvaluator:
       agent_module: The path to python module that contains the definition of
         the agent. There is convention in place here, where the code is going to
         look for 'root_agent' in the loaded module.
-      eval_dataset: The eval data set. This can be either a string representing
+      eval_dataset_file_path_or_dir: The eval data set. This can be either a string representing
         full path to the file containing eval dataset, or a directory that is
         recursively explored for all files that have a `.test.json` suffix.
       num_runs: Number of times all entries in the eval dataset should be

google/adk/evaluation/eval_sets_manager.py

@@ -12,9 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from abc import ABC
 from abc import abstractmethod
+from typing import Optional
 
+from ..errors.not_found_error import NotFoundError
 from .eval_case import EvalCase
 from .eval_set import EvalSet
 
@@ -23,21 +27,47 @@ class EvalSetsManager(ABC):
   """An interface to manage an Eval Sets."""
 
   @abstractmethod
-  def get_eval_set(self, app_name: str, eval_set_id: str) -> EvalSet:
+  def get_eval_set(self, app_name: str, eval_set_id: str) -> Optional[EvalSet]:
     """Returns an EvalSet identified by an app_name and eval_set_id."""
-    raise NotImplementedError()
 
   @abstractmethod
   def create_eval_set(self, app_name: str, eval_set_id: str):
     """Creates an empty EvalSet given the app_name and eval_set_id."""
-    raise NotImplementedError()
 
   @abstractmethod
   def list_eval_sets(self, app_name: str) -> list[str]:
     """Returns a list of EvalSets that belong to the given app_name."""
-    raise NotImplementedError()
+
+  @abstractmethod
+  def get_eval_case(
+      self, app_name: str, eval_set_id: str, eval_case_id: str
+  ) -> Optional[EvalCase]:
+    """Returns an EvalCase if found, otherwise None."""
 
   @abstractmethod
   def add_eval_case(self, app_name: str, eval_set_id: str, eval_case: EvalCase):
-    """Adds the given EvalCase to an existing EvalSet identified by app_name and eval_set_id."""
-    raise NotImplementedError()
+    """Adds the given EvalCase to an existing EvalSet identified by app_name and eval_set_id.
+
+    Raises:
+      NotFoundError: If the eval set is not found.
+    """
+
+  @abstractmethod
+  def update_eval_case(
+      self, app_name: str, eval_set_id: str, updated_eval_case: EvalCase
+  ):
+    """Updates an existing EvalCase give the app_name and eval_set_id.
+
+    Raises:
+      NotFoundError: If the eval set or the eval case is not found.
+    """
+
+  @abstractmethod
+  def delete_eval_case(
+      self, app_name: str, eval_set_id: str, eval_case_id: str
+  ):
+    """Deletes the given EvalCase identified by app_name, eval_set_id and eval_case_id.
+
+    Raises:
+      NotFoundError: If the eval set or the eval case to delete is not found.
+    """

google/adk/evaluation/evaluation_generator.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import importlib
 from typing import Any
 from typing import Optional
@@ -56,7 +58,7 @@ class EvaluationGenerator:
     """Returns evaluation responses for the given dataset and agent.
 
     Args:
-      eval_dataset: The dataset that needs to be scraped for responses.
+      eval_set: The eval set that needs to be scraped for responses.
       agent_module_path: Path to the module that contains the root agent.
       repeat_num: Number of time the eval dataset should be repeated. This is
         usually done to remove uncertainty that a single run may bring.
@@ -209,7 +211,8 @@ class EvaluationGenerator:
     """Process the queries using the existing session data without invoking the runner."""
     responses = data.copy()
 
-    # Iterate through the provided queries and align them with the session events
+    # Iterate through the provided queries and align them with the session
+    # events
     for index, eval_entry in enumerate(responses):
       query = eval_entry["query"]
       actual_tool_uses = []
@@ -241,5 +244,3 @@ class EvaluationGenerator:
       responses[index]["actual_tool_use"] = actual_tool_uses
       responses[index]["response"] = response
     return responses
-    return responses
-    return responses

google/adk/evaluation/local_eval_sets_manager.py

@@ -12,18 +12,22 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import json
 import logging
 import os
 import re
 import time
 from typing import Any
+from typing import Optional
 import uuid
 
 from google.genai import types as genai_types
 from pydantic import ValidationError
 from typing_extensions import override
 
+from ..errors.not_found_error import NotFoundError
 from .eval_case import EvalCase
 from .eval_case import IntermediateData
 from .eval_case import Invocation
@@ -39,9 +43,9 @@ _EVAL_SET_FILE_EXTENSION = ".evalset.json"
 def _convert_invocation_to_pydantic_schema(
     invocation_in_json_format: dict[str, Any],
 ) -> Invocation:
-  """Converts an invocation from old json format to new Pydantic Schema"""
+  """Converts an invocation from old json format to new Pydantic Schema."""
   query = invocation_in_json_format["query"]
-  reference = invocation_in_json_format["reference"]
+  reference = invocation_in_json_format.get("reference", "")
   expected_tool_use = []
   expected_intermediate_agent_responses = []
 
@@ -186,11 +190,14 @@ class LocalEvalSetsManager(EvalSetsManager):
     self._agents_dir = agents_dir
 
   @override
-  def get_eval_set(self, app_name: str, eval_set_id: str) -> EvalSet:
+  def get_eval_set(self, app_name: str, eval_set_id: str) -> Optional[EvalSet]:
     """Returns an EvalSet identified by an app_name and eval_set_id."""
     # Load the eval set file data
-    eval_set_file_path = self._get_eval_set_file_path(app_name, eval_set_id)
-    return load_eval_set_from_file(eval_set_file_path, eval_set_id)
+    try:
+      eval_set_file_path = self._get_eval_set_file_path(app_name, eval_set_id)
+      return load_eval_set_from_file(eval_set_file_path, eval_set_id)
+    except FileNotFoundError:
+      return None
 
   @override
   def create_eval_set(self, app_name: str, eval_set_id: str):
@@ -228,12 +235,19 @@ class LocalEvalSetsManager(EvalSetsManager):
 
   @override
   def add_eval_case(self, app_name: str, eval_set_id: str, eval_case: EvalCase):
-    """Adds the given EvalCase to an existing EvalSet identified by app_name and eval_set_id."""
+    """Adds the given EvalCase to an existing EvalSet identified by app_name and eval_set_id.
+
+    Raises:
+      NotFoundError: If the eval set is not found.
+    """
     eval_case_id = eval_case.eval_id
     self._validate_id(id_name="Eval Case Id", id_value=eval_case_id)
 
     eval_set = self.get_eval_set(app_name, eval_set_id)
 
+    if not eval_set:
+      raise NotFoundError(f"Eval set `{eval_set_id}` not found.")
+
     if [x for x in eval_set.eval_cases if x.eval_id == eval_case_id]:
       raise ValueError(
           f"Eval id `{eval_case_id}` already exists in `{eval_set_id}`"
@@ -245,6 +259,87 @@ class LocalEvalSetsManager(EvalSetsManager):
     eval_set_file_path = self._get_eval_set_file_path(app_name, eval_set_id)
     self._write_eval_set(eval_set_file_path, eval_set)
 
+  @override
+  def get_eval_case(
+      self, app_name: str, eval_set_id: str, eval_case_id: str
+  ) -> Optional[EvalCase]:
+    """Returns an EvalCase if found, otherwise None."""
+    eval_set = self.get_eval_set(app_name, eval_set_id)
+
+    if not eval_set:
+      return None
+
+    eval_case_to_find = None
+
+    # Look up the eval case by eval_case_id
+    for eval_case in eval_set.eval_cases:
+      if eval_case.eval_id == eval_case_id:
+        eval_case_to_find = eval_case
+        break
+
+    return eval_case_to_find
+
+  @override
+  def update_eval_case(
+      self, app_name: str, eval_set_id: str, updated_eval_case: EvalCase
+  ):
+    """Updates an existing EvalCase give the app_name and eval_set_id.
+
+    Raises:
+      NotFoundError: If the eval set or the eval case is not found.
+    """
+    eval_case_id = updated_eval_case.eval_id
+
+    # Find the eval case to be updated.
+    eval_case_to_update = self.get_eval_case(
+        app_name, eval_set_id, eval_case_id
+    )
+
+    if eval_case_to_update:
+      # Remove the eval case from the existing eval set.
+      eval_set = self.get_eval_set(app_name, eval_set_id)
+      eval_set.eval_cases.remove(eval_case_to_update)
+
+      # Add the updated eval case to the existing eval set.
+      eval_set.eval_cases.append(updated_eval_case)
+
+      # Persit the eval set.
+      eval_set_file_path = self._get_eval_set_file_path(app_name, eval_set_id)
+      self._write_eval_set(eval_set_file_path, eval_set)
+    else:
+      raise NotFoundError(
+          f"Eval Set `{eval_set_id}` or Eval id `{eval_case_id}` not found.",
+      )
+
+  @override
+  def delete_eval_case(
+      self, app_name: str, eval_set_id: str, eval_case_id: str
+  ):
+    """Deletes the given EvalCase identified by app_name, eval_set_id and eval_case_id.
+
+    Raises:
+      NotFoundError: If the eval set or the eval case to delete is not found.
+    """
+    # Find the eval case that needs to be deleted.
+    eval_case_to_remove = self.get_eval_case(
+        app_name, eval_set_id, eval_case_id
+    )
+
+    if eval_case_to_remove:
+      logger.info(
+          "EvalCase`%s` was found in the eval set. It will be removed"
+          " permanently.",
+          eval_case_id,
+      )
+      eval_set = self.get_eval_set(app_name, eval_set_id)
+      eval_set.eval_cases.remove(eval_case_to_remove)
+      eval_set_file_path = self._get_eval_set_file_path(app_name, eval_set_id)
+      self._write_eval_set(eval_set_file_path, eval_set)
+    else:
+      raise NotFoundError(
+          f"Eval Set `{eval_set_id}` or Eval id `{eval_case_id}` not found.",
+      )
+
   def _get_eval_set_file_path(self, app_name: str, eval_set_id: str) -> str:
     return os.path.join(
         self._agents_dir,

google/adk/flows/llm_flows/agent_transfer.py

@@ -98,11 +98,11 @@ question to that agent. When transferring, do not generate any text other than
 the function call.
 """
 
-  if agent.parent_agent:
+  if agent.parent_agent and not agent.disallow_transfer_to_parent:
     si += f"""
 Your parent agent is {agent.parent_agent.name}. If neither the other agents nor
 you are best for answering the question according to the descriptions, transfer
-to your parent agent. If you don't have parent agent, try answer by yourself.
+to your parent agent.
 """
   return si
 

google/adk/flows/llm_flows/base_llm_flow.py

@@ -23,6 +23,7 @@ from typing import cast
 from typing import Optional
 from typing import TYPE_CHECKING
 
+from google.genai import types
 from websockets.exceptions import ConnectionClosedOK
 
 from . import functions
@@ -50,6 +51,8 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger('google_adk.' + __name__)
 
+_ADK_AGENT_NAME_LABEL_KEY = 'adk_agent_name'
+
 
 class BaseLlmFlow(ABC):
   """A basic flow that calls the LLM in a loop until a final response is generated.
@@ -281,6 +284,12 @@ class BaseLlmFlow(ABC):
         yield event
       if not last_event or last_event.is_final_response():
         break
+      if last_event.partial:
+        # TODO: handle this in BaseLlm level.
+        raise ValueError(
+            f"Last event shouldn't be partial. LLM max output limit may be"
+            f' reached.'
+        )
 
   async def _run_one_step_async(
       self,
@@ -493,6 +502,16 @@ class BaseLlmFlow(ABC):
       yield response
       return
 
+    llm_request.config = llm_request.config or types.GenerateContentConfig()
+    llm_request.config.labels = llm_request.config.labels or {}
+
+    # Add agent name as a label to the llm_request. This will help with slicing
+    # the billing reports on a per-agent basis.
+    if _ADK_AGENT_NAME_LABEL_KEY not in llm_request.config.labels:
+      llm_request.config.labels[_ADK_AGENT_NAME_LABEL_KEY] = (
+          invocation_context.agent.name
+      )
+
     # Calls the LLM.
     llm = self.__get_llm(invocation_context)
     with tracer.start_as_current_span('call_llm'):

google/adk/flows/llm_flows/contents.py

@@ -170,10 +170,10 @@ def _rearrange_events_for_latest_function_response(
   for idx in range(function_call_event_idx + 1, len(events) - 1):
     event = events[idx]
     function_responses = event.get_function_responses()
-    if (
-        function_responses
-        and function_responses[0].id in function_responses_ids
-    ):
+    if function_responses and any([
+        function_response.id in function_responses_ids
+        for function_response in function_responses
+    ]):
       function_response_events.append(event)
   function_response_events.append(events[-1])