借助 Knowledge Catalog(以前称为 Dataplex Universal Catalog)的开源发现代理,您可以使用复杂或冗长的自然语言查询来查找相关数据资产。通过使用智能体开发套件 (ADK),您可以将此 AI 赋能的助理作为根智能体运行,或将其作为工具集成到自定义智能体中。如需了解详情,请参阅 GitHub 上的发现代理。
使用场景
发现智能体可为以下场景提供丰富的对话式体验:
- 复杂或组合的意图和限制条件:处理具有多个条件的搜索请求,例如在
us-central1中查找数据集,但排除 BigQuery 中的资源。 - 面向业务的搜索:根据意图和业务情境发现数据资产,而不是匹配确切的技术术语。
- 多轮探索:通过对话式对话优化搜索,缩小结果范围。
发现代理基于 Knowledge Catalog 语义搜索构建,可提供开箱即用的混合搜索。通过优化查询理解和表述,该代理可提供比标准 Knowledge Catalog Search API 更准确的结果,尤其是在处理复杂或冗长的查询时。您可以继续直接使用 Knowledge Catalog 语义搜索,以进行高意向搜索(当您知道特定资源或列时)、低延迟查询或零设置混合搜索。如需了解详情,请参阅在 Knowledge Catalog 中搜索数据资产。
工作原理
发现代理会执行以下步骤来响应搜索查询:
- 分析输入内容以了解查询意图,生成多个搜索变体,并将字词映射到元数据过滤条件。
- 使用 Knowledge Catalog 语义搜索功能搜索资源。
- 根据相关性对合并结果进行排名。
下图提供了该流程的详细信息:
智能体依靠 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 Catalog Viewer (
roles/dataplex.catalogViewer) - Vertex AI User (
roles/aiplatform.user) - Service Usage Consumer (
roles/serviceusage.serviceUsageConsumer)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含使用发现代理所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需使用发现代理,需要具备以下权限:
-
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) 获得此权限。了解如何授予角色。
设置环境
如需为发现代理设置开发环境,请执行以下操作:
克隆
dataplex-labs代码库:git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git ~/dataplex-labs切换到代理目录:
cd ~/dataplex-labs/knowledge_catalog_discovery_agent创建并激活 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使用 Google Cloud 进行身份验证并设置环境变量:
gcloud auth application-default login export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GOOGLE_GENAI_USE_VERTEXAI=True替换以下内容:
PROJECT_ID:您的项目的 ID。
以根智能体身份运行发现智能体
如需直接以根代理身份运行发现代理,请执行以下操作:
- 在
knowledge_catalog_discovery_agent文件夹中的agent.py文件中,将root_agent = discovery_agent添加到文件末尾,以便 ADK CLI 可以将发现代理加载为根代理。 使用
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或.。
如果系统在您首次运行时提示您启用遥测,请输入
y或n,然后按Enter:Enable telemetry? [Y/n]: y如需稍后停用遥测,请运行
adk telemetry disable。验证代理是否已初始化并显示交互式
[user]:提示:Running agent knowledge_catalog_discovery_agent, type exit to exit. [user]:在
[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.
- 数据探索:
如需退出交互式会话并彻底关闭后台连接,请在
[user]:提示符处输入exit:[user]: exit
将发现代理作为代理工具运行
如需将发现代理集成到更大的自定义代理(例如 my_custom_agent)中,请执行以下操作:
创建
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在
~/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), ], )使用
adk run命令运行自定义代理:adk run ~/dataplex-labs/my_custom_agent在
[user]:提示符处,让自定义智能体发现并总结资产,以测试集成:[user]: Search for all datasets in us-central1 and give me a summary of their business context.如需退出交互式会话,请在
[user]:提示符处输入exit:[user]: exit