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 multitours : affiner votre recherche par le biais d'un dialogue pour réduire le nombre de résultats.

L'agent de découverte est basé sur la recherche sémantique du catalogue de connaissances, 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 schéma 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 ressources Google Cloud pertinentes. L'extrait de code suivant montre comment l'agent appelle la recherche sémantique du catalogue de connaissances :


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

Avant de commencer

Pour exécuter l'agent de découverte du catalogue de connaissances, 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 projet Google Cloud 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 avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. 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 que sous-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