@oliverlessa/gemini-agent-lib/docs/vertex-grounding-search.md

Uma biblioteca NodeJS para criar agentes de IA com Gemini LLM

Para ilustrar a estrutura final de `tools` ao usar o Vertex AI com Function Calling e Google Search Retrieval simultaneamente, vou fornecer um exemplo concreto em JavaScript, seguindo o formato esperado pelo Vertex AI SDK (com base no nosso planejamento e compreensão da documentação do Gemini).

**Exemplo da Estrutura Final de `tools` para Vertex AI (Function Calling e Google Search Retrieval Combinados):**

```javascript
const toolsForVertexAIExample = [
  {
    functionDeclarations: [ // 1. Declarações de Funções (Function Calling) - Array de objetos
      {
        name: "get_current_weather",
        description: "Obtém a temperatura atual e as condições climáticas para uma determinada localização.",
        parameters: {
          type: "OBJECT", // Importante: Usar "OBJECT" em uppercase para Vertex AI (pode ser sensível a case)
          properties: {
            location: {
              type: "STRING", // Importante: Usar "STRING" em uppercase para Vertex AI
              description: "A cidade e estado, por exemplo: 'São Paulo, SP'"
            },
            unit: {
              type: "STRING", // Importante: Usar "STRING" em uppercase para Vertex AI
              enum: ["celsius", "fahrenheit"],
              description: "A unidade de temperatura a ser utilizada. Padrão é celsius."
            }
          },
          required: ["location"]
        }
      },
      {
        name: "search_restaurants",
        description: "Pesquisa restaurantes em uma determinada localização com base em critérios.",
        parameters: {
          type: "OBJECT", // Importante: Usar "OBJECT" em uppercase para Vertex AI
          properties: {
            location: {
              type: "STRING", // Importante: Usar "STRING" em uppercase para Vertex AI
              description: "Nome da cidade ou região para pesquisar restaurantes."
            },
            cuisine: {
              type: "STRING", // Importante: Usar "STRING" em uppercase para Vertex AI
              description: "Tipo de culinária desejada (opcional)."
            },
            price_range: {
              type: "STRING", // Importante: Usar "STRING" em uppercase para Vertex AI
              enum: ["barato", "médio", "caro"],
              description: "Faixa de preço desejada (opcional)."
            }
          },
          required: ["location"]
        }
      }
      // ... Você pode adicionar mais functionDeclarations aqui ...
    ],
    googleSearchRetrieval: { // 2. Configuração do Google Search Retrieval - Objeto
      disableAttribution: false // ou true, para desabilitar ou habilitar a atribuição de fontes
    }
  }
];
```

**Explicação Detalhada da Estrutura:**

1.  **Array Externo `toolsForVertexAIExample`:**
    *   A configuração `tools` é um array.  Mesmo quando combinamos Function Calling e Google Search Retrieval, **ainda é um array**.
    *   Na maioria dos casos (e no nosso cenário combinado), este array conterá **apenas um elemento**, que é um objeto contendo as configurações combinadas.

2.  **Objeto de Configuração Combinada (Primeiro Elemento do Array):**
    *   O primeiro (e geralmente único) elemento do array `toolsForVertexAIExample` é um objeto JavaScript.
    *   Este objeto tem **duas propriedades principais, que são irmãs (no mesmo nível):**
        *   **`functionDeclarations`:**
            *   **Valor:** Um array de objetos.
            *   **Conteúdo:** Cada objeto dentro deste array é uma **declaração de função** (function declaration), que define uma de suas tools/funções personalizadas.
            *   **Exemplos no Código:**  `get_current_weather` e `search_restaurants` são exemplos de function declarations.
            *   **Estrutura Interna da Function Declaration:** Cada function declaration (como `get_current_weather`) tem as propriedades:
                *   `name`: Nome da função (string).
                *   `description`: Descrição da função (string).
                *   `parameters`: Um objeto que define os parâmetros da função, seguindo o formato JSON Schema (com `type`, `properties`, `required`, `enum`, etc.). **Importante notar o uso de `type: "OBJECT"` e `type: "STRING"` em uppercase, que pode ser relevante para o Vertex AI.**
        *   **`googleSearchRetrieval`:**
            *   **Valor:** Um objeto.
            *   **Conteúdo:** Este objeto configura o Google Search Retrieval.
            *   **Exemplo no Código:**
                ```javascript
                googleSearchRetrieval: {
                    disableAttribution: false
                }
                ```
                *   `disableAttribution: false`:  Um exemplo de opção de configuração para Google Search Retrieval. `false` significa que a API Gemini **irá incluir atribuição** (links para as fontes da pesquisa Google) na resposta quando usar o Google Search. Se você definir como `true`, a atribuição será desabilitada.

**Como Usar Esta Estrutura em seu Código (Classe `Agent` e `VertexAILLM`):**

1.  **Definir `tools` no `Agent`:** Ao instanciar a classe `Agent`, você passaria o array `toolsForVertexAIExample` (ou um array similar com suas próprias tools e configuração de Google Search Retrieval) para a propriedade `tools` do agente.

    ```javascript
    const meuAgente = new Agent({
        // ... outras propriedades do agente ...
        tools: toolsForVertexAIExample, // Passando a configuração combinada de tools
        enableGoogleSearch: false // Note que enableGoogleSearch AQUI DEVE SER false, pois a config de pesquisa já está em 'tools'
    });
    ```

    **Importante:** Quando você fornece a configuração `googleSearchRetrieval` **dentro do array `tools`**, você **não precisa (e não deve)** habilitar `googleSearchRetrieval` também usando a propriedade `enableGoogleSearch` do `Agent`. A propriedade `enableGoogleSearch` que adicionamos ao `Agent` seria mais útil como um *atalho* para habilitar apenas o Google Search Retrieval *sem* function calling (o que pode ser um caso de uso mais simples em algumas situações).  Se você está definindo uma configuração `tools` completa que já inclui `googleSearchRetrieval`, deixe `enableGoogleSearch` como `false` ou não defina (já que o padrão é `false`).

2.  **`prepareToolsForLLM()`:**  A função `prepareToolsForLLM()` na classe `Agent` deve ser capaz de processar essa estrutura `toolsForVertexAIExample` corretamente e passá-la para a chamada à API Gemini via Vertex AI. A versão corrigida de `prepareToolsForLLM()` que implementamos anteriormente já deve ser capaz de lidar com essa estrutura combinada.

**Em Resumo:**

Esta estrutura de `tools` demonstra como você pode **combinar o poder do Function Calling com a capacidade de Google Search Retrieval** em suas aplicações de agentes Gemini no Vertex AI. Ao fornecer um array `tools` com essa estrutura para o seu agente, você estará habilitando o modelo Gemini a escolher usar suas funções personalizadas, realizar pesquisas na web, ou até mesmo combinar ambas as abordagens para responder da melhor forma possível às solicitações dos usuários.  Lembre-se sempre de verificar a documentação mais recente da API Vertex AI para garantir que a estrutura e as opções de configuração estejam atualizadas.