构建代理以发现数据

借助 Knowledge Catalog(以前称为 Dataplex Universal Catalog)的开源发现代理,您可以使用复杂或冗长的自然语言查询来查找相关数据资产。通过使用智能体开发套件 (ADK),您可以将此 AI 赋能的助理作为根智能体运行,或将其作为工具集成到自定义智能体中。如需了解详情,请参阅 GitHub 上的发现代理。

使用场景

发现智能体可为以下场景提供丰富的对话式体验:

  • 复杂或组合的意图和限制条件:处理具有多个条件的搜索请求,例如在 us-central1 中查找数据集,但排除 BigQuery 中的资源。
  • 面向业务的搜索:根据意图和业务情境发现数据资产,而不是匹配确切的技术术语。
  • 多轮探索:通过对话式对话优化搜索,缩小结果范围。

发现代理基于 Knowledge Catalog 语义搜索构建,可提供开箱即用的混合搜索。通过优化查询理解和表述,该代理可提供比标准 Knowledge Catalog Search API 更准确的结果,尤其是在处理复杂或冗长的查询时。您可以继续直接使用 Knowledge Catalog 语义搜索,以进行高意向搜索(当您知道特定资源或列时)、低延迟查询或零设置混合搜索。如需了解详情,请参阅在 Knowledge Catalog 中搜索数据资产。

工作原理

发现代理会执行以下步骤来响应搜索查询:

  1. 分析输入内容以了解查询意图,生成多个搜索变体,并将字词映射到元数据过滤条件。
  2. 使用 Knowledge Catalog 语义搜索功能搜索资源。
  3. 根据相关性对合并结果进行排名。

下图提供了该流程的详细信息:

搜索请求的发现代理进程。
发现代理中搜索请求的处理路径。

智能体依靠 Knowledge Catalog Search API 来提取相关Google Cloud 资源。以下代码段展示了智能体如何调用 Knowledge Catalog 语义搜索:

# Configure the request parameters for the
# call to Knowledge Catalog Semantic Search API.
endpoint = "dataplex.googleapis.com"

client = dataplex_v1.CatalogServiceClient(
    client_options={"api_endpoint": endpoint}
)

location = "global"
consumer_project_id = "my-gcp-project"
parent_name = f"projects/{consumer_project_id}/locations/{location}"

# Call Knowledge Catalog Semantic Search API.
response = client.search_entries(
    request={
        "name": parent_name,
        "query": query,
        "page_size": 50,
        "semantic_search": True,
    }
)

# Call Knowledge Catalog LookupContext for each search result
# to retrieve rich, LLM-ready metadata.
entries = []
for result in response.results:
    entry_name = result.dataplex_entry.name

    # Prepare the LookupContext request for the specific resource
    lookup_request = {
        "name": parent_name,
        "resources": [entry_name]
    }

    # Call the LookupContext API
    lookup_response = client.lookup_context(request=lookup_request)

    # Extract the rich context YAML to share with the agent
    entries.append({
        "entry_name": entry_name,
        "context": lookup_response.context
    })

return {"results": entries}

准备工作

如需运行 Knowledge Catalog 发现代理,请确保您满足以下要求:

所需的角色

如需获得使用发现代理所需的权限,请让您的管理员为您授予 Google Cloud 项目的以下 IAM 角色:

如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含使用发现代理所需的权限。如需查看所需的确切权限,请展开所需权限部分:

所需权限

如需使用发现代理,需要具备以下权限:

  • dataplex.projects.search
  • dataplex.entries.get
  • aiplatform.endpoints.predict
  • serviceusage.services.use

您也可以使用自定义角色或其他预定义角色来获取这些权限。

除了在运行代理的项目中拥有这些角色之外,您还必须对底层源系统资源拥有读取权限(例如,对于 BigQuery 资产,需要 BigQuery Metadata Viewer [roles/bigquery.metadataViewer])。search_entries 和 lookup_context 方法仅返回您有权访问的资产的结果。

启用 API

如需使用 Knowledge Catalog 发现代理,请在项目中启用以下 API:Dataplex API、Vertex AI API 和 Service Usage API。

启用 API 所需的角色

如需启用 API,您需要拥有 serviceusage.services.enable 权限。如果您创建了项目,则可能已经通过 Owner 角色 (roles/owner) 拥有此权限。否则,您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

设置环境

如需为发现代理设置开发环境,请执行以下操作:

  1. 克隆 dataplex-labs 代码库:

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git ~/dataplex-labs
    
  2. 切换到代理目录:

    cd ~/dataplex-labs/knowledge_catalog_discovery_agent
    
  3. 创建并激活 Python 虚拟环境,然后安装 requirements.txt 文件中列出的依赖项:

    • google-adk(智能体开发套件)
    • google-cloud-dataplex(Knowledge Catalog Python 客户端)
    • google-api-core
    python3 -m venv /tmp/kcsearch
    source /tmp/kcsearch/bin/activate
    pip3 install -r requirements.txt
    
  4. 使用 Google Cloud 进行身份验证并设置环境变量:

    gcloud auth application-default login
    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_GENAI_USE_VERTEXAI=True
    

    替换以下内容:

    • PROJECT_ID:您的项目的 ID。

以根智能体身份运行发现智能体

如需直接以根代理身份运行发现代理,请执行以下操作:

  1. 在 knowledge_catalog_discovery_agent 文件夹中的 agent.py 文件中,将 root_agent = discovery_agent 添加到文件末尾,以便 ADK CLI 可以将发现代理加载为根代理。
  2. 使用 adk run 命令运行代理:

    adk run PATH_TO_AGENT_FOLDER
    

    替换以下内容:

    • PATH_TO_AGENT_FOLDER:knowledge_catalog_discovery_agent 目录的路径。例如,如果您已在 knowledge_catalog_discovery_agent 目录中,请使用 ~/dataplex-labs/knowledge_catalog_discovery_agent 或 .。
  3. 如果系统在您首次运行时提示您启用遥测,请输入 y 或 n,然后按 Enter:

    Enable telemetry? [Y/n]: y
    

    如需稍后停用遥测,请运行 adk telemetry disable。

  4. 验证代理是否已初始化并显示交互式 [user]: 提示:

    Running agent knowledge_catalog_discovery_agent, type exit to exit.
    [user]:
    
  5. 在 [user]: 提示符处,输入自然语言查询,以发现和探索数据资产。将以下场景中的示例数据集和表名称替换为您项目中的资源:

    • 数据探索:
      • Show me all datasets in the us region.
      • What is the sales_orders_us dataset about?
      • Is there a demographic dataset I can join with my sales data?
    • 元数据和治理发现:
      • Show me if any tables in sales_orders_us are missing schemas or descriptions.
      • Find all BigQuery tables related to customer accounts and summarize their schemas.
  6. 如需退出交互式会话并彻底关闭后台连接,请在 [user]: 提示符处输入 exit:

    [user]: exit
    

将发现代理作为代理工具运行

如需将发现代理集成到更大的自定义代理(例如 my_custom_agent)中,请执行以下操作:

  1. 创建 my_custom_agent 目录,并将 knowledge_catalog_discovery_agent 文件夹复制到其中:

    mkdir -p ~/dataplex-labs/my_custom_agent
    touch ~/dataplex-labs/my_custom_agent/agent.py
    cp -r ~/dataplex-labs/knowledge_catalog_discovery_agent ~/dataplex-labs/my_custom_agent/
    

    验证您的 my_custom_agent 目录是否具有以下结构:

    my_custom_agent/
    ├── agent.py
    └── knowledge_catalog_discovery_agent/
        ├── SKILL.md
        ├── agent.py
        ├── tools.py
        └── utils.py
    
  2. 在 ~/dataplex-labs/my_custom_agent/agent.py 中,导入 discovery_agent 并将其封装在 agent_tool.AgentTool 中:

    from google.adk.agents import LlmAgent
    from google.adk.tools import agent_tool
    from .knowledge_catalog_discovery_agent.agent import discovery_agent
    
    GEMINI_MODEL = "gemini-2.5-flash"
    
    root_agent = LlmAgent(
        name="my_custom_agent",
        model=GEMINI_MODEL,
        instruction=(
            "You are a Custom Agent. Your goal is to help users understand"
            " their data landscape, evaluate data assets, and derive insights"
            " from available resources. **IMPORTANT**: You should use the"
            " `knowledge_catalog_discovery_agent` to search for and discover"
            " data assets. For best results, pass in the natural language user"
            " query as is to the `knowledge_catalog_discovery_agent`. Once"
            " assets are found, analyze their metadata, compare them, and"
            " provide recommendations or summaries to help the user make"
            " decisions. Focus on general metadata summary and comparison."
        ),
        tools=[
            agent_tool.AgentTool(discovery_agent),
        ],
    )
    
  3. 使用 adk run 命令运行自定义代理:

    adk run ~/dataplex-labs/my_custom_agent
    
  4. 在 [user]: 提示符处,让自定义智能体发现并总结资产,以测试集成:

    [user]: Search for all datasets in us-central1 and give me a summary of their business context.
    
  5. 如需退出交互式会话,请在 [user]: 提示符处输入 exit:

    [user]: exit
    

后续步骤

概念

通过结合使用自然语言、元数据过滤条件、限定谓语和逻辑运算符来构建查询。

AI 集成

使用 ADK 构建、测试和编排 Python 智能体和智能体工具。

应用场景

逐步了解上下文丰富化、数据沿袭和生成式 AI 工作流的端到端场景。