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

google/adk/cli/fast_api.py

@@ -65,10 +65,13 @@ from ..evaluation.eval_metrics import EvalMetric
 from ..evaluation.eval_metrics import EvalMetricResult
 from ..evaluation.eval_metrics import EvalMetricResultPerInvocation
 from ..evaluation.eval_result import EvalSetResult
+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 ..evaluation.local_eval_sets_manager import LocalEvalSetsManager
 from ..events.event import Event
 from ..memory.in_memory_memory_service import InMemoryMemoryService
+from ..memory.vertex_ai_memory_bank_service import VertexAiMemoryBankService
 from ..memory.vertex_ai_rag_memory_service import VertexAiRagMemoryService
 from ..runners import Runner
 from ..sessions.database_session_service import DatabaseSessionService
@@ -198,6 +201,7 @@ def get_fast_api_app(
     session_service_uri: Optional[str] = None,
     artifact_service_uri: Optional[str] = None,
     memory_service_uri: Optional[str] = None,
+    eval_storage_uri: Optional[str] = None,
     allow_origins: Optional[list[str]] = None,
     web: bool,
     trace_to_cloud: bool = False,
@@ -256,8 +260,18 @@ def get_fast_api_app(
 
   runner_dict = {}
 
-  eval_sets_manager = LocalEvalSetsManager(agents_dir=agents_dir)
-  eval_set_results_manager = LocalEvalSetResultsManager(agents_dir=agents_dir)
+  # Set up eval managers.
+  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
+    )
+    eval_sets_manager = gcs_eval_managers.eval_sets_manager
+    eval_set_results_manager = gcs_eval_managers.eval_set_results_manager
+  else:
+    eval_sets_manager = LocalEvalSetsManager(agents_dir=agents_dir)
+    eval_set_results_manager = LocalEvalSetResultsManager(agents_dir=agents_dir)
 
   # Build the Memory service
   if memory_service_uri:
@@ -269,6 +283,16 @@ def get_fast_api_app(
       memory_service = VertexAiRagMemoryService(
           rag_corpus=f'projects/{os.environ["GOOGLE_CLOUD_PROJECT"]}/locations/{os.environ["GOOGLE_CLOUD_LOCATION"]}/ragCorpora/{rag_corpus}'
       )
+    elif memory_service_uri.startswith("agentengine://"):
+      agent_engine_id = memory_service_uri.split("://")[1]
+      if not agent_engine_id:
+        raise click.ClickException("Agent engine id can not be empty.")
+      envs.load_dotenv_for_agent("", agents_dir)
+      memory_service = VertexAiMemoryBankService(
+          project=os.environ["GOOGLE_CLOUD_PROJECT"],
+          location=os.environ["GOOGLE_CLOUD_LOCATION"],
+          agent_engine_id=agent_engine_id,
+      )
     else:
       raise click.ClickException(
           "Unsupported memory service URI: %s" % memory_service_uri

google/adk/cli/utils/evals.py

@@ -14,17 +14,36 @@
 
 from __future__ import annotations
 
+import dataclasses
+import os
 from typing import Any
 from typing import Tuple
 
 from google.genai import types as genai_types
+from pydantic import alias_generators
+from pydantic import BaseModel
+from pydantic import ConfigDict
 from typing_extensions import deprecated
 
 from ...evaluation.eval_case import IntermediateData
 from ...evaluation.eval_case import Invocation
+from ...evaluation.gcs_eval_set_results_manager import GcsEvalSetResultsManager
+from ...evaluation.gcs_eval_sets_manager import GcsEvalSetsManager
 from ...sessions.session import Session
 
 
+class GcsEvalManagers(BaseModel):
+  model_config = ConfigDict(
+      alias_generator=alias_generators.to_camel,
+      populate_by_name=True,
+      arbitrary_types_allowed=True,
+  )
+
+  eval_sets_manager: GcsEvalSetsManager
+
+  eval_set_results_manager: GcsEvalSetResultsManager
+
+
 @deprecated('Use convert_session_to_eval_invocations instead.')
 def convert_session_to_eval_format(session: Session) -> list[dict[str, Any]]:
   """Converts a session data into eval format.
@@ -176,3 +195,37 @@ def convert_session_to_eval_invocations(session: Session) -> list[Invocation]:
       )
 
   return invocations
+
+
+def create_gcs_eval_managers_from_uri(
+    eval_storage_uri: str,
+) -> GcsEvalManagers:
+  """Creates GcsEvalManagers from eval_storage_uri.
+
+  Args:
+      eval_storage_uri: The evals storage URI to use. Supported URIs:
+        gs://<bucket name>. If a path is provided, the bucket will be extracted.
+
+  Returns:
+      GcsEvalManagers: The GcsEvalManagers object.
+
+  Raises:
+      ValueError: If the eval_storage_uri is not supported.
+  """
+  if eval_storage_uri.startswith('gs://'):
+    gcs_bucket = eval_storage_uri.split('://')[1]
+    eval_sets_manager = GcsEvalSetsManager(
+        bucket_name=gcs_bucket, project=os.environ['GOOGLE_CLOUD_PROJECT']
+    )
+    eval_set_results_manager = GcsEvalSetResultsManager(
+        bucket_name=gcs_bucket, project=os.environ['GOOGLE_CLOUD_PROJECT']
+    )
+    return GcsEvalManagers(
+        eval_sets_manager=eval_sets_manager,
+        eval_set_results_manager=eval_set_results_manager,
+    )
+  else:
+    raise ValueError(
+        f'Unsupported evals storage URI: {eval_storage_uri}. Supported URIs:'
+        ' gs://<bucket name>'
+    )

google/adk/evaluation/final_response_match_v1.py

@@ -0,0 +1,110 @@
+# 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 google.genai import types as genai_types
+from rouge_score import rouge_scorer
+from typing_extensions import override
+
+from .eval_case import Invocation
+from .eval_metrics import EvalMetric
+from .evaluator import EvalStatus
+from .evaluator import EvaluationResult
+from .evaluator import Evaluator
+from .evaluator import PerInvocationResult
+
+
+class RougeEvaluator(Evaluator):
+  """Calculates the ROUGE-1 metric to compare responses."""
+
+  def __init__(self, eval_metric: EvalMetric):
+    self._eval_metric = eval_metric
+
+  @override
+  def evaluate_invocations(
+      self,
+      actual_invocations: list[Invocation],
+      expected_invocations: list[Invocation],
+  ) -> EvaluationResult:
+    total_score = 0.0
+    num_invocations = 0
+    per_invocation_results = []
+    for actual, expected in zip(actual_invocations, expected_invocations):
+      reference = _get_text_from_content(expected.final_response)
+      response = _get_text_from_content(actual.final_response)
+      rouge_1_scores = _calculate_rouge_1_scores(response, reference)
+      score = rouge_1_scores.fmeasure
+      per_invocation_results.append(
+          PerInvocationResult(
+              actual_invocation=actual,
+              expected_invocation=expected,
+              score=score,
+              eval_status=_get_eval_status(score, self._eval_metric.threshold),
+          )
+      )
+      total_score += score
+      num_invocations += 1
+
+    if per_invocation_results:
+      overall_score = total_score / num_invocations
+      return EvaluationResult(
+          overall_score=overall_score,
+          overall_eval_status=_get_eval_status(
+              overall_score, self._eval_metric.threshold
+          ),
+          per_invocation_results=per_invocation_results,
+      )
+
+    return EvaluationResult()
+
+
+def _get_text_from_content(content: Optional[genai_types.Content]) -> str:
+  if content and content.parts:
+    return "\n".join([part.text for part in content.parts if part.text])
+
+  return ""
+
+
+def _get_eval_status(score: float, threshold: float):
+  return EvalStatus.PASSED if score >= threshold else EvalStatus.FAILED
+
+
+def _calculate_rouge_1_scores(candidate: str, reference: str):
+  """Calculates the ROUGE-1 score between a candidate and reference text.
+
+  ROUGE-1 measures the overlap of unigrams (single words) between the
+  candidate and reference texts. The score is broken down into:
+  - Precision: The proportion of unigrams in the candidate that are also in the
+  reference.
+  - Recall: The proportion of unigrams in the reference that are also in the
+  candidate.
+  - F-measure: The harmonic mean of precision and recall.
+
+  Args:
+      candidate: The generated text to be evaluated.
+      reference: The ground-truth text to compare against.
+
+  Returns:
+      A dictionary containing the ROUGE-1 precision, recall, and f-measure.
+  """
+  scorer = rouge_scorer.RougeScorer(["rouge1"], use_stemmer=True)
+
+  # The score method returns a dictionary where keys are the ROUGE types
+  # and values are Score objects (tuples) with precision, recall, and fmeasure.
+  scores = scorer.score(reference, candidate)
+
+  return scores["rouge1"]

google/adk/evaluation/gcs_eval_sets_manager.py

@@ -72,6 +72,13 @@ class GcsEvalSetsManager(EvalSetsManager):
           f"Invalid {id_name}. {id_name} should have the `{pattern}` format",
       )
 
+  def _load_eval_set_from_blob(self, blob_name: str) -> Optional[EvalSet]:
+    blob = self.bucket.blob(blob_name)
+    if not blob.exists():
+      return None
+    eval_set_data = blob.download_as_text()
+    return EvalSet.model_validate_json(eval_set_data)
+
   def _write_eval_set_to_blob(self, blob_name: str, eval_set: EvalSet):
     """Writes an EvalSet to GCS."""
     blob = self.bucket.blob(blob_name)
@@ -88,11 +95,7 @@ class GcsEvalSetsManager(EvalSetsManager):
   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."""
     eval_set_blob_name = self._get_eval_set_blob_name(app_name, eval_set_id)
-    blob = self.bucket.blob(eval_set_blob_name)
-    if not blob.exists():
-      return None
-    eval_set_data = blob.download_as_text()
-    return EvalSet.model_validate_json(eval_set_data)
+    return self._load_eval_set_from_blob(eval_set_blob_name)
 
   @override
   def create_eval_set(self, app_name: str, eval_set_id: str):

google/adk/evaluation/response_evaluator.py

@@ -27,10 +27,12 @@ from vertexai.preview.evaluation import MetricPromptTemplateExamples
 
 from .eval_case import IntermediateData
 from .eval_case import Invocation
+from .eval_metrics import EvalMetric
 from .evaluator import EvalStatus
 from .evaluator import EvaluationResult
 from .evaluator import Evaluator
 from .evaluator import PerInvocationResult
+from .final_response_match_v1 import RougeEvaluator
 
 
 class ResponseEvaluator(Evaluator):
@@ -40,7 +42,7 @@ class ResponseEvaluator(Evaluator):
     if "response_evaluation_score" == metric_name:
       self._metric_name = MetricPromptTemplateExamples.Pointwise.COHERENCE
     elif "response_match_score" == metric_name:
-      self._metric_name = "rouge_1"
+      self._metric_name = "response_match_score"
     else:
       raise ValueError(f"`{metric_name}` is not supported.")
 
@@ -52,6 +54,15 @@ class ResponseEvaluator(Evaluator):
       actual_invocations: list[Invocation],
       expected_invocations: list[Invocation],
   ) -> EvaluationResult:
+    # If the metric is response_match_score, just use the RougeEvaluator.
+    if self._metric_name == "response_match_score":
+      rouge_evaluator = RougeEvaluator(
+          EvalMetric(metric_name=self._metric_name, threshold=self._threshold)
+      )
+      return rouge_evaluator.evaluate_invocations(
+          actual_invocations, expected_invocations
+      )
+
     total_score = 0.0
     num_invocations = 0
     per_invocation_results = []

google/adk/events/event.py

@@ -34,9 +34,10 @@ class Event(LlmResponse):
   taken by the agents like function calls, etc.
 
   Attributes:
-    invocation_id: The invocation ID of the event.
-    author: "user" or the name of the agent, indicating who appended the event
-      to the session.
+    invocation_id: Required. The invocation ID of the event. Should be non-empty
+      before appending to a session.
+    author: Required. "user" or the name of the agent, indicating who appended
+      the event to the session.
     actions: The actions taken by the agent.
     long_running_tool_ids: The ids of the long running function calls.
     branch: The branch of the event.
@@ -55,9 +56,8 @@ class Event(LlmResponse):
   )
   """The pydantic model config."""
 
-  # TODO: revert to be required after spark migration
   invocation_id: str = ''
-  """The invocation ID of the event."""
+  """The invocation ID of the event. Should be non-empty before appending to a session."""
   author: str
   """'user' or the name of the agent, indicating who appended the event to the
   session."""

google/adk/flows/llm_flows/contents.py

@@ -43,12 +43,20 @@ class _ContentLlmRequestProcessor(BaseLlmRequestProcessor):
     if not isinstance(agent, LlmAgent):
       return
 
-    if agent.include_contents != 'none':
+    if agent.include_contents == 'default':
+      # Include full conversation history
       llm_request.contents = _get_contents(
           invocation_context.branch,
           invocation_context.session.events,
           agent.name,
       )
+    else:
+      # Include current turn context only (no conversation history)
+      llm_request.contents = _get_current_turn_contents(
+          invocation_context.branch,
+          invocation_context.session.events,
+          agent.name,
+      )
 
     # Maintain async generator behavior
     if False:  # Ensures it behaves as a generator
@@ -190,13 +198,15 @@ def _get_contents(
 ) -> list[types.Content]:
   """Get the contents for the LLM request.
 
+  Applies filtering, rearrangement, and content processing to events.
+
   Args:
     current_branch: The current branch of the agent.
-    events: A list of events.
+    events: Events to process.
     agent_name: The name of the agent.
 
   Returns:
-    A list of contents.
+    A list of processed contents.
   """
   filtered_events = []
   # Parse the events, leaving the contents and the function calls and
@@ -211,12 +221,13 @@ def _get_contents(
       # Skip events without content, or generated neither by user nor by model
       # or has empty text.
       # E.g. events purely for mutating session states.
+
       continue
     if not _is_event_belongs_to_branch(current_branch, event):
       # Skip events not belong to current branch.
       continue
     if _is_auth_event(event):
-      # skip auth event
+      # Skip auth events.
       continue
     filtered_events.append(
         _convert_foreign_event(event)
@@ -224,12 +235,15 @@ def _get_contents(
         else event
     )
 
+  # Rearrange events for proper function call/response pairing
   result_events = _rearrange_events_for_latest_function_response(
       filtered_events
   )
   result_events = _rearrange_events_for_async_function_responses_in_history(
       result_events
   )
+
+  # Convert events to contents
   contents = []
   for event in result_events:
     content = copy.deepcopy(event.content)
@@ -238,6 +252,37 @@ def _get_contents(
   return contents
 
 
+def _get_current_turn_contents(
+    current_branch: Optional[str], events: list[Event], agent_name: str = ''
+) -> list[types.Content]:
+  """Get contents for the current turn only (no conversation history).
+
+  When include_contents='none', we want to include:
+  - The current user input
+  - Tool calls and responses from the current turn
+  But exclude conversation history from previous turns.
+
+  In multi-agent scenarios, the "current turn" for an agent starts from an
+  actual user or from another agent.
+
+  Args:
+    current_branch: The current branch of the agent.
+    events: A list of all session events.
+    agent_name: The name of the agent.
+
+  Returns:
+    A list of contents for the current turn only, preserving context needed
+    for proper tool execution while excluding conversation history.
+  """
+  # Find the latest event that starts the current turn and process from there
+  for i in range(len(events) - 1, -1, -1):
+    event = events[i]
+    if event.author == 'user' or _is_other_agent_reply(agent_name, event):
+      return _get_contents(current_branch, events[i:], agent_name)
+
+  return []
+
+
 def _is_other_agent_reply(current_agent_name: str, event: Event) -> bool:
   """Whether the event is a reply from another agent."""
   return bool(

google/adk/flows/llm_flows/functions.py

@@ -519,3 +519,35 @@ def merge_parallel_function_response_events(
   # Use the base_event as the timestamp
   merged_event.timestamp = base_event.timestamp
   return merged_event
+
+
+def find_matching_function_call(
+    events: list[Event],
+) -> Optional[Event]:
+  """Finds the function call event that matches the function response id of the last event."""
+  if not events:
+    return None
+
+  last_event = events[-1]
+  if (
+      last_event.content
+      and last_event.content.parts
+      and any(part.function_response for part in last_event.content.parts)
+  ):
+
+    function_call_id = next(
+        part.function_response.id
+        for part in last_event.content.parts
+        if part.function_response
+    )
+    for i in range(len(events) - 2, -1, -1):
+      event = events[i]
+      # looking for the system long running request euc function call
+      function_calls = event.get_function_calls()
+      if not function_calls:
+        continue
+
+      for function_call in function_calls:
+        if function_call.id == function_call_id:
+          return event
+  return None

google/adk/memory/__init__.py

@@ -15,12 +15,14 @@ import logging
 
 from .base_memory_service import BaseMemoryService
 from .in_memory_memory_service import InMemoryMemoryService
+from .vertex_ai_memory_bank_service import VertexAiMemoryBankService
 
 logger = logging.getLogger('google_adk.' + __name__)
 
 __all__ = [
     'BaseMemoryService',
     'InMemoryMemoryService',
+    'VertexAiMemoryBankService',
 ]
 
 try:
@@ -29,7 +31,7 @@ try:
   __all__.append('VertexAiRagMemoryService')
 except ImportError:
   logger.debug(
-      'The Vertex sdk is not installed. If you want to use the'
+      'The Vertex SDK is not installed. If you want to use the'
       ' VertexAiRagMemoryService please install it. If not, you can ignore this'
       ' warning.'
   )

google/adk/memory/vertex_ai_memory_bank_service.py

@@ -0,0 +1,150 @@
+# 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 json
+import logging
+from typing import Optional
+from typing import TYPE_CHECKING
+
+from typing_extensions import override
+
+from google import genai
+
+from .base_memory_service import BaseMemoryService
+from .base_memory_service import SearchMemoryResponse
+from .memory_entry import MemoryEntry
+
+if TYPE_CHECKING:
+  from ..sessions.session import Session
+
+logger = logging.getLogger('google_adk.' + __name__)
+
+
+class VertexAiMemoryBankService(BaseMemoryService):
+  """Implementation of the BaseMemoryService using Vertex AI Memory Bank."""
+
+  def __init__(
+      self,
+      project: Optional[str] = None,
+      location: Optional[str] = None,
+      agent_engine_id: Optional[str] = None,
+  ):
+    """Initializes a VertexAiMemoryBankService.
+
+    Args:
+      project: The project ID of the Memory Bank to use.
+      location: The location of the Memory Bank to use.
+      agent_engine_id: The ID of the agent engine to use for the Memory Bank.
+        e.g. '456' in
+        'projects/my-project/locations/us-central1/reasoningEngines/456'.
+    """
+    self._project = project
+    self._location = location
+    self._agent_engine_id = agent_engine_id
+
+  @override
+  async def add_session_to_memory(self, session: Session):
+    api_client = self._get_api_client()
+
+    if not self._agent_engine_id:
+      raise ValueError('Agent Engine ID is required for Memory Bank.')
+
+    events = []
+    for event in session.events:
+      if event.content and event.content.parts:
+        events.append({
+            'content': event.content.model_dump(exclude_none=True, mode='json')
+        })
+    request_dict = {
+        'direct_contents_source': {
+            'events': events,
+        },
+        'scope': {
+            'app_name': session.app_name,
+            'user_id': session.user_id,
+        },
+    }
+
+    if events:
+      api_response = await api_client.async_request(
+          http_method='POST',
+          path=f'reasoningEngines/{self._agent_engine_id}/memories:generate',
+          request_dict=request_dict,
+      )
+      logger.info(f'Generate memory response: {api_response}')
+    else:
+      logger.info('No events to add to memory.')
+
+  @override
+  async def search_memory(self, *, app_name: str, user_id: str, query: str):
+    api_client = self._get_api_client()
+
+    api_response = await api_client.async_request(
+        http_method='POST',
+        path=f'reasoningEngines/{self._agent_engine_id}/memories:retrieve',
+        request_dict={
+            'scope': {
+                'app_name': app_name,
+                'user_id': user_id,
+            },
+            'similarity_search_params': {
+                'search_query': query,
+            },
+        },
+    )
+    api_response = _convert_api_response(api_response)
+    logger.info(f'Search memory response: {api_response}')
+
+    if not api_response or not api_response.get('retrievedMemories', None):
+      return SearchMemoryResponse()
+
+    memory_events = []
+    for memory in api_response.get('retrievedMemories', []):
+      # TODO: add more complex error handling
+      memory_events.append(
+          MemoryEntry(
+              author='user',
+              content=genai.types.Content(
+                  parts=[
+                      genai.types.Part(text=memory.get('memory').get('fact'))
+                  ],
+                  role='user',
+              ),
+              timestamp=memory.get('updateTime'),
+          )
+      )
+    return SearchMemoryResponse(memories=memory_events)
+
+  def _get_api_client(self):
+    """Instantiates an API client for the given project and location.
+
+    It needs to be instantiated inside each request so that the event loop
+    management can be properly propagated.
+
+    Returns:
+      An API client for the given project and location.
+    """
+    client = genai.Client(
+        vertexai=True, project=self._project, location=self._location
+    )
+    return client._api_client
+
+
+def _convert_api_response(api_response):
+  """Converts the API response to a JSON object based on the type."""
+  if hasattr(api_response, 'body'):
+    return json.loads(api_response.body)
+  return api_response

google/adk/models/lite_llm.py

@@ -29,6 +29,7 @@ from typing import Tuple
 from typing import Union
 
 from google.genai import types
+import litellm
 from litellm import acompletion
 from litellm import ChatCompletionAssistantMessage
 from litellm import ChatCompletionAssistantToolCall
@@ -53,6 +54,9 @@ from .base_llm import BaseLlm
 from .llm_request import LlmRequest
 from .llm_response import LlmResponse
 
+# This will add functions to prompts if functions are provided.
+litellm.add_function_to_prompt = True
+
 logger = logging.getLogger("google_adk." + __name__)
 
 _NEW_LINE = "\n"
@@ -662,6 +666,10 @@ class LiteLlm(BaseLlm):
 
     messages, tools, response_format = _get_completion_inputs(llm_request)
 
+    if "functions" in self._additional_args:
+      # LiteLLM does not support both tools and functions together.
+      tools = None
+
     completion_args = {
         "model": self.model,
         "messages": messages,
@@ -679,7 +687,7 @@ class LiteLlm(BaseLlm):
       aggregated_llm_response_with_tool_call = None
       usage_metadata = None
       fallback_index = 0
-      for part in self.llm_client.completion(**completion_args):
+      async for part in await self.llm_client.acompletion(**completion_args):
         for chunk, finish_reason in _model_response_to_chunk(part):
           if isinstance(chunk, FunctionChunk):
             index = chunk.index or fallback_index