A extensão Gemini CLI para Elasticsearch com ferramentas e recursos

Temos a satisfação de anunciar o lançamento da nossa extensão Elastic para a Gemini CLI do Google, trazendo toda a eficiência da Elasticsearch e Elastic Agent Builder diretamente para o seu fluxo de trabalho de desenvolvimento de IA. Essa extensão também oferece várias habilidades de agente recentemente desenvolvidas para interagir com o Elasticsearch.

A extensão está disponível como um projeto open source aqui.

O que é a Gemini CLI e como você a instala?

Gemini CLI é um agente de IA open source que traz os modelos Gemini do Google diretamente para a linha de comando. Ele permite que os desenvolvedores interajam com a IA a partir do terminal para realizar tarefas como gerar código, editar arquivos, executar comandos do shell e recuperar informações da web.

Diferentemente das interfaces típicas de chat, a Gemini CLI se integra ao seu ambiente local de desenvolvimento, o que significa que ela pode entender o contexto do projeto, modificar arquivos, executar builds ou testes e automatizar fluxos de trabalho diretamente no terminal. Isso a torna útil para desenvolvedores, engenheiros de confiabilidade de sites (SREs) e outros profissionais que desejam codificação e automação assistidas por IA sem sair do fluxo de trabalho da linha de comando.

Você pode instalar a Gemini CLI usando vários gerenciadores de pacotes. O método mais comum é usar o npm:

Para conhecer opções alternativas de instalação, consulte a página oficial de instalação.

Após a instalação, inicie a CLI executando:

Você vê uma tela, conforme mostrado na Figura 1:

Configurar o Elasticsearch

Precisamos ter uma instância do Elasticsearch em execução. Se quiser usar o servidor MCP (Model Context Protocol), você também precisará ter o Kibana 9.3+ instalado. Para usar a habilidade da Elasticsearch linguagem de consulta (ES|QL) (esql) descrita abaixo, o Kibana não é necessário.

Você pode ativar um teste gratuito no Elastic Cloud ou instalá-lo localmente usando o script start-local :

Isso instalará o Elasticsearch e o Kibana no seu computador e gerará uma chave API para ser usada na configuração da Gemini CLI.

A chave API será mostrada como saída do comando anterior e armazenada em um .env arquivo na pasta elastic-start-local.

Se você está usando o Elasticsearch no local (por exemplo, usando start-local), e quer usar o Elastic Agent Builder com MCP, também precisa conectar um grande modelo de linguagem (LLM). Você pode ler esta página de documentação para entender as diferentes opções.

Se você estiver usando o Elastic Cloud (ou serverless), já tem uma conexão LLM pré-configurada.

Instale a extensão do Elasticsearch

Você pode instalar a extensão Elasticsearch para Gemini CLI com o seguinte comando:

Você pode verificar se as extensões foram instaladas com sucesso abrindo o Gemini e executando o seguinte comando:

Você deverá ver a extensão Elasticsearch disponível.

Se quiser usar a integração MCP, precisa ter uma versão do Elasticsearch 9.3+ instalada. Você precisa da URL do seu servidor MCP do Kibana:

• Obtenha a URL do seu servidor MCP em Agents > View all tools > Manage MCP > Copy MCP Server URL (Agentes > Ver todas as ferramentas > Gerenciar MCP > Copiar URL do Servidor MCP).
• A URL ficará assim: https://your-kibana-instance/api/agent_builder/mcp

Você precisa da URL do endpoint do Elasticsearch. Isso normalmente é relatado no topo da página do Kibana Elasticsearch. Se você está rodando o Elasticsearch com start-local, você já tem o endpoint na chave ES_LOCAL_URL no start-local .env. arquivo.

Também é necessário uma chave de API. Se estiver executando o Elasticsearch com start-local, você já tem a ES_LOCAL_API_KEY no arquivostart-local .env arquivo. Caso contrário, é possível criar uma chave de API usando a interface do Kibana, conforme indicado aqui:

• No Kibana: Stack Management > Security > API Keys > Create API Key (Stack management > Segurança > Chaves de API > Criar chave de API) .
• Sugerimos definir apenas os privilégios de leitura para a chave API, habilitando o privilégio feature_agentBuilder.read conforme reportado aqui.
• Copie o valor da chave de API codificada.

Defina as variáveis de ambiente necessárias no seu shell:

Instale o conjunto de dados de exemplo

Você pode instalar o conjunto de dados de pedidos de comércio eletrônico disponível no Kibana. Inclui um único índice chamado kibana_sample_data_ecommerce, contendo informações sobre 4.675 pedidos de um website. Para cada pedido, temos as seguintes informações:

• Informações do cliente (nome, ID, data de nascimento, e-mail e mais).
• Data do pedido.
• ID do pedido.
• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto e outros detalhes).
• SKU.
• Preço total (sem impostos, com impostos).
• Quantidade total.
• Informações geográficas (cidade, país, continente, localização, região).

Para instalar os dados de exemplo, abra a página Integrações no Kibana (busque por “Integração” na barra de busca superior) e instale os Dados de Exemplo. Para mais detalhes, consulte a documentação aqui.

O objetivo deste artigo é mostrar como é fácil configurar o Gemini CLI para se conectar ao Elasticsearch e interagir com o índice kibana_sample_data_ecommerce.

Como usar o Elasticsearch MCP

Você pode verificar a conexão usando o seguinte comando no Gemini:

Você deve ver o elastic-agent-builder ativado, como mostrado na Figura 2:

O Elasticsearch fornece um conjunto padrão de ferramentas. Veja a descrição aqui.

Usando essas ferramentas, você pode interagir com o Elasticsearch, fazendo perguntas como:

• Give me the list of all the indexes available in Elasticsearch.
• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

Dependendo da pergunta, o Gemini usará uma ou mais ferramentas disponíveis para tentar respondê-la.

Os comandos

Na extensão Elasticsearch para Gemini CLI, também adicionamos /elastic comandos.

Se você executar o comando /help, verá todas as opções de /elastic disponíveis (Figura 3):

Esses comandos podem ser úteis se você quiser executar diretamente uma ferramenta específica do servidor MCP.elastic-agent-builder Por exemplo, usando o seguinte comando, você pode obter o mapeamento do kibana_sample_data_ecommerce:

Esses comandos são essencialmente atalhos para executar ferramentas específicas, em vez de depender do modelo Gemini para determinar qual ferramenta deve ser usada.

Como usar as habilidades do Elasticsearch

Essa extensão também inclui uma habilidade de agente para o ES|QL, a Linguagem de Consulta Elasticsearch disponível no Elasticsearch. Agent Skills é um formato aberto que fornece aos agentes de programação de IA, como o Gemini CLI, instruções personalizadas para tarefas específicas. Eles utilizam um conceito chamado divulgação progressiva, o que significa que apenas uma breve descrição da habilidade é adicionada ao prompt inicial do sistema. Quando você solicita que o agente execute uma tarefa, como consultar o Elasticsearch, ele associa a solicitação à habilidade relevante e carrega dinamicamente as instruções detalhadas. Essa é uma forma eficiente de gerenciar orçamentos de tokens enquanto fornece à IA exatamente o contexto que ela precisa.

A habilidade esqlfoi projetada para permitir que o Gemini CLI escreva e execute consultas ES|QL diretamente no seu cluster. ES|QL é uma poderosa linguagem de consulta encadeada que torna a exploração de dados, a análise de logs e as agregações altamente intuitivas. Com essa habilidade ativada, você não precisa pesquisar a sintaxe ES|QL; basta fazer perguntas em linguagem natural ao Gemini CLI sobre seus dados e o agente cuidará do resto.

As execuções são realizadas usando simples comandos curl executados em um terminal. Isso é possível porque o Elasticsearch oferece um conjunto abrangente de APIs REST que podem ser facilmente usadas para integrar o sistema a qualquer arquitetura.

O que a habilidadeesqloferece:

• Descoberta de índices e esquemas: o agente pode usar as ferramentas integradas da habilidade para listar os índices disponíveis e buscar mapeamentos de campo. Por exemplo, antes de escrever uma consulta para o conjunto de dados de comércio eletrônico, o agente pode executar uma verificação de esquema em kibana_sample_data_ecommerce para entender os campos disponíveis, como taxful_total_price ou category.
• Tradução perfeita da linguagem natural: a habilidade dá ao agente mais do que um simples manual de referência; ela fornece um guia específico para interpretar a intenção do usuário. Quando você digita solicitações em linguagem natural, como "Mostrar tempo médio de resposta agrupado por serviço", o agente usa o padrão de correspondência da habilidade para traduzir instantaneamente suas palavras nas agregações, filtros e comandos ES|QL corretos.
• Autocorreção: Se uma consulta falhar (por exemplo, devido a uma incompatibilidade de tipo ou erro de sintaxe), a skill retorna a consulta gerada juntamente com a mensagem de erro exata do Elasticsearch, permitindo que o agente corrija instantaneamente a consulta e tente novamente sem que você precise intervir.

Como a habilidade esql também está disponível como ferramenta no servidor MCP elastic-agent-builder, precisamos desativar esse servidor momentaneamente. Você pode usar o seguinte comando para desativá-lo:

Em seguida, você pode simplesmente digitar um prompt como esse em sua Gemini CLI:

O agente irá:

• Reconheça a necessidade da habilidade esql .
• Verifique o esquema do kibana_sample_data_ecommerce.
• Crie uma consulta ES|QL, como: FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5.
• Execute a consulta na API do Elasticsearch.
• Apresente a resposta final para você diretamente no terminal.

Aqui, apresentamos um exemplo de resposta do Gemini ao prompt anterior:

É interessante notar como o modelo Gemini gera a resposta final mostrando todos os passos que ele segue. Aqui, você pode ver claramente a influência da habilidade no processo de raciocínio do modelo. Na primeira vez que o modelo reconhece que precisa usar uma habilidade ou executar um comando shell, ele solicita permissão usando a abordagem baseada em intervenção humana.

Ao lidar com o trabalho pesado de descoberta de esquema, geração de consultas e execução, a habilidade esql permite que você se concentre inteiramente nas respostas, em vez da mecânica de obtê-las. Você obterá os dados de que precisa, formatados corretamente e diretamente no seu terminal, tudo isso sem precisar escrever uma única linha de código ou alternar para outro aplicativo.

Conclusão

Neste artigo, apresentamos a extensão Elasticsearch para Gemini CLI que lançamos recentemente. Essa extensão oferece a você a capacidade de interagir com a instância do Elasticsearch usando o Gemini e o servidor Elasticsearch MCP fornecido pelo Elastic Agent Builder, disponível a partir da versão 9.3.0, bem como o comando /elastic.

Além disso, a extensão também inclui uma habilidade esql que converte a solicitação do usuário de linguagem natural em uma consulta ES|QL. Essa habilidade pode ser particularmente útil quando o servidor MCP não pode ser usado, pois a comunicação subjacente é conduzida por comandos curl simples executados em um terminal. O Elasticsearch oferece um conjunto abrangente de APIs REST que podem ser facilmente integradas a qualquer projeto. Isso é especialmente útil ao desenvolver aplicações de IA agêntica.

Para mais informações sobre nossa extensão Gemini CLI, acesse o repositório do projeto aqui.