Citations available for Vertex AI Search with structured data ?

[merzak274j]

Is citation metadata (e.g., groundingMetadata) currently supported when grounding on a Vertex AI Search datastore backed by structured data?

In my testing, this metadata appears to be dropped, though it is present when using the GenAI SDK directly.

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The ADK does support citation metadata for Vertex AI Search, but it is primarily designed for unstructured data. While there is some indication that it can work with structured data, it's possible that you are encountering a limitation or a configuration issue.

---

Hello! Thanks for your question.

The Application Development Kit (ADK) is designed to work with Vertex AI Search and provides citation metadata through the grounding_metadata attribute in the LlmResponse object. This metadata is crucial for grounding the model's responses in your source data and providing citations. [1]

Based on the information available, the ADK's grounding capabilities are most robust with unstructured data, where it can extract chunks of text and their corresponding URIs to include in the groundingMetadata. When you are using structured data, it is possible that the citation metadata is not being populated as expected. This could be due to a few reasons:

1. Configuration: The VertexAiSearchTool can be configured to search with different modes, such as CHUNKS. It is possible that the way the tool is configured affects how metadata is retrieved from structured data sources.
2. Data Structure: The structure of your data in the Vertex AI Search datastore might influence whether the necessary metadata for citations can be extracted. The ADK code has some logic to prioritize URIs from struct_data, which suggests that it is intended to work, but it might have specific requirements for the data format.
3. ADK Version: Ensure you are using a recent version of the ADK, as features and capabilities are continuously updated. For example, version 1.16.0 introduced citation_metadata to LlmResponse, which is related to grounding.

While I cannot confirm if this is a bug or a limitation without more details about your implementation, I would recommend reviewing the ADK's documentation on grounding with Vertex AI Search and ensuring your data and tool configuration align with the expected formats.

If you continue to experience issues, providing a minimal reproducible example would be very helpful for further investigation.

---

[1] https://google.github.io/adk-docs/grounding/vertex_ai_search_grounding/

[merzak274j]

Hi, adding concrete details + a minimal repro snippet from my side.

What I observe

• My Vertex AI Search datastore is structured.
• Vertex AI Search rejects chunk-style results for this engine unless content_search_spec.search_result_mode is set to DOCUMENTS (otherwise I get a 400).
• With ADK + VertexAiSearchTool against this structured datastore, LlmResponse.grounding_metadata (and any citation payload) appears empty / missing, even though the response is clearly grounded in retrieved records.
• When I query the same datastore via the GenAI SDK directly, I can see the grounding/citation payload present (or at least the equivalent grounding information).

This makes me suspect one of:

1. DOCUMENTS-mode structured results don’t include enough URI/chunk citation payload for ADK to translate into grounding_metadata, or
2. ADK is dropping / not propagating the Search tool’s metadata into LlmResponse.grounding_metadata, especially in the recommended multi-agent setup (AgentTool) used to combine built-in tools.

Minimal repro (ADK)

import os
from google.adk.agents import LlmAgent
from google.adk.tools import VertexAiSearchTool

DATA_STORE_ID = "projects/PROJECT/locations/global/collections/default_collection/dataStores/STORE_ID"

agent = LlmAgent(
    name="search_agent",
    model="gemini-3-flash-preview",
    instruction="Search the datastore and answer using the retrieved results.",
    tools=[VertexAiSearchTool(data_store_id=DATA_STORE_ID)],
)

# Runner code depends on your ADK integration; the key check is:
# print(response.grounding_metadata)  # <-- empty/missing for me on structured datastore

When the datastore is structured, I also see the API-side constraint:

400 `content_search_spec.search_result_mode` must be set to SearchRequest.ContentSearchSpec.SearchResultMode.DOCUMENTS when the engine contains structured data store.

So this engine is effectively locked into DOCUMENTS search result mode.

Minimal repro (GenAI SDK)

import os
from google import genai

client = genai.Client(vertexai=True)

# Pseudocode-ish: the key point is that the direct SDK call returns grounding/citation payload
# in the response object (whereas ADK's LlmResponse.grounding_metadata is empty for me).
#
# resp = client.models.generate_content(
#     model="gemini-3-flash-preview",
#     contents="...",
#     tools=[ ... Vertex AI Search tool / retrieval config ... ],
# )
# print(resp.candidates[0].grounding_metadata or resp.candidates[0].groundingMetadata)

Ask / clarification

Can you confirm whether LlmResponse.grounding_metadata citations are expected to be populated for structured Vertex AI Search datastores (DOCUMENTS mode), and if so:

• which exact fields/URIs in a structured document result ADK uses to populate citations, and
• whether the multi-agent pattern (AgentTool) is expected to propagate grounding metadata back to the root response?

If structured/DOCUMENTS is not currently supported for citations, it’d be helpful to document that limitation (and recommended workarounds, like emitting doc ids/URIs explicitly in text).