Google Search Tool does not return grounding metadata in ADK Runner events

[robert-h-dss]

** Please make sure you read the contribution guide and file the issues in the right place. **
Contribution guide.

Describe the bug
When utilizing the Google Search tool within an ADK Runner flow, the event objects emitted by the Runner do not contain the expected grounding_metadata. This metadata, crucial for understanding the source and reliability of information, is absent from the event representing the tool's output.

While grounding_metadata appears to be logged elsewhere (e.g., in debug or info logs), it is not accessible directly within the Runner's event stream after the tool execution, which prevents programmatic access to provenance information.

To Reproduce

Steps to reproduce the behavior:

1. Configure the ADK agents with the structure shown below, which includes an orchestrator_agent using a chat_agent, which in turn uses a google_search_agent as a tool:

   from google.adk.agents.llm_agent import LlmAgent
   from google.adk.tools import agent_tool
   from google.adk.tools import google_search
   
   orchestrator_agent = LlmAgent(
       model=_settings.google_llm_model,
       name="ai_assistant",
       instruction=(prompt.INSTRUCTION_PROMPT),
       sub_agents=[
         chat_agent,
         # ... other sub_agents
       ],
   )
   
   chat_agent = LlmAgent(
       model=_settings.google_llm_model,
       name="chat_ai_assistant",
       instruction=(prompt.INSTRUCTION_PROMPT),
       global_instruction=(prompt.GLOBAL_PROMPT),
       tools=[
           agent_tool.AgentTool(agent=google_search_agent, skip_summarization=True),
       ],
       sub_agents=[
           faq_agent,
           # ... other sub_agents
       ],
   )
   
   google_search_agent = LlmAgent(
       model=_settings.google_llm_model,
       name="google_search_agent",
       instruction=prompt.GOOGLE_SEARCH_PROMPT,
       tools=[
           google_search
       ],
   )
   
   faq_agent = LlmAgent(
       model=_settings.google_llm_model,
       name="faq_agent",
       instruction=prompt.FAQ_PROMPT,
       tools=(
           [
             faq_tool
           ]
       ),
   )

2. Implement a process_message function that uses the Runner to interact with the orchestrator agent and iterates through its events:

   async def process_message(
       self, query: str, session_id: str, user_id: str, dtr_token: str
     ) -> str:
       """Process a message and get the agent's response.
   
       Args:
         query: The user's query
         session_id: The session ID
   
       Returns:
         str: The agent's response
       """
       try:
         # Ensure session exists
         self.get_or_create_session(session_id, user_id, dtr_token)
   
         # Create runner
         runner = Runner(
           agent=orchestrator_agent,
           app_name=self.app_name,
           session_service=self.session_service,
         )
   
         # Prepare user message
         content = types.Content(role="user", parts=[types.Part(text=query)])
   
         # Default response
         final_response_text = "Agent did not produce a final response."
   
         # Run agent and get response
         async for event in runner.run_async(
           user_id=user_id, session_id=session_id, new_message=content
         ):
           # Observe 'event' objects here.
           # print(f"Received event: {event}") # Add this to inspect events
           if event.is_final_response():
             if event.content and event.content.parts:
               if event.content.parts[0].function_response:
                 final_response_text = event.content.parts[
                   0
                 ].function_response.response["result"]
               elif event.content.parts[0].text:
                 final_response_text = event.content.parts[0].text
               else:
                 final_response_text = event.content.parts[1].text
             elif event.actions and event.actions.escalate:
               final_response_text = f"Agent escalated: {event.error_message or 'No specific message.'}"
             break
   
         return final_response_text
   
       except Exception as e:
         logger.error(f"Error processing message: ") # Consider adding {e} to the log message
         raise

3. Call process_message with a query that prompts the chat_agent to use the google_search_agent tool.

4. Examine the event objects yielded by runner.run_async(). Observe that the event pertaining to the google_search tool's result lacks grounding_metadata.

Expected behavior
The event object corresponding to the google_search tool's output should include grounding_metadata. This metadata should be accessible directly within the event structure (e.g., event.content.parts[0].tool_output.grounding_metadata or a similar path) to allow downstream processing of sourced information.

It is suspected that an intermediary event object might be missing between the AgentTool call event and its eventual result event that should contain this metadata.

Screenshots
If applicable, add screenshots to help explain your problem.

Desktop (please complete the following information):

• OS: macOS 15.5
• Python version(python -V): 3.13.2
• ADK version(pip show google-adk): 1.3.0

Model Information:
gemini-2.5-flash

Additional context
The described agent structure (orchestrator -> chat_agent -> google_search_agent) is intended to fully leverage the Google Search tool. However, the current event emission by the Runner prevents direct access to grounding information.

Additionally, related functionalities such as skip_summarization (when set on the AgentTool) and general tool callback mechanisms also do not appear to function as expected.

[KSonPham]

Hey @robert-h-dss have you tried:

gm = event.grounding_metadata
        if gm and gm.grounding_chunks:
            for chunk in gm.grounding_chunks:
                if chunk.web and chunk.web.uri:
                    citations.append(chunk.web.uri)

[robert-h-dss]

Hey @KSonPham as I mentioned with the setup above, the whole event stream does not contain grounding_metadata.

[renshi-a]

I've investigated this issue and found the root cause of why GroundingMetadata is not being returned when using google_search_agent through AgentTool.

Investigation Summary

Test Setup

I created comprehensive tests in ADK-Java with different approaches:

1. Direct LlmAgent with GoogleSearchTool
2. Using Runner with GoogleSearchTool
3. Using AgentTool.create() to wrap the search agent

Results

• Test 1 & 2: ✅ Successfully retrieved GroundingMetadata
• Test 3: ❌ No GroundingMetadata returned through AgentTool

Root Cause

The issue is in the AgentTool implementation in both ADK-Python and ADK-Java. The tool only returns the text content from the last event, discarding all other event metadata including GroundingMetadata:

ADK-Python

adk-python/src/google/adk/tools/agent_tool.py

Lines 134 to 141 in 0ec69d0

	user_id='tmp_user',
	state=tool_context.state.to_dict(),
	)
	last_event = None
	async for event in runner.run_async(
	user_id=session.user_id, session_id=session.id, new_message=content
	):

  if not last_event or not last_event.content or not last_event.content.parts:
    return ''
  merged_text = '\n'.join(p.text for p in last_event.content.parts if p.text)
  # ... 
  return tool_result  # Only returns text or parsed object, no metadata

ADK-Java (AgentTool.java:113-145):

  .lastElement()
  .map(optionalLastEvent -> {
      // ... extracts only text content
      return ImmutableMap.of("result", output);
  })

When Google Search is executed, the agent's response event contains both:

• The answer text in event.content
• The GroundingMetadata in event.groundingMetadata

However, AgentTool only extracts and returns the text portion, discarding the GroundingMetadata.

Update

I've discovered that while AgentTool loses GroundingMetadata, using a custom BaseAgent as a subagent successfully preserves it.

When you create a custom agent that extends BaseAgent and use it as a subagent (not via AgentTool), the entire event stream is propagated to the parent agent, including GroundingMetadata:

Python equivalent example

  class GoogleSearchAgent(BaseAgent):
      def __init__(self):
          super().__init__(name="google_search_agent",
  description="Performs Google searches")
          self.internal_agent = LlmAgent(
              tools=[GoogleSearchTool()],
              # ... other config
          )

      async def run_async(self, invocation_context):
          # Simply return the internal agent's event 
  stream
          async for event in
  self.internal_agent.run_async(invocation_context):
              yield event  # All events including 
  GroundingMetadata are preserved

  ### Use as subagent
  main_agent = LlmAgent(
      sub_agents=[GoogleSearchAgent()],  # ✅ 
  GroundingMetadata preserved
      # ... other config
  )

The crucial difference is that:

• AgentTool: Extracts only the final text/object from the event stream
• SubAgent: Passes the entire event stream to the parent, preserving all metadata

This provides a viable workaround for scenarios where you need to modularize Google Search functionality while preserving GroundingMetadata.

[robert-h-dss]

@renshi-a Hi! Thank you for your comment!

I have tried this work around, doesn't work in case you want to use more sub-agents (see example implementation above).

Error is the following:

2025-07-21 09:08:56.429 | ERROR | process_message:85 | Error processing message: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}} 2025-07-21 09:08:56.430 | ERROR | chat:50 | Error in chat endpoint: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': 'Multiple tools are supported only when they are all search tools.', 'status': 'INVALID_ARGUMENT'}}

The code doesn't run if you have multiple sub-agents or either agent as tools. (And of course the important thing is that you have more than one (sub)agent than Google Search.)

[bmigette]

I'm facing the same issue, I have an agent that leverages 2 Agents as AgentTool, one for websearch, and one for RAG, it seems to be loosing groundingMetadata with this approach

main_agent = Agent(
    model=GEMINI_MODEL,
    name='main_agent',
    description="Agent to answer question",
    instruction=return_instructions_root(),
    tools=[        
        AgentTool(agent=rag_agent),
        AgentTool(agent=google_search_agent),
    ]
)

Is there a way to retrieve the groundingMetadata one way or the other ?
Edit: It seems using SequentialAgent + ParallelAgent as described in this example might do the trick:
https://google.github.io/adk-docs/agents/workflow-agents/parallel-agents/#how-it-works

Edit2: While I get the event results for all sub_agents running the main agent locally (via adk web), I get only the final event when using a deployed agent on AgentEngine, and grounding info is not retrieved. So still looking for a good solution for this too :)