Merge branch 'main' into adk-runner-helper

Author: Jacksunwei

.github/copybara-pr-handler.yml renamed to .github/workflows/copybara-pr-handler.yml

@@ -38,7 +38,7 @@ dependencies = [
   "google-cloud-secret-manager>=2.22.0, <3.0.0",             # Fetching secrets in RestAPI Tool
   "google-cloud-spanner>=3.56.0, <4.0.0",                    # For Spanner database
   "google-cloud-speech>=2.30.0, <3.0.0",                     # For Audio Transcription
-  "google-cloud-storage>=2.18.0, <3.0.0",                    # For GCS Artifact service
+  "google-cloud-storage>=3.0.0, <4.0.0",                     # For GCS Artifact service
   "google-genai>=1.45.0, <2.0.0",                            # Google GenAI SDK
   "graphviz>=0.20.2, <1.0.0",                                # Graphviz for graph rendering
   "mcp>=1.8.0, <2.0.0;python_version>='3.10'",               # For MCP Toolset

pyproject.toml

@@ -689,9 +689,43 @@ def __get_agent_to_run(self, agent_name: str) -> BaseAgent:
     """Find the agent to run under the root agent by name."""
     agent_to_run = self.root_agent.find_agent(agent_name)
     if not agent_to_run:
-      raise ValueError(f'Agent {agent_name} not found in the agent tree.')
+      available = self._get_available_agent_names()
+      error_msg = (
+          f"Agent '{agent_name}' not found.\n"
+          f"Available agents: {', '.join(available)}\n\n"
+          'Possible causes:\n'
+          '  1. Agent not registered before being referenced\n'
+          '  2. Agent name mismatch (typo or case sensitivity)\n'
+          '  3. Timing issue (agent referenced before creation)\n\n'
+          'Suggested fixes:\n'
+          '  - Verify agent is registered with root agent\n'
+          '  - Check agent name spelling and case\n'
+          '  - Ensure agents are created before being referenced'
+      )
+      raise ValueError(error_msg)
     return agent_to_run
 
+  def _get_available_agent_names(self) -> list[str]:
+    """Helper to get all agent names in the tree for error reporting.
+
+    This is a private helper method used only for error message formatting.
+    Traverses the agent tree starting from root_agent and collects all
+    agent names for display in error messages.
+
+    Returns:
+      List of all agent names in the agent tree.
+    """
+    agents = []
+
+    def collect_agents(agent):
+      agents.append(agent.name)
+      if hasattr(agent, 'sub_agents') and agent.sub_agents:
+        for sub_agent in agent.sub_agents:
+          collect_agents(sub_agent)
+
+    collect_agents(self.root_agent)
+    return agents
+
   def __get_transfer_to_agent_or_none(
       self, event: Event, from_agent: str
   ) -> Optional[BaseAgent]:

src/google/adk/agents/llm_agent.py

@@ -356,29 +356,33 @@ def _construct_message_parts_from_session(
     """
     message_parts: list[A2APart] = []
     context_id = None
+
+    events_to_process = []
     for event in reversed(ctx.session.events):
-      if _is_other_agent_reply(self.name, event):
-        event = _present_other_agent_message(event)
-      elif event.author == self.name:
+      if event.author == self.name:
         # stop on content generated by current a2a agent given it should already
         # be in remote session
         if event.custom_metadata:
           metadata = event.custom_metadata
           context_id = metadata.get(A2A_METADATA_PREFIX + "context_id")
         break
+      events_to_process.append(event)
+
+    for event in reversed(events_to_process):
+      if _is_other_agent_reply(self.name, event):
+        event = _present_other_agent_message(event)
 
       if not event.content or not event.content.parts:
         continue
 
       for part in event.content.parts:
-
         converted_part = self._genai_part_converter(part)
         if converted_part:
           message_parts.append(converted_part)
         else:
           logger.warning("Failed to convert part to A2A format: %s", part)
 
-    return message_parts[::-1], context_id
+    return message_parts, context_id
 
   async def _handle_a2a_response(
       self, a2a_response: A2AClientEvent | A2AMessage, ctx: InvocationContext

src/google/adk/agents/remote_a2a_agent.py

@@ -214,14 +214,16 @@ def pretty_print_eval_result(eval_result: EvalCaseResult):
     expected_invocation = per_invocation_result.expected_invocation
     row_data = {
         "prompt": _convert_content_to_text(actual_invocation.user_content),
-        "expected_response": _convert_content_to_text(
-            expected_invocation.final_response if expected_invocation else None
+        "expected_response": (
+            _convert_content_to_text(expected_invocation.final_response)
+            if expected_invocation
+            else None
         ),
         "actual_response": _convert_content_to_text(
             actual_invocation.final_response
         ),
-        "expected_tool_calls": _convert_tool_calls_to_text(
-            expected_invocation.intermediate_data
+        "expected_tool_calls": (
+            _convert_tool_calls_to_text(expected_invocation.intermediate_data)
             if expected_invocation
             else None
         ),
@@ -252,11 +254,23 @@ def pretty_print_eval_result(eval_result: EvalCaseResult):
     )
     click.echo("Invocation Details:")
     df = pd.DataFrame(data)
+
+    # Identify columns where ALL values are exactly None
+    columns_to_keep = []
     for col in df.columns:
-      if df[col].dtype == "object":
-        df[col] = df[col].str.wrap(40)
-    click.echo(tabulate(df, headers="keys", tablefmt="grid"))
-  click.echo("\n\n")  # Few empty lines for visual clarity
+      # Check if all elements in the column are NOT None
+      if not df[col].apply(lambda x: x is None).all():
+        columns_to_keep.append(col)
+
+    # Select only the columns to keep
+    df_result = df[columns_to_keep]
+
+    for col in df_result.columns:
+      if df_result[col].dtype == "object":
+        df_result[col] = df_result[col].str.wrap(40)
+
+    click.echo(tabulate(df_result, headers="keys", tablefmt="grid"))
+    click.echo("\n\n")  # Few empty lines for visual clarity
 
 
 def get_eval_sets_manager(

src/google/adk/cli/cli_eval.py

@@ -108,6 +108,10 @@ class Invocation(EvalBaseModel):
   """Details about the App that was used for this invocation."""
 
 
+SessionState: TypeAlias = dict[str, Any]
+"""The state of the session."""
+
+
 class SessionInput(EvalBaseModel):
   """Values that help initialize a Session."""
 
@@ -117,7 +121,7 @@ class SessionInput(EvalBaseModel):
   user_id: str
   """The user id."""
 
-  state: dict[str, Any] = Field(default_factory=dict)
+  state: SessionState = Field(default_factory=dict)
   """The state of the session."""
 
 
@@ -159,6 +163,9 @@ class EvalCase(EvalBaseModel):
   )
   """A list of rubrics that are applicable to all the invocations in the conversation of this eval case."""
 
+  final_session_state: Optional[SessionState] = Field(default_factory=dict)
+  """The expected final session state at the end of the conversation."""
+
   @model_validator(mode="after")
   def ensure_conversation_xor_conversation_scenario(self) -> EvalCase:
     if (self.conversation is None) == (self.conversation_scenario is None):

src/google/adk/evaluation/eval_case.py

@@ -594,7 +594,12 @@ def _is_event_belongs_to_branch(
   """
   if not invocation_branch or not event.branch:
     return True
-  return invocation_branch.startswith(event.branch)
+  # We use dot to delimit branch nodes. To avoid simple prefix match
+  # (e.g. agent_0 unexpectedly matching agent_00), require either perfect branch
+  # match, or match prefix with an additional explicit '.'
+  return invocation_branch == event.branch or invocation_branch.startswith(
+      f'{event.branch}.'
+  )
 
 
 def _is_function_call_event(event: Event, function_name: str) -> bool:

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

@@ -716,10 +716,17 @@ def _get_tool(
 ):
   """Returns the tool corresponding to the function call."""
   if function_call.name not in tools_dict:
-    raise ValueError(
-        f'Function {function_call.name} is not found in the tools_dict:'
-        f' {tools_dict.keys()}.'
+    available = list(tools_dict.keys())
+    error_msg = (
+        f"Tool '{function_call.name}' not found.\nAvailable tools:"
+        f" {', '.join(available)}\n\nPossible causes:\n  1. LLM hallucinated"
+        ' the function name - review agent instruction clarity\n  2. Tool not'
+        ' registered - verify agent.tools list\n  3. Name mismatch - check for'
+        ' typos\n\nSuggested fixes:\n  - Review agent instruction to ensure'
+        ' tool usage is clear\n  - Verify tool is included in agent.tools'
+        ' list\n  - Check for typos in function name'
     )
+    raise ValueError(error_msg)
 
   return tools_dict[function_call.name]
 

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

@@ -35,7 +35,6 @@
 from ..events.event import Event
 from ..events.event_actions import EventActions
 from ..utils.vertex_ai_utils import get_express_mode_api_key
-from ..utils.vertex_ai_utils import is_vertex_express_mode
 from .base_session_service import BaseSessionService
 from .base_session_service import GetSessionConfig
 from .base_session_service import ListSessionsResponse
@@ -115,53 +114,14 @@ async def create_session(
     config = {'session_state': state} if state else {}
     config.update(kwargs)
 
-    if is_vertex_express_mode(
-        self._project, self._location, self._express_mode_api_key
-    ):
-      config['wait_for_completion'] = False
-      api_response = await api_client.aio.agent_engines.sessions.create(
-          name=f'reasoningEngines/{reasoning_engine_id}',
-          user_id=user_id,
-          config=config,
-      )
-      logger.info('Create session response received.')
-      session_id = api_response.name.split('/')[-3]
-
-      # Express mode doesn't support LRO, so we need to poll
-      # the session resource.
-      # TODO: remove this once LRO polling is supported in Express mode.
-      @retry(
-          stop=stop_after_attempt(6),
-          wait=wait_exponential(multiplier=1, min=1, max=3),
-          retry=retry_if_result(lambda response: not response),
-          reraise=True,
-      )
-      async def _poll_session_resource():
-        try:
-          return await api_client.aio.agent_engines.sessions.get(
-              name=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}'
-          )
-        except ClientError:
-          logger.info('Polling session resource')
-          return None
-
-      try:
-        await _poll_session_resource()
-      except Exception as exc:
-        raise ValueError('Failed to create session.') from exc
-
-      get_session_response = await api_client.aio.agent_engines.sessions.get(
-          name=f'reasoningEngines/{reasoning_engine_id}/sessions/{session_id}'
-      )
-    else:
-      api_response = await api_client.aio.agent_engines.sessions.create(
-          name=f'reasoningEngines/{reasoning_engine_id}',
-          user_id=user_id,
-          config=config,
-      )
-      logger.debug('Create session response: %s', api_response)
-      get_session_response = api_response.response
-      session_id = get_session_response.name.split('/')[-1]
+    api_response = await api_client.aio.agent_engines.sessions.create(
+        name=f'reasoningEngines/{reasoning_engine_id}',
+        user_id=user_id,
+        config=config,
+    )
+    logger.debug('Create session response: %s', api_response)
+    get_session_response = api_response.response
+    session_id = get_session_response.name.split('/')[-1]
 
     session = Session(
         app_name=app_name,

src/google/adk/sessions/vertex_ai_session_service.py

@@ -26,18 +26,6 @@
 from ..utils.env_utils import is_env_enabled
 
 
-def is_vertex_express_mode(
-    project: Optional[str], location: Optional[str], api_key: Optional[str]
-) -> bool:
-  """Check if Vertex AI and API key are both enabled replacing project and location, meaning the user is using the Vertex Express Mode."""
-  return (
-      is_env_enabled('GOOGLE_GENAI_USE_VERTEXAI')
-      and api_key is not None
-      and project is None
-      and location is None
-  )
-
-
 def get_express_mode_api_key(
     project: Optional[str],
     location: Optional[str],