Criar um agente para descobrir seus dados

O agente de descoberta do Knowledge Catalog é um assistente com tecnologia de IA que melhora a relevância da pesquisa para consultas complexas em linguagem natural com base nos recursos de pesquisa do Knowledge Catalog. Ao otimizar a compreensão e a formulação de consultas, ele oferece resultados mais precisos do que a API Knowledge Catalog Search padrão. Esse recurso é essencial, principalmente para consultas complexas ou longas.

Casos de uso

O agente de descoberta oferece uma experiência de conversa avançada para cenários como:

  • Objetivos e restrições complexos ou combinados:processamento de solicitações de pesquisa com vários critérios, como encontrar conjuntos de dados em us-central1, mas excluir recursos no BigQuery.
  • Pesquisa orientada aos negócios:descubra recursos de dados com base na intenção e no contexto de negócios, em vez de corresponder a termos técnicos exatos.
  • Exploração em várias etapas:refinar a pesquisa com um diálogo para reduzir os resultados.

O agente de descoberta é criado com base na pesquisa semântica do Knowledge Catalog, que oferece pesquisa híbrida pronta para uso. Você pode continuar usando a pesquisa semântica do Knowledge Catalog diretamente quando precisar processar pesquisas de alta intenção (quando você conhece o recurso ou a coluna específica), requisitos de baixa latência ou pesquisa híbrida sem configuração.

Como funciona

O agente de descoberta realiza as seguintes etapas para responder a uma consulta de pesquisa:

  1. Analisa a entrada para entender a intenção da consulta, gera várias variações de pesquisa e mapeia termos para filtros de metadados.
  2. Pesquisa recursos usando a pesquisa semântica do Knowledge Catalog.
  3. Classifica os resultados combinados com base na relevância.

O diagrama a seguir mostra os detalhes do processo:

Processo do agente de descoberta para solicitações de pesquisa.
Caminho de processamento para solicitações de pesquisa no agente de descoberta.

O agente usa a API Knowledge Catalog Search para buscar recursos Google Cloud relevantes. O snippet de código a seguir mostra como o agente chama a pesquisa semântica do 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}

Antes de começar

Para executar o agente de descoberta do Knowledge Catalog, verifique se você atende aos seguintes requisitos:

Funções exigidas

Para receber as permissões necessárias para usar o agente de descoberta, peça ao administrador para conceder a você os seguintes papéis do IAM no seu Google Cloud projeto iam.gserviceaccount.com:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar o agente de descoberta. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar o agente de descoberta:

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

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Ativar APIs

Para usar o agente de descoberta do Knowledge Catalog, ative as seguintes APIs no seu projeto: API Knowledge Catalog, API Vertex AI e API Service Usage.

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

Ativar as APIs

Configure o ambiente

Para configurar o ambiente de desenvolvimento do agente de descoberta, faça o seguinte:

  1. Clone o repositório dataplex-labs.

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

  2. Mude para o diretório do agente:

    cd dataplex-labs/knowledge_catalog_discovery_agent

  3. Crie e ative um ambiente virtual do Python e instale as dependências listadas no arquivo requirements.txt:

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

  source /tmp/kcsearch/bin/activate

  pip3 install -r requirements.txt

  4. Configure as variáveis de ambiente com o seguinte comando:

    
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_GENAI_USE_VERTEXAI=True

    Substitua:

    • PROJECT_ID com o ID do projeto

Executar o agente de descoberta como o agente raiz

Para executar o agente de descoberta diretamente como o agente raiz, faça o seguinte:

  1. No arquivo agent.py localizado na pasta knowledge_catalog_discovery_agent, renomeie a variável discovery_agent como root_agent.

  2. Execute o agente usando o comando adk run:

    adk run path/to/agent/parent/folder

    Substitua:

    • path/to/agent/parent/folder com o diretório pai que contém a pasta com o agente. Por exemplo, se o agente estiver em knowledge_catalog_discovery_agent/, execute adk run no diretório agents/.

Executar o agente de descoberta como uma ferramenta de agente

Para integrar o agente de descoberta a um agente personalizado maior, como o my_custom_agent, faça o seguinte:

  1. Configure a estrutura do projeto para conter o módulo do agente de descoberta:

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

  2. No arquivo agent.py do seu agente personalizado, importe o agente de descoberta e use-o como uma ferramenta de agente. Confira o exemplo:

    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. Execute o agente usando o comando adk run:

    adk run path/to/agent/parent/folder

    Substitua:

    • path/to/agent/parent/folder com o diretório pai que contém a pasta my_custom_agent/. Por exemplo, se o agente estiver em agents/my_custom_agent/, execute adk run no diretório agents/.

A seguir