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, il fournit des résultats plus précis que l'API de recherche Knowledge Catalog 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, par exemple :

  • Intention et contraintes complexes ou combinées : traitement des requêtes de recherche avec plusieurs critères, par exemple la recherche d'ensembles de données dans us-central1, mais l'exclusion des ressources dans BigQuery.
  • Recherche axée sur l'entreprise : découverte d'actifs de données en fonction de l'intention et du contexte métier plutôt que de la correspondance exacte des termes techniques.
  • Exploration en plusieurs étapes : affinement de votre recherche par le biais d'un dialogue conversationnel pour limiter les résultats.

L'agent de découverte repose sur la recherche sémantique Knowledge Catalog qui vous offre une recherche hybride prête à l'emploi. Vous pouvez continuer à utiliser directement la recherche sémantique Knowledge Catalog 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'entrée 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 les détails du processus :

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

L'agent s'appuie sur l'API de recherche Knowledge Catalog pour extraire les ressources pertinentes Google Cloud . L'extrait de code suivant montre comment l'agent appelle la recherche sémantique 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 respecter les exigences 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 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 requirements.txt fichier :

    • 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 à l'aide de 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 directement l'agent de découverte 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 adk run commande :

    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 dans un agent personnalisé plus volumineux, tel que my_custom_agent, procédez comme suit :

  1. Configurez la structure de votre projet pour qu'elle contienne le module de l'agent de découverte :

    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. Consultez l'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/.

Étape suivante