Ground agents with data and organizational context

Google Cloud Build with AI Agents
, , ,
1

Introduction

LLM-powered agents have changed how we interact with and understand data. They offer the potential to provide insights from datasets, answer complex questions, synthetise broad range of signals , generate code, and power intelligent data discovery tools. However, to unlock this potential reliably, LLMs need more than just a table name; they need broad, AND relevant, context associated with the data asset. Without proper grounding in factual metadata and real-world usage patterns, LLMs are prone to hallucinate, providing plausible but incorrect or irrelevant answers. This is where Knowledge Catalog now offers a tool to supplement agentic workflows - LookupContext API.

The context gap in agentic workflows

Imagine asking an LLM to summarize the information about the Transactions table. To provide an accurate and insightful summary, the LLM would need to retrieve multiple pieces of context to to address questions like:

  • What is the precise schema, including data types and column descriptions?

  • Are there any business definitions or glossary terms associated with these columns?

  • What is the overall purpose or description of this table?

  • How is this table typically used? Are some columns more important than others?

  • What’s the general data quality?

  • Does this table relate to other important data assets?

  • What’s the data distribution? Which columns contain highly unique values and which ones are mostly empty? What are the sample values?

Traditionally, gathering this information in an agentic workflow involves a complex “treasure hunt” - stitching together data from multiple API calls to various systems, parsing different formats, and manually assembling a prompt. This process is slow, error-prone, and difficult to scale.

Introducing LookupContext

Knowledge Catalog has recently launched the new LookupContext API endpoint. This powerful feature is designed to bridge the context gap, providing a single, performant API call to retrieve a rich, pre-formatted bundle of metadata specifically tailored for consumption by LLMs.

With LookupContext, you can equip your AI applications with a deep understanding of your data assets, significantly improving the accuracy and relevance of LLM-generated responses.

Key benefits of LookupContext API:

  • LLM-ready formats: Returns metadata in clean, structured format (YAML), minimizing the need for complex prompt engineering.

  • Rich and relevant metadata: Consolidates essential information including schema, column descriptions, attached business terms, data profiles, data quality scores, usage statistics, and relationships to other catalog entries.

  • Retrieval of context across the relationship graph: Includes patterns detected through continuous analysis of query history, providing the “missing link” for accurate multi-table SQL generation.

  • High performance: Engineered for low-latency retrieval, crucial for interactive AI applications.

  • Security-awareness: Automatically respects user permissions. Inaccessible information is seamlessly truncated from the response, ensuring the LLM only sees what the user is authorized to see.

  • Intelligent truncation: Allows specifying a context budget to manage LLM token limits. Knowledge Catalog intelligently prioritizes the most critical information when truncation is necessary.

Further on the relationship graph

One of the most significant hurdles for LLMs is understanding how disparate tables relate in a complex schema. Without this knowledge, LLMs often hallucinate “custom functions” or incorrect logic to join data. To solve this, Knowledge Catalog now continuously analyzes your organization’s logs history to detect potential JOIN patterns. For instance, instead of an LLM hallucinating a complex temporary function and a CASE statement to map country codes, this context allows it to generate a simple, performant INNER JOIN against the existing country_tariffs table.

This intelligence is automatically included in the LookupContext response. By grounding your agent in actual usage patterns, you ensure it produces realistic, performant queries that reflect your team’s established data practices.

Use case: AI-powered data asset summarization

Let’s say you want to build an agent that generates a natural language summary for a given data asset in your catalog.

The Knowledge Catalog LookupContext workflow is as follows:

  1. The agent makes a single API call.

  2. The API returns a well-structured document in yaml (default), json, or xml format containing the essential metadata.

  3. This YAML is injected directly into the LLM prompt.

  4. The LLM, grounded by this rich context, generates an accurate and insightful summary.

Here’s an example how you can construct a sample agentic RAG workflow by leveraging LookupContext API:


from google.cloud import dataplex_v1

from google.api_core import exceptions

client = dataplex_v1.CatalogServiceClient()

request = dataplex_v1.LookupContextRequest(

    name="projects/test-project/locations/us",

    resources=[resource_name],

)


context_yaml = client.lookup_context(request=request).context

llm_prompt = f"""

Your task is to generate a concise summary of a data asset based on the provided context. It will be presented in YAML format and may include data asset details such as its schema, descriptions, associated business, terms, data profile statistics (like sample values, null percentages, and uniqueness percentages), as well as data quality test results. You may be provided with sample SQL queries. Inspect these SQL queries for interesting patterns that can be reused for querying best practices.

```

{context_yaml}

```

"""




gemini_model.generate_content(llm_prompt)

A conceptual sample response from LookupContext API is similar to the following:

resources:

  - catalogEntry: transactions

    description: Stores detailed records of regional sales transaction. Includes customer information and product details.

    schema:

      - name: product_sku

        type: STRING

        description: Stock Keeping Unit of the product sold.

        distinctValues: 436213

        nullRatio: 0.1

        sampleValues: 

          - NIK-AIR-WHT-10

      - name: customer_id

        type: STRING

        description: Unique identifier for the customer.

        distinctValues: 81732

        nullRatio: 0.0

        sampleValues: 

          - 61f0c404-5cb3-11e7-907b-a6006ad3dba0

      - name: region

        type: STRING

        description: Sales region

        distinctValues: 3

        nullRatio: 0.0

        sampleValues: 

          - EMEA

      - name: sale_amount

        type: NUMERIC

        description: The total amount for this sale transaction.

        terms: "Gross Revenue"

        distinctValues: 321452

        nullRatio: 0.0

        sampleValues: 

          - 100

      - name: sale_date

        type: DATE

        nullRatio: 0.0

        sampleValues: 

          - 2026-03-11T13:00:00

    qualityStatus: PASS

Get started

Accurate and reliable AI in the data domain hinges on effective grounding. LookupContext API in Knowledge Catalog provides a streamlined and powerful way to furnish your LLMs with the rich, real-time metadata they need.

Explore the new LookupContext endpoint and see how it enhances your agents accuracy.

For more information, see the Knowledge Catalog API documentation and LookupContext API guide.

Author: Mateusz Nowak, Andrew Ikonnikov, Paulina Trzeciak

2 Likes