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 :)

[odrobek]

I'd also like to see a solution to this. While building an agent, Google Search and RAG tools are vital, but the only workaround is using AgentTool wrappers, which as this issue describes, loses all grounding metadata, which is also vital to the function of the agent. Would love to know if there will be a solution for this or if anyone has found any workarounds, especially for the deployed agents.

As @robert-h-dss notes above, using multiple sub-agents is not possible with multiple different built in tools, so AgentTool wrapping is currently the only way to get the search working, but the grounding metadata is lost. Hoping this is resolved sometime soon.

[seanzhou1023]

Thanks for reporting the issue. I understand this issue only happens when you use an agent (which uses google_search tool) as tool. This is the current limitation. we don't support tool response with grounding_metadata.

a work around you can do is that the parent agent and the agent wrapped in the tool shares artifact service, you can use artifact service as a media to pass this information :

1. you have an after_model_callback for the agent that is wrapped as tool that save the grounding_metadata from the llm_response to artifact service.
2. you have an after_agent_callback / after_tool_callback for the parent agent to read the grounding_metadata from the artifact service

Let me know if that works for you.

meanwhile we will explore how we can let tool return some metadata that agent can encode them into event yielded

[maryshgh]

I believe artifacts are recommended for specific types of data and use cases, my issue is that the python dictionary returned by tool is converted to a text by agent wrapped in the AgentTool, it doesn't seem practical to add all that complexities with artifacts to only be able to pass a python dictionary, can we just store them in state using the callback tools?

[bmigette]

Hi, here's a working example I've managed to do. I haven't tested it thoroughly. The session state might persists during multiple messages, so you might need a before_model callback to clear it. In my case, appending the temp: prefix prevented to get the output.

Agent:

corpus = os.environ.get("RAG_JIRA_CORPUS")
assert corpus is not None

def save_grounding_metadata(callback_context: CallbackContext, llm_response: LlmResponse) -> Optional[types.Content]:
    callback_context.state["rag_grounding_sources"] = llm_response.grounding_metadata
    # temp: to persist only during invocation. Won't be available after agent execution
    # https://google.github.io/adk-docs/sessions/state/#organizing-state-with-prefixes-scope-matters
    return None

jira_rag_tool = VertexAiRagRetrieval(
    name='jira_rag_tool',
    description=(
        'Use this tool to retrieve Jira ticket details from the RAG corpus,'
    ),
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus
        )
    ],
    similarity_top_k=10,
    vector_distance_threshold=0.6,
)

jira_rag_agent_rag = Agent(
    model=GEMINI_MODEL,
    name="jira_rag_agent",
    description="Agent to answer questions RAG with Jira Tickets.",
    instruction=prompt.JIRA_RAG_PROMPT_RAG,
    #output_key="google_search_output",
    tools=[jira_rag_tool],
    after_model_callback = save_grounding_metadata
)
# https://google.github.io/adk-docs/tools/built-in-tools/#use-built-in-tools-with-other-tools
# Currently, for each root agent or single agent, only one built-in tool is supported. No other tools of any type can be used in the same agent.
# Solution: Create a secondary agent with RAG tool and include it as a tool in root agent
jira_rag_agent = Agent(
    model=GEMINI_MODEL,
    name="jira_rag_agent",
    description="Agent to answer questions RAG with Jira Tickets.",
    instruction=prompt.JIRA_RAG_PROMPT,
    #output_key="google_search_output",
    #tools=[jira_rag_tool, get_single_jira_details],
    tools=[AgentTool(jira_rag_agent_rag), get_single_jira_details],
)

root_agent = jira_rag_agent

Getting metadata:

async def get_chat_response_from_chat_id(self, query: str, user: str, chat_id: str) -> AIAgentResult:
        """
        Retrieve chat response using specific chat ID for Google Search Agent

        Args:
            query (str): User's input message
            chat_id (str): Unique identifier for the chat session
            urns:
            dict: Response from ADK
        """
        # Placeholder for actual implementation
        #
        #session = self.agent_engine.get_session(user_id=user, session_id=chat_id)
        logger.debug("get_chat_response_from_chat_id session %s", chat_id)
        text_parts = []
        sources = []
        events = []
        source_offset = 0
        content = types.Content(role="user", parts=[types.Part(text=query)])
        async for event in self.runner.run_async(
            user_id=user,
            session_id=chat_id,
            new_message=content,
        ):

            logger.debug("\n\n-------------------------")
            logger.debug(f"event : ")
            logger.debug("-------------------------\n\n")

            logger.debug(f"event.invocation_id: {event.invocation_id}")
            logger.debug(f"event.id: {event.id}")
            logger.debug(f"event.is_final_response(): {event.is_final_response()}")                       

            if event.is_final_response():
                session = self.session_service.get_session_sync(user_id=user, session_id=chat_id, app_name=APP_NAME)
                logger.debug("Session State Grounding Data: %s", session.state['rag_grounding_sources']) #Here  you can get 
                text_part = self._get_text_parts_from_event(event)
                text_parts.extend(text_part)
                sources.extend(self._get_sources_from_event(event, source_offset))
                source_offset += len(text_part)

            events.append(event)
        self._last_events = events
        return AIAgentResult(True, self.model_name, text_parts, sources, events)