Créer un agent pour découvrir vos données

L'agent de découverte Knowledge Catalog est un assistant optimisé par l'IA qui améliore la pertinence de la recherche pour les requêtes complexes en langage naturel en fonction des fonctionnalités de recherche de Knowledge Catalog. En optimisant la compréhension et la formulation des requêtes, elle fournit des résultats plus précis que l'API Knowledge Catalog Search standard. Cette fonctionnalité est essentielle, en particulier pour les requêtes complexes ou longues.

Cas d'utilisation

L'agent de découverte offre une expérience conversationnelle riche pour les scénarios suivants :

  • Intents et contraintes complexes ou combinées : traitement des demandes de recherche comportant plusieurs critères, par exemple la recherche d'ensembles de données dans us-central1, mais en excluant les ressources dans BigQuery.
  • Recherche axée sur l'activité : découvrez des composants de données en fonction de l'intention et du contexte métier, plutôt qu'en recherchant des termes techniques exacts.
  • Exploration multitour : affiner votre recherche par le biais d'un dialogue conversationnel pour réduire le nombre de résultats.

L'agent de découverte est basé sur la recherche sémantique Knowledge Catalog, qui vous offre une recherche hybride prête à l'emploi. Vous pouvez continuer à utiliser la recherche sémantique Knowledge Catalog directement lorsque vous devez traiter des recherches à forte intention (lorsque vous connaissez la ressource ou la colonne spécifique), des exigences de faible latence ou une recherche hybride sans configuration.

Fonctionnement

L'agent de découverte effectue les étapes suivantes pour répondre à une requête de recherche :

  1. Analyse l'intention de l'utilisateur pour comprendre la requête, génère plusieurs variantes de recherche et mappe les termes aux filtres de métadonnées.
  2. Recherche des ressources à l'aide de la recherche sémantique Knowledge Catalog.
  3. Classe les résultats fusionnés en fonction de leur pertinence.

Le diagramme suivant fournit des informations détaillées sur le processus :

Processus de l'agent Discovery pour les requêtes de recherche.
Chemin de traitement des requêtes de recherche dans l'agent Discovery.

L'agent s'appuie sur l'API Knowledge Catalog Search pour extraire les ressourcesGoogle Cloud pertinentes. L'extrait de code suivant montre comment l'agent appelle la recherche sémantique de 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}

Avant de commencer

Pour exécuter l'agent de découverte Knowledge Catalog, assurez-vous de remplir les conditions suivantes :

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser l'agent de découverte, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre Google Cloud projet iam.gserviceaccount.com :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour utiliser l'agent de découverte. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Vous devez disposer des autorisations suivantes pour utiliser l'agent de découverte :

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

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Activer les API

Pour utiliser l'agent de découverte Knowledge Catalog, activez les API suivantes dans votre projet : API Knowledge Catalog, API Vertex AI et API Service Usage.

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

Activer les API

Configurer l'environnement

Pour configurer l'environnement de développement de l'agent de découverte, procédez comme suit :

  1. Clonez le dépôt dataplex-labs.

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

  2. Accédez au répertoire de l'agent :

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Créez et activez un environnement virtuel Python, puis installez les dépendances listées dans le fichier requirements.txt :

    • google-adk (Agent Development Kit)
    • google-cloud-dataplex (client Python Knowledge Catalog)
    • google-api-core
      python3 -m venv /tmp/kcsearch

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. Configurez les variables d'environnement avec la commande suivante :

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Remplacez les éléments suivants :

    • PROJECT_ID par l'ID de votre projet ;

Exécuter l'agent de découverte en tant qu'agent racine

Pour exécuter l'agent de découverte directement en tant qu'agent racine, procédez comme suit :

  1. Dans le fichier agent.py situé dans le dossier knowledge_catalog_discovery_agent, renommez la variable discovery_agent en root_agent.

  2. Exécutez l'agent à l'aide de la commande adk run :

    adk run path/to/agent/parent/folder

    Remplacez les éléments suivants :

    • path/to/agent/parent/folder par le répertoire parent contenant le dossier de votre agent. Par exemple, si votre agent se trouve dans knowledge_catalog_discovery_agent/, exécutez adk run à partir du répertoire agents/.

Exécuter l'agent de découverte en tant qu'outil d'agent

Pour intégrer l'agent de découverte à un agent personnalisé plus vaste, tel que my_custom_agent, procédez comme suit :

  1. Configurez la structure de votre projet pour qu'il contienne le module de l'agent Discovery :

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

  2. Dans le fichier agent.py de votre agent personnalisé, importez l'agent de découverte et utilisez-le comme outil d'agent. Voici un exemple :

    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. Exécutez l'agent à l'aide de la commande adk run :

    adk run path/to/agent/parent/folder

    Remplacez les éléments suivants :

    • path/to/agent/parent/folder par le répertoire parent contenant votre dossier my_custom_agent/. Par exemple, si votre agent se trouve dans agents/my_custom_agent/, exécutez adk run à partir du répertoire agents/.

Étapes suivantes