Merge branch 'main' into refactor/callback-pipeline

Resolved conflict in functions.py by accepting main's version.
Our branch does not modify functions.py.

Author: jaywang172

pyproject.toml

@@ -25,43 +25,43 @@ classifiers = [ # List of https://pypi.org/classifiers/
 ]
 dependencies = [
   # go/keep-sorted start
-  "PyYAML>=6.0.2, <7.0.0",                                  # For APIHubToolset.
-  "absolufy-imports>=0.3.1, <1.0.0",                        # For Agent Engine deployment.
-  "anyio>=4.9.0, <5.0.0;python_version>='3.10'",            # For MCP Session Manager
-  "authlib>=1.5.1, <2.0.0",                                 # For RestAPI Tool
-  "click>=8.1.8, <9.0.0",                                   # For CLI tools
-  "fastapi>=0.115.0, <1.0.0",                               # FastAPI framework
-  "google-api-python-client>=2.157.0, <3.0.0",              # Google API client discovery
-  "google-cloud-aiplatform[agent_engines]>=1.121.0, <2.0.0",# For VertexAI integrations, e.g. example store.
-  "google-cloud-bigtable>=2.32.0",                          # For Bigtable database
-  "google-cloud-discoveryengine>=0.13.12, <0.14.0",         # For Discovery Engine Search Tool
-  "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-genai>=1.41.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
-  "opentelemetry-api>=1.37.0, <=1.37.0",                    # OpenTelemetry - limit upper version for sdk and api to not risk breaking changes from unstable _logs package.
+  "PyYAML>=6.0.2, <7.0.0",                                   # For APIHubToolset.
+  "absolufy-imports>=0.3.1, <1.0.0",                         # For Agent Engine deployment.
+  "anyio>=4.9.0, <5.0.0;python_version>='3.10'",             # For MCP Session Manager
+  "authlib>=1.5.1, <2.0.0",                                  # For RestAPI Tool
+  "click>=8.1.8, <9.0.0",                                    # For CLI tools
+  "fastapi>=0.115.0, <1.119.0",                              # FastAPI framework
+  "google-api-python-client>=2.157.0, <3.0.0",               # Google API client discovery
+  "google-cloud-aiplatform[agent_engines]>=1.121.0, <2.0.0", # For VertexAI integrations, e.g. example store.
+  "google-cloud-bigtable>=2.32.0",                           # For Bigtable database
+  "google-cloud-discoveryengine>=0.13.12, <0.14.0",          # For Discovery Engine Search Tool
+  "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-genai>=1.41.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
+  "opentelemetry-api>=1.37.0, <=1.37.0",                     # OpenTelemetry - limit upper version for sdk and api to not risk breaking changes from unstable _logs package.
   "opentelemetry-exporter-gcp-logging>=1.9.0a0, <2.0.0",
   "opentelemetry-exporter-gcp-monitoring>=1.9.0a0, <2.0.0",
   "opentelemetry-exporter-gcp-trace>=1.9.0, <2.0.0",
   "opentelemetry-exporter-otlp-proto-http>=1.36.0",
   "opentelemetry-resourcedetector-gcp>=1.9.0a0, <2.0.0",
   "opentelemetry-sdk>=1.37.0, <=1.37.0",
-  "pydantic>=2.0, <3.0.0",                                  # For data validation/models
-  "python-dateutil>=2.9.0.post0, <3.0.0",                   # For Vertext AI Session Service
-  "python-dotenv>=1.0.0, <2.0.0",                           # To manage environment variables
+  "pydantic>=2.0, <3.0.0",                                   # For data validation/models
+  "python-dateutil>=2.9.0.post0, <3.0.0",                    # For Vertext AI Session Service
+  "python-dotenv>=1.0.0, <2.0.0",                            # To manage environment variables
   "requests>=2.32.4, <3.0.0",
-  "sqlalchemy-spanner>=1.14.0",                             # Spanner database session service
-  "sqlalchemy>=2.0, <3.0.0",                                # SQL database ORM
-  "starlette>=0.46.2, <1.0.0",                              # For FastAPI CLI
-  "tenacity>=8.0.0, <9.0.0",                                # For Retry management
+  "sqlalchemy-spanner>=1.14.0",                              # Spanner database session service
+  "sqlalchemy>=2.0, <3.0.0",                                 # SQL database ORM
+  "starlette>=0.46.2, <1.0.0",                               # For FastAPI CLI
+  "tenacity>=8.0.0, <9.0.0",                                 # For Retry management
   "typing-extensions>=4.5, <5",
-  "tzlocal>=5.3, <6.0",                                     # Time zone utilities
-  "uvicorn>=0.34.0, <1.0.0",                                # ASGI server for FastAPI
-  "watchdog>=6.0.0, <7.0.0",                                # For file change detection and hot reload
-  "websockets>=15.0.1, <16.0.0",                            # For BaseLlmFlow
+  "tzlocal>=5.3, <6.0",                                      # Time zone utilities
+  "uvicorn>=0.34.0, <1.0.0",                                 # ASGI server for FastAPI
+  "watchdog>=6.0.0, <7.0.0",                                 # For file change detection and hot reload
+  "websockets>=15.0.1, <16.0.0",                             # For BaseLlmFlow
   # go/keep-sorted end
 ]
 dynamic = ["version"]
@@ -111,13 +111,13 @@ eval = [
 test = [
   # go/keep-sorted start
   "a2a-sdk>=0.3.0,<0.4.0;python_version>='3.10'",
-  "anthropic>=0.43.0",                      # For anthropic model tests
-  "kubernetes>=29.0.0",                     # For GkeCodeExecutor
+  "anthropic>=0.43.0",                            # For anthropic model tests
+  "kubernetes>=29.0.0",                           # For GkeCodeExecutor
   "langchain-community>=0.3.17",
-  "langgraph>=0.2.60, <0.4.8",              # For LangGraphAgent
-  "litellm>=1.75.5, <2.0.0",                # For LiteLLM tests
-  "llama-index-readers-file>=0.4.0",        # For retrieval tests
-  "openai>=1.100.2",                        # For LiteLLM
+  "langgraph>=0.2.60, <0.4.8",                    # For LangGraphAgent
+  "litellm>=1.75.5, <2.0.0",                      # For LiteLLM tests
+  "llama-index-readers-file>=0.4.0",              # For retrieval tests
+  "openai>=1.100.2",                              # For LiteLLM
   "pytest>=8.3.4",
   "pytest-asyncio>=0.25.0",
   "pytest-mock>=3.14.0",
@@ -139,22 +139,20 @@ docs = [
 
 # Optional extensions
 extensions = [
-  "anthropic>=0.43.0",                         # For anthropic model support
-  "beautifulsoup4>=3.2.2",                     # For load_web_page tool.
-  "crewai[tools];python_version>='3.10'",      # For CrewaiTool
-  "docker>=7.0.0",                             # For ContainerCodeExecutor
-  "kubernetes>=29.0.0",                        # For GkeCodeExecutor
-  "langgraph>=0.2.60, <0.4.8",                 # For LangGraphAgent
-  "litellm>=1.75.5",                           # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
-  "llama-index-readers-file>=0.4.0",           # For retrieval using LlamaIndex.
-  "llama-index-embeddings-google-genai>=0.3.0",# For files retrieval using LlamaIndex.
-  "lxml>=5.3.0",                               # For load_web_page tool.
-  "toolbox-core>=0.1.0",                       # For tools.toolbox_toolset.ToolboxToolset
+  "anthropic>=0.43.0",                          # For anthropic model support
+  "beautifulsoup4>=3.2.2",                      # For load_web_page tool.
+  "crewai[tools];python_version>='3.10'",       # For CrewaiTool
+  "docker>=7.0.0",                              # For ContainerCodeExecutor
+  "kubernetes>=29.0.0",                         # For GkeCodeExecutor
+  "langgraph>=0.2.60, <0.4.8",                  # For LangGraphAgent
+  "litellm>=1.75.5",                            # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
+  "llama-index-readers-file>=0.4.0",            # For retrieval using LlamaIndex.
+  "llama-index-embeddings-google-genai>=0.3.0", # For files retrieval using LlamaIndex.
+  "lxml>=5.3.0",                                # For load_web_page tool.
+  "toolbox-core>=0.1.0",                        # For tools.toolbox_toolset.ToolboxToolset
 ]
 
-otel-gcp = [
-  "opentelemetry-instrumentation-google-genai>=0.3b0, <1.0.0",
-]
+otel-gcp = ["opentelemetry-instrumentation-google-genai>=0.3b0, <1.0.0"]
 
 
 [tool.pyink]

src/google/adk/agents/base_agent.py

@@ -158,8 +158,8 @@ class MyAgent(BaseAgent):
 
   Returns:
     Optional[types.Content]: The content to return to the user.
-      When the content is present, the provided content will be used as agent
-      response and appended to event history as agent response.
+      When the content is present, an additional event with the provided content
+      will be appended to event history as an additional agent response.
   """
 
   def _load_agent_state(

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

@@ -275,20 +275,38 @@ async def _execute_single_function_call_async(
     tool_confirmation: Optional[ToolConfirmation] = None,
 ) -> Optional[Event]:
   """Execute a single function call with thread safety for state modifications."""
-  tool, tool_context = _get_tool_and_context(
-      invocation_context,
-      function_call,
-      tools_dict,
-      tool_confirmation,
+  # Do not use "args" as the variable name, because it is a reserved keyword
+  # in python debugger.
+  # Make a deep copy to avoid being modified.
+  function_args = (
+      copy.deepcopy(function_call.args) if function_call.args else {}
   )
 
-  with tracer.start_as_current_span(f'execute_tool {tool.name}'):
-    # Do not use "args" as the variable name, because it is a reserved keyword
-    # in python debugger.
-    # Make a deep copy to avoid being modified.
-    function_args = (
-        copy.deepcopy(function_call.args) if function_call.args else {}
+  tool_context = _create_tool_context(
+      invocation_context, function_call, tool_confirmation
+  )
+
+  try:
+    tool = _get_tool(function_call, tools_dict)
+  except ValueError as tool_error:
+    tool = BaseTool(name=function_call.name, description='Tool not found')
+    error_response = (
+        await invocation_context.plugin_manager.run_on_tool_error_callback(
+            tool=tool,
+            tool_args=function_args,
+            tool_context=tool_context,
+            error=tool_error,
+        )
     )
+    if error_response is not None:
+      return __build_response_event(
+          tool, error_response, tool_context, invocation_context
+      )
+    else:
+      raise tool_error
+
+  async def _run_with_trace():
+    nonlocal function_args
 
     # Step 1: Check if plugin before_tool_callback overrides the function
     # response.
@@ -375,13 +393,23 @@ async def _execute_single_function_call_async(
     function_response_event = __build_response_event(
         tool, function_response, tool_context, invocation_context
     )
-    trace_tool_call(
-        tool=tool,
-        args=function_args,
-        function_response_event=function_response_event,
-    )
     return function_response_event
 
+  with tracer.start_as_current_span(f'execute_tool {tool.name}'):
+    try:
+      function_response_event = await _run_with_trace()
+      trace_tool_call(
+          tool=tool,
+          args=function_args,
+          function_response_event=function_response_event,
+      )
+      return function_response_event
+    except:
+      trace_tool_call(
+          tool=tool, args=function_args, function_response_event=None
+      )
+      raise
+
 
 async def handle_function_calls_live(
     invocation_context: InvocationContext,
@@ -451,13 +479,17 @@ async def _execute_single_function_call_live(
   tool, tool_context = _get_tool_and_context(
       invocation_context, function_call, tools_dict
   )
-  with tracer.start_as_current_span(f'execute_tool {tool.name}'):
+
+  function_args = (
+      copy.deepcopy(function_call.args) if function_call.args else {}
+  )
+
+  async def _run_with_trace():
+    nonlocal function_args
+
     # Do not use "args" as the variable name, because it is a reserved keyword
     # in python debugger.
     # Make a deep copy to avoid being modified.
-    function_args = (
-        copy.deepcopy(function_call.args) if function_call.args else {}
-    )
     function_response = None
 
     # Handle before_tool_callbacks - iterate through the canonical callback
@@ -511,13 +543,23 @@ async def _execute_single_function_call_live(
     function_response_event = __build_response_event(
         tool, function_response, tool_context, invocation_context
     )
-    trace_tool_call(
-        tool=tool,
-        args=function_args,
-        function_response_event=function_response_event,
-    )
     return function_response_event
 
+  with tracer.start_as_current_span(f'execute_tool {tool.name}'):
+    try:
+      function_response_event = await _run_with_trace()
+      trace_tool_call(
+          tool=tool,
+          args=function_args,
+          function_response_event=function_response_event,
+      )
+      return function_response_event
+    except:
+      trace_tool_call(
+          tool=tool, args=function_args, function_response_event=None
+      )
+      raise
+
 
 async def _process_function_live_helper(
     tool,
@@ -639,24 +681,45 @@ async def run_tool_and_update_queue(tool, function_args, tool_context):
   return function_response
 
 
-def _get_tool_and_context(
-    invocation_context: InvocationContext,
-    function_call: types.FunctionCall,
-    tools_dict: dict[str, BaseTool],
-    tool_confirmation: Optional[ToolConfirmation] = None,
+def _get_tool(
+    function_call: types.FunctionCall, tools_dict: dict[str, BaseTool]
 ):
+  """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'Function {function_call.name} is not found in the tools_dict:'
+        f' {tools_dict.keys()}.'
     )
 
-  tool_context = ToolContext(
+  return tools_dict[function_call.name]
+
+
+def _create_tool_context(
+    invocation_context: InvocationContext,
+    function_call: types.FunctionCall,
+    tool_confirmation: Optional[ToolConfirmation] = None,
+):
+  """Creates a ToolContext object."""
+  return ToolContext(
       invocation_context=invocation_context,
       function_call_id=function_call.id,
       tool_confirmation=tool_confirmation,
   )
 
-  tool = tools_dict[function_call.name]
+
+def _get_tool_and_context(
+    invocation_context: InvocationContext,
+    function_call: types.FunctionCall,
+    tools_dict: dict[str, BaseTool],
+    tool_confirmation: Optional[ToolConfirmation] = None,
+):
+  """Returns the tool and tool context corresponding to the function call."""
+  tool = _get_tool(function_call, tools_dict)
+  tool_context = _create_tool_context(
+      invocation_context,
+      function_call,
+      tool_confirmation,
+  )
 
   return (tool, tool_context)
 

src/google/adk/telemetry/tracing.py

@@ -26,6 +26,7 @@
 import json
 import os
 from typing import Any
+from typing import Optional
 from typing import TYPE_CHECKING
 
 from google.genai import types
@@ -118,7 +119,7 @@ def trace_agent_invocation(
 def trace_tool_call(
     tool: BaseTool,
     args: dict[str, Any],
-    function_response_event: Event,
+    function_response_event: Optional[Event],
 ):
   """Traces tool call.
 
@@ -154,7 +155,8 @@ def trace_tool_call(
   tool_call_id = '<not specified>'
   tool_response = '<not specified>'
   if (
-      function_response_event.content is not None
+      function_response_event is not None
+      and function_response_event.content is not None
       and function_response_event.content.parts
   ):
     response_parts = function_response_event.content.parts
@@ -169,7 +171,8 @@ def trace_tool_call(
 
   if not isinstance(tool_response, dict):
     tool_response = {'result': tool_response}
-  span.set_attribute('gcp.vertex.agent.event_id', function_response_event.id)
+  if function_response_event is not None:
+    span.set_attribute('gcp.vertex.agent.event_id', function_response_event.id)
   if _should_add_request_response_to_spans():
     span.set_attribute(
         'gcp.vertex.agent.tool_response',