Repository navigation
Description
** 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:
-
Configure the ADK agents with the structure shown below, which includes an
orchestrator_agentusing achat_agent, which in turn uses agoogle_search_agentas 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 ] ), )
-
Implement a
process_messagefunction that uses theRunnerto 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
-
Call
process_messagewith a query that prompts thechat_agentto use thegoogle_search_agenttool. -
Examine the
eventobjects yielded byrunner.run_async(). Observe that theeventpertaining to thegoogle_searchtool's result lacksgrounding_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.
Activity
KSonPham commentedon Jul 2, 2025
Hey @robert-h-dss have you tried:
robert-h-dss commentedon Jul 2, 2025
Hey @KSonPham as I mentioned with the setup above, the whole event stream does not contain grounding_metadata.
renshi-a commentedon Jul 19, 2025
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:
Results
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
ADK-Java (AgentTool.java:113-145):
When Google Search is executed, the agent's response event contains both:
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
The crucial difference is that:
This provides a viable workaround for scenarios where you need to modularize Google Search functionality while preserving GroundingMetadata.
robert-h-dss commentedon Jul 21, 2025
@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 commentedon Aug 5, 2025
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
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 commentedon Aug 22, 2025
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 commentedon Aug 29, 2025
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 :
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 commentedon Sep 8, 2025
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 commentedon Sep 11, 2025
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:
Getting metadata:
2 remaining items
kurochig commentedon Dec 24, 2025
In my case the callback_context example from the above didn't work. I have an orchestrator agent having search agent as a tool, which has a search tool of its own. In a nutshell orchestrator => search => tool.
There is session isolation: When AgentTool calls search_agent, it creates a separate session with its own session ID (see agent_tool.py in ADK lines 137-152):
When we store metadata in callback_context.state['metadata'], which is invocation-scoped and stored in each search_agent's session state.
State forwarding: Only event.actions.state_delta is forwarded from child to parent (see agent_tool.py lines 162-163)
Also, when state is updated, then it replaces values (dict.update), so lists aren't merged. When we have two child sessions running in parallel, then only one of them would end up in parent, the other one is simply overwritten.
Hence the function that collects metadata
This function is attached as the following:
I have a plugin that collects the metadata
The plugin has after_run_callback:
here is what _extract_grounding_sources does, it's written very defensively, so kind of verbose
This solution worked for me.
surajksharma07 commentedon Jan 16, 2026
This is a known limitation with
AgentTool- it only extracts text content and discardsgrounding_metadata.Use
GoogleSearchAgentToolfromgoogle.adk.tools.google_search_agent_toolinstead:After the run completes, access grounding metadata via
session.state.get("temp:_adk_grounding_metadata").surajksharma07 commentedon Feb 4, 2026
Checked against latest ADK (post v1.23.0) — the core
AgentToolbug is still present.agent_tool.py:247-276still only extracts text from the last event and discardsgrounding_metadata.However,
GoogleSearchAgentTool(google_search_agent_tool.py:111-140) is available as a workaround — it captures grounding metadata and stores it insession.state["temp:_adk_grounding_metadata"].This workaround is marked temporary internally (
TODO(b/448114567)), indicating the team intends to fixAgentToolitself.surajksharma07 commentedon Feb 4, 2026
@Jacksunwei Please have a look into it once.
xuanyang15 commentedon Apr 5, 2026
Grounding metadata is part of the llm response, it is not an event to emit. We have added a
propagate_grounding_metadataparameter in AgentTool (d689a04), which can be used to propagate grounding metadata from AgentTool to its parent agent. If you need other operation on the grounding metadata, you can also consider using callbacks to read and manipulate the metadata instate['temp:_adk_grounding_metadata'].