Crea un agente para descubrir tus datos

El agente de descubrimiento de Knowledge Catalog es un asistente potenciado por IA que mejora la relevancia de la búsqueda para las consultas complejas en lenguaje natural según las capacidades de búsqueda de Knowledge Catalog. Al optimizar la comprensión y la formulación de las búsquedas, proporciona resultados más precisos que la API de Knowledge Catalog Search estándar. Esta capacidad es fundamental, especialmente para las búsquedas complejas o extensas.

Casos de uso

El agente de descubrimiento proporciona una experiencia de conversación enriquecida para situaciones como las siguientes:

  • Intenciones y restricciones complejas o combinadas: Manejo de solicitudes de búsqueda con múltiples criterios, como encontrar conjuntos de datos en us-central1, pero excluir recursos en BigQuery
  • Búsqueda orientada a los negocios: Descubre activos de datos en función de la intención y el contexto empresarial, en lugar de hacer coincidir términos técnicos exactos.
  • Exploración de varios turnos: Define mejor tu búsqueda a través de un diálogo conversacional para limitar los resultados.

El agente de descubrimiento se basa en la búsqueda semántica de Knowledge Catalog, que te proporciona una búsqueda híbrida lista para usar. Puedes seguir usando la búsqueda semántica de Knowledge Catalog directamente cuando necesites procesar búsquedas con un alto nivel de intención (cuando conozcas el recurso o la columna específicos), requisitos de baja latencia o la búsqueda híbrida sin configuración.

Cómo funciona

El agente de descubrimiento realiza los siguientes pasos para responder a una búsqueda:

  1. Analiza la entrada para comprender la intención de la búsqueda, genera múltiples variaciones de búsqueda y asigna términos a filtros de metadatos.
  2. Busca recursos con la búsqueda semántica de Knowledge Catalog.
  3. Clasifica los resultados combinados según la relevancia.

En el siguiente diagrama, se proporcionan los detalles del proceso:

Es el proceso del agente de descubrimiento para las solicitudes de búsqueda.
Ruta de procesamiento para las solicitudes de búsqueda en el agente de descubrimiento.

El agente se basa en la API de Knowledge Catalog Search para recuperar recursos Google Cloud relevantes. En el siguiente fragmento de código, se muestra cómo el agente llama a la búsqueda semántica del Catálogo de conocimiento:


      # 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,
          }
      )

      # Extract useful metadata to share with the agent.
      entries = [
          {
              "entry_name": result.dataplex_entry.name,
              "system": result.dataplex_entry.entry_source.system,
              "resource_id": result.dataplex_entry.entry_source.resource,
              "display_name": result.dataplex_entry.entry_source.display_name,
          }
          for result in response.results
      ]

      return {"results": entries}

Antes de comenzar

Para ejecutar el agente de detección de Knowledge Catalog, asegúrate de cumplir con los siguientes requisitos:

Roles obligatorios

Para obtener los permisos que necesitas para usar el agente de descubrimiento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu Google Cloud proyecto iam.gserviceaccount.com:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para usar el agente de detección. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para usar el agente de descubrimiento:

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

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Habilita las APIs

Para usar el agente de descubrimiento de Knowledge Catalog, habilita las siguientes APIs en tu proyecto: API de Knowledge Catalog, API de Vertex AI y API de Service Usage.

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el permiso serviceusage.services.enable. Obtén más información para otorgar roles.

Habilitar las API

Configura el entorno

Para configurar el entorno de desarrollo del agente de descubrimiento, haz lo siguiente:

  1. Clona el repositorio dataplex-labs.

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git

  2. Cambia al directorio del agente:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Crea y activa un entorno virtual de Python y, luego, instala las dependencias que se indican en el archivo requirements.txt:

    • google-adk (Kit de desarrollo de agentes)
    • google-cloud-dataplex (cliente de Python de Knowledge Catalog)
    • google-api-core
      python3 -m venv /tmp/kcsearch

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. Configura las variables de entorno con el siguiente comando:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Reemplaza lo siguiente:

    • PROJECT_ID con el ID de tu proyecto

Ejecuta el agente de descubrimiento como el agente raíz

Para ejecutar el agente de detección directamente como agente raíz, haz lo siguiente:

  1. En el archivo agent.py ubicado en la carpeta knowledge_catalog_discovery_agent, cambia el nombre de la variable discovery_agent a root_agent.

  2. Ejecuta el agente con el comando adk run:

    adk run path/to/agent/parent/folder

    Reemplaza lo siguiente:

    • path/to/agent/parent/folder por el directorio principal que contiene la carpeta con tu agente. Por ejemplo, si tu agente reside en knowledge_catalog_discovery_agent/, ejecuta adk run desde el directorio agents/.

Ejecuta el agente de descubrimiento como un agente secundario

Para integrar el agente de descubrimiento en un agente personalizado más grande, como my_custom_agent, haz lo siguiente:

  1. Configura la estructura de tu proyecto para que contenga el módulo del agente de descubrimiento:

    my_custom_agent/
├── agent.py
└── knowledge_catalog_discovery_agent/
    ├── SKILL.md
    ├── agent.py
    ├── tools.py
    └── utils.py

  2. En el archivo agent.py de tu agente personalizado, importa el agente de descubrimiento y úsalo como herramienta del agente. Consulta el ejemplo:

    root_agent = llm_agent.Agent(
    model=google_llm.Gemini(model=GEMINI_MODEL),
    name="my_custom_agent",
    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, you should analyze their metadata, compare them, and"
        " provide recommendations or summaries to the user to help them make"
        " decisions. Focus on general metadata summary and comparison."
    ),
    tools=[
        agent_tool.AgentTool(discovery_agent),
    ],
)

  3. Ejecuta el agente con el comando adk run:

    adk run path/to/agent/parent/folder

    Reemplaza lo siguiente:

    • path/to/agent/parent/folder por el directorio principal que contiene tu carpeta my_custom_agent/ Por ejemplo, si tu agente reside en agents/my_custom_agent/, ejecuta adk run desde el directorio agents/.

¿Qué sigue?