fix: Fix built-in search tools in agent hierarchy when transfer_to_agent is present

Gemini models reject requests that combine built-in search tools (such as
GoogleSearchTool or VertexAiSearchTool) with function declarations (such as
transfer_to_agent) with "400 INVALID_ARGUMENT: Tool use with function calling
is unsupported".

This change addresses this in two ways:
1. When built-in search tools (GoogleSearchTool / VertexAiSearchTool) have
   `bypass_multi_tools_limit=True` in an agent hierarchy, `multiple_tools`
   now accounts for transfer targets so the tool is converted to its
   function-tool equivalent (GoogleSearchAgentTool / DiscoveryEngineSearchTool),
   allowing it to cleanly coexist with `transfer_to_agent`.
2. When built-in search tools are used without bypass in an agent hierarchy,
   `_AgentTransferLlmRequestProcessor` skips injecting `transfer_to_agent`
   and transfer instructions, ensuring only the built-in search tool is sent
   to the model without conflict.

Co-authored-by: Shangjie Chen <deanchen@google.com>
PiperOrigin-RevId: 967423502

Author: DeanChensj

src/google/adk/agents/llm_agent.py

@@ -783,7 +783,9 @@ async def canonical_tools(
     # We may need to wrap some built-in tools if there are other tools
     # because the built-in tools cannot be used together with other tools.
     # TODO: Remove once the workaround is no longer needed.
-    multiple_tools = len(self.tools) > 1
+    from ..flows.llm_flows.agent_transfer import _get_transfer_targets
+
+    multiple_tools = len(self.tools) > 1 or bool(_get_transfer_targets(self))
     model = self.canonical_model
 
     results = await asyncio.gather(*(

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

@@ -43,13 +43,17 @@ async def run_async(
       self, invocation_context: InvocationContext, llm_request: LlmRequest
   ) -> AsyncGenerator[Event, None]:
     agent = as_llm_agent(invocation_context)
-    if not hasattr(agent, 'disallow_transfer_to_parent'):
-      return
-
     transfer_targets = _get_transfer_targets(agent)
     if not transfer_targets:
       return
 
+    if err_msg := _get_incompatible_builtin_tool_error(agent):
+      sub_agents = getattr(agent, 'sub_agents', None) or []
+      sub_agent_targets = [t for t in transfer_targets if t in sub_agents]
+      if sub_agent_targets:
+        raise ValueError(err_msg)
+      return
+
     transfer_to_agent_tool = _build_transfer_tool(transfer_targets)
 
     llm_request.append_instructions([
@@ -159,7 +163,7 @@ def _build_transfer_instructions(
   return si
 
 
-def _get_transfer_targets(agent: LlmAgent) -> list[BaseAgent]:
+def _get_transfer_targets(agent: BaseAgent) -> list[BaseAgent]:
   """Gets the list of agents that the current agent can transfer to.
 
   The transfer targets include:
@@ -170,32 +174,35 @@ def _get_transfer_targets(agent: LlmAgent) -> list[BaseAgent]:
       not disallow transfer to peers.
 
   Args:
-    agent: The LlmAgent for which to find transfer targets.
+    agent: The BaseAgent for which to find transfer targets.
 
   Returns:
     A list of BaseAgent instances that are valid transfer targets.
   """
+  if not hasattr(agent, 'disallow_transfer_to_parent'):
+    return []
+
   result = []
-  result.extend([
-      sub_agent
-      for sub_agent in agent.sub_agents
-      if not hasattr(sub_agent, 'mode')
-      or sub_agent.mode not in ('single_turn', 'task')
-  ])
-
-  if not agent.parent_agent or not hasattr(
-      agent.parent_agent, 'disallow_transfer_to_parent'
-  ):
+  if hasattr(agent, 'sub_agents') and agent.sub_agents:
+    result.extend([
+        sub_agent
+        for sub_agent in agent.sub_agents
+        if not hasattr(sub_agent, 'mode')
+        or sub_agent.mode not in ('single_turn', 'task')
+    ])
+
+  parent = getattr(agent, 'parent_agent', None)
+  if not parent or not hasattr(parent, 'disallow_transfer_to_parent'):
     return result
 
-  if not agent.disallow_transfer_to_parent:
-    result.append(agent.parent_agent)
+  if not getattr(agent, 'disallow_transfer_to_parent', False):
+    result.append(parent)
 
-  if not agent.disallow_transfer_to_peers:
+  if not getattr(agent, 'disallow_transfer_to_peers', False):
     result.extend([
         peer_agent
-        for peer_agent in agent.parent_agent.sub_agents
-        if peer_agent.name != agent.name
+        for peer_agent in getattr(parent, 'sub_agents', []) or []
+        if getattr(peer_agent, 'name', None) != getattr(agent, 'name', None)
         and (
             not hasattr(peer_agent, 'mode')
             or peer_agent.mode not in ('single_turn', 'task')
@@ -219,3 +226,38 @@ def _build_transfer_tool(
   return TransferToAgentTool(
       agent_names=[target.name for target in transfer_targets]
   )
+
+
+def _get_incompatible_builtin_tool_error(agent: BaseAgent) -> str | None:
+  """Returns an error message if the agent uses built-in tools incompatible with function calling."""
+  tools = getattr(agent, 'tools', None)
+  if not tools:
+    return None
+
+  from ...tools.enterprise_search_tool import EnterpriseWebSearchTool
+  from ...tools.google_search_tool import GoogleSearchTool
+  from ...tools.vertex_ai_search_tool import VertexAiSearchTool
+
+  agent_name = getattr(agent, 'name', '')
+  for tool in tools:
+    if (
+        isinstance(tool, (GoogleSearchTool, VertexAiSearchTool))
+        and not tool.bypass_multi_tools_limit
+    ):
+      return (
+          f"Agent '{agent_name}' has sub-agent transfer targets but is"
+          f' configured with {tool.__class__.__name__} without'
+          ' bypass_multi_tools_limit=True. Gemini API does not allow built-in'
+          ' search tools to be combined with function calling (agent'
+          ' delegation). To enable both search and sub-agent delegation, set'
+          ' bypass_multi_tools_limit=True on GoogleSearchTool or'
+          ' VertexAiSearchTool.'
+      )
+    if isinstance(tool, EnterpriseWebSearchTool):
+      return (
+          f"Agent '{agent_name}' has sub-agent transfer targets but is"
+          ' configured with EnterpriseWebSearchTool. Gemini API does not allow'
+          ' EnterpriseWebSearchTool to be combined with function calling'
+          ' (agent delegation).'
+      )
+  return None

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

@@ -492,7 +492,9 @@ async def _process_agent_tools(
     return
   agent = cast('LlmAgent', raw_agent)
 
-  multiple_tools = len(agent.tools) > 1
+  from .agent_transfer import _get_transfer_targets
+
+  multiple_tools = len(agent.tools) > 1 or bool(_get_transfer_targets(agent))
   model = agent.canonical_model
 
   from ...agents.llm_agent import _convert_tool_union_to_tools

tests/unittests/agents/test_llm_agent_fields.py

@@ -33,6 +33,7 @@
 from google.adk.planners.built_in_planner import BuiltInPlanner
 from google.adk.sessions.in_memory_session_service import InMemorySessionService
 from google.adk.tools.base_toolset import BaseToolset
+from google.adk.tools.enterprise_search_tool import EnterpriseWebSearchTool
 from google.adk.tools.function_tool import FunctionTool
 from google.adk.tools.google_search_tool import google_search
 from google.adk.tools.google_search_tool import GoogleSearchTool
@@ -557,6 +558,115 @@ async def test_handle_vais_only(self):
     assert tools[0].name == 'vertex_ai_search'
     assert tools[0].__class__.__name__ == 'VertexAiSearchTool'
 
+  async def test_handle_google_search_in_hierarchy_with_bypass(self):
+    """Test that google_search with bypass is wrapped when in an agent hierarchy."""
+    search_agent = LlmAgent(
+        name='search_agent',
+        model='gemini-pro',
+        tools=[GoogleSearchTool(bypass_multi_tools_limit=True)],
+    )
+    _ = LlmAgent(
+        name='root_agent',
+        model='gemini-pro',
+        sub_agents=[search_agent],
+    )
+    ctx = await _create_readonly_context(search_agent)
+    tools = await search_agent.canonical_tools(ctx)
+
+    assert len(tools) == 1
+    assert tools[0].name == 'google_search_agent'
+    assert tools[0].__class__.__name__ == 'GoogleSearchAgentTool'
+
+  async def test_handle_google_search_in_hierarchy_no_bypass(self):
+    """Test that google_search without bypass is not wrapped even in a hierarchy."""
+    search_agent = LlmAgent(
+        name='search_agent',
+        model='gemini-pro',
+        tools=[google_search],
+    )
+    _ = LlmAgent(
+        name='root_agent',
+        model='gemini-pro',
+        sub_agents=[search_agent],
+    )
+    ctx = await _create_readonly_context(search_agent)
+    tools = await search_agent.canonical_tools(ctx)
+
+    assert len(tools) == 1
+    assert tools[0].name == 'google_search'
+    assert tools[0].__class__.__name__ == 'GoogleSearchTool'
+
+  @mock.patch(
+      'google.auth.default',
+      mock.MagicMock(return_value=('credentials', 'project')),
+  )
+  async def test_handle_vais_in_hierarchy_with_bypass(self):
+    """Test that VertexAiSearchTool with bypass is replaced when in an agent hierarchy."""
+    search_agent = LlmAgent(
+        name='search_agent',
+        model='gemini-pro',
+        tools=[
+            VertexAiSearchTool(
+                data_store_id='test_data_store_id',
+                bypass_multi_tools_limit=True,
+            ),
+        ],
+    )
+    _ = LlmAgent(
+        name='root_agent',
+        model='gemini-pro',
+        sub_agents=[search_agent],
+    )
+    ctx = await _create_readonly_context(search_agent)
+    tools = await search_agent.canonical_tools(ctx)
+
+    assert len(tools) == 1
+    assert tools[0].name == 'discovery_engine_search'
+    assert tools[0].__class__.__name__ == 'DiscoveryEngineSearchTool'
+
+  async def test_handle_vais_in_hierarchy_no_bypass(self):
+    """Test that VertexAiSearchTool without bypass is not replaced even in a hierarchy."""
+    search_agent = LlmAgent(
+        name='search_agent',
+        model='gemini-pro',
+        tools=[
+            VertexAiSearchTool(
+                data_store_id='test_data_store_id',
+                bypass_multi_tools_limit=False,
+            ),
+        ],
+    )
+    _ = LlmAgent(
+        name='root_agent',
+        model='gemini-pro',
+        sub_agents=[search_agent],
+    )
+    ctx = await _create_readonly_context(search_agent)
+    tools = await search_agent.canonical_tools(ctx)
+
+    assert len(tools) == 1
+    assert tools[0].name == 'vertex_ai_search'
+    assert tools[0].__class__.__name__ == 'VertexAiSearchTool'
+
+  async def test_handle_enterprise_web_search_in_hierarchy(self):
+    """Enterprise web search without bypass remains a built-in search tool in a hierarchy."""
+    search_agent = LlmAgent(
+        name='search_agent',
+        model='gemini-pro',
+        tools=[EnterpriseWebSearchTool()],
+    )
+    _ = LlmAgent(
+        name='root_agent',
+        model='gemini-pro',
+        sub_agents=[search_agent],
+    )
+    ctx = await _create_readonly_context(search_agent)
+    tools = await search_agent.canonical_tools(ctx)
+
+    assert len(tools) == 1
+    assert tools[0].name == 'enterprise_web_search'
+    assert tools[0].__class__.__name__ == 'EnterpriseWebSearchTool'
+
   async def test_multiple_tools_resolution(self):
     """Test that multiple tools are resolved correctly."""