Recentemente, contribuímos para o projeto open source mastra-ai/mastra adicionando suporte ao Elasticsearch como banco de dados vetorial. Com esse novo recurso, você pode usar o Elasticsearch nativamente no Mastra para armazenar embeddings. Além dos vetores, o Elasticsearch oferece um conjunto de recursos avançados para atender a todos os seus requisitos de engenharia de contexto. (por exemplo, busca híbrida e reranking).

Este artigo detalha a criação de um agente para implementar uma arquitetura de retrieval augmented generation (RAG) usando o Elasticsearch. Vamos apresentar um projeto de demonstração onde uma abordagem agentiva é usada para interagir com um corpus de dados de filmes de ficção científica armazenados no Elasticsearch. O projeto está disponível em elastic/mastra-elasticsearch-example.

Mastra

Mastra é um framework TypeScript para criar aplicações de IA com agentes.

A estrutura do projeto em Mastra é a seguinte:

No Mastra, você pode criar agentes, ferramentas, fluxos de trabalho e métricas.

Um agente é uma classe que aceita uma mensagem na entrada e produz uma resposta como saída. Um agente pode usar ferramentas, grandes modelos de linguagem (LLMs) e uma memória (figura 1).

As ferramentas de um agente permitem que ele interaja com o "mundo externo", como se comunicar com uma API web ou realizar uma operação interna, como consultar o Elasticsearch. O componente de memória é essencial para armazenar o histórico das conversas, incluindo entradas e saídas anteriores. Esse contexto armazenado permite que o agente forneça respostas mais informadas e relevantes para futuras perguntas utilizando suas interações passadas.

Os fluxos de trabalho permitem que você defina sequências complexas de tarefas usando etapas claras e estruturadas, em vez de depender do raciocínio de um único agente (figura 2). Eles dão controle total sobre como as tarefas são divididas, como os dados circulam entre elas e o que é executado e quando. Os fluxos de trabalho são executados usando o mecanismo de execução integrado por padrão ou podem ser implantados em executores de fluxo de trabalho.

No Mastra, você também pode definir métricas, que são testes automatizados para avaliar as saídas dos agentes usando métodos baseados em modelos, regras e estatísticas. Os avaliadores retornam métricas: valores numéricos (normalmente entre 0 e 1) que quantificam o quanto uma saída atende aos seus critérios de avaliação. Essas métricas permitem que você acompanhe objetivamente o desempenho, compare diferentes abordagens e identifique áreas de melhoria em seus sistemas de IA. Os avaliadores podem ser personalizados com seus próprios prompts e funções de métrica.

Elasticsearch

Para executar o projeto de demonstração, precisamos ter uma instância do Elasticsearch em execução. 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 integração Mastra.

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

Instalar e configurar a demonstração

Criamos um repositório elastic/mastra-elasticsearch-example contendo o código-fonte do projeto de demonstração. O exemplo relatado no repositório ilustra como criar um agente no Mastra que implementa uma arquitetura RAG para recuperar documentos do Elasticsearch.

Fornecemos um conjunto de dados para a demonstração sobre filmes de ficção científica. Extraímos 500 filmes do conjunto de dados IMDb no Kaggle.

O primeiro passo é instalar as dependências do projeto com npm, usando o seguinte comando:

Então precisamos configurar o arquivo .env que conterá as configurações. Podemos gerar esse arquivo copiando a estrutura do arquivo .env.example, usando o seguinte comando:

Agora podemos editar o arquivo .env, adicionando as informações que faltam:

O nome do índice do Elasticsearch é scifi-movies. Se quiser, pode mudar usando a variável de ambiente ELASTICSEARCH_INDEX_NAME.

Usamos a OpenAI como serviço de embeddings, o que significa que você precisa fornecer uma chave de API para a OpenAI na variável de ambiente OPENAI_API_KEY.

O modelo de embedding usado no exemplo é openai/text-embedding-3-small, com uma dimensão de embedding de 1.536.

Para gerar a resposta final, utilizamos o modelo openai/gpt-5-nano para reduzir os custos.

A arquitetura RAG permite que você use um modelo LLM final menos potente (e normalmente mais barato) porque o trabalho pesado de fundamentar a resposta é feito pelo componente de recuperação (Elasticsearch, neste caso).

O LLM menor é responsável apenas por duas tarefas principais:

• Reformulação/embedding da consulta: conversão da pergunta do usuário em linguagem natural em um vetor de embedding para busca semântica.

• Sintetização da resposta: pegar os fragmentos de contexto recuperados e altamente relevantes (documentos/filmes) e sintetizá-los em uma resposta coerente, final e legível por humanos, seguindo as instruções do prompt fornecido.

Como o processo RAG fornece o contexto factual exato necessário para a resposta, o LLM final não precisa ser massivo ou altamente complexo, nem precisa possuir todo o conhecimento necessário dentro de seus próprios parâmetros (é aí que modelos grandes e caros se destacam). Basicamente, ele atua como um sofisticado resumidor e formatador de texto para o contexto fornecido pelo Elasticsearch, e não como uma base de conhecimento completa em si. Isso permite o uso de modelos como gpt-5-nano para otimização de custos e latência.

Após a configuração do arquivo .env, você pode fazer a ingestão dos filmes no Elasticsearch usando o seguinte comando:

Você deve ver uma saída da seguinte forma:

O mapeamento do índice de filmes de ficção científica contém os seguintes campos:

• embedding, dense_vector com dimensão de 1.536, similaridade cosseno.

• description, texto contendo a descrição do filme.

• director, texto contendo o nome do diretor.

• título, texto contendo o título do filme.

Geramos os embeddings usando o título e a descrição. Como o título e a descrição são dois campos separados, a concatenação de ambos garante que o vetor de embedding resultante capture tanto a identidade específica e única (título) quanto o contexto rico e descritivo (descrição) do filme, resultando em buscas semânticas mais precisas e abrangentes. Essa entrada combinada oferece ao modelo de embedding uma representação mais adequada do conteúdo do documento para comparação de similaridade.

Execute a demonstração

Você pode executar a demonstração com o seguinte comando:

Esse comando iniciará uma aplicação web em localhost:4111 para acessar o Mastra Studio (Figura 3).

O Mastra Studio oferece uma interface de usuário interativa para criar e testar seus agentes, além de uma REST API que expõe seu aplicativo Mastra como um serviço local. Isso permite que você comece a trabalhar imediatamente, sem se preocupar com integração.

Fornecemos um Agente Elasticsearch que utiliza o createVectorQueryTool da Mastra como ferramenta para executar busca semântica usando Elasticsearch. Esse agente utiliza a abordagem RAG para buscar documentos relevantes (ou seja, filmes) para responder à pergunta do usuário.

Este agente usa o seguinte prompt:

Se você clicar no menu Mastra Studio > Agents e selecionar Agente Elasticsearch, pode testar o agente usando um sistema de chat. Por exemplo, você pode pedir informações sobre filmes de ficção científica com a seguinte pergunta:

Encontre 5 filmes ou séries de TV sobre OVNIs.

Você notará que o agente executará a ferramenta vectorQueryTool. Você pode clicar na ferramenta invocada para visualizar a entrada e a saída. Ao final da execução, o LLM responderá à sua pergunta, considerando o contexto do índice de filmes de ficção científica do Elasticsearch (figura 4).

O Mastra executa internamente os seguintes passos:

1. Conversão de vetor: A pergunta do usuário, Encontre 5 filmes ou séries de TV sobre OVNIs, é convertida em uma incorporação vetorial usando o modelo openai/text-embedding-3-small da OpenAI.

2. Busca vetorial: este embedding é então usado para consultar o Elasticsearch por meio de uma busca vetorial.

3. Recuperação do resultado: o Elasticsearch retorna um conjunto de 10 filmes altamente relevantes para a consulta (ou seja, aqueles cujos vetores estão mais próximos do vetor de consulta do usuário).

4. Geração de respostas: os filmes recuperados e a pergunta original do usuário são enviados para o LLM, especificamente openai/gpt-5-nano. O LLM processa essas informações e gera uma resposta final, garantindo que o pedido do usuário por cinco resultados seja atendido.

O Agente Elasticsearch

Aqui apresentamos o código-fonte do agente Elasticsearch.

O vectorQueryTool é a ferramenta que é invocada para implementar a parte de recuperação do exemplo RAG. Ele utiliza a implementação ElasticSearchVector que a Elastic contribuiu para o Mastra.

O agente é um objeto da classe agent que utiliza o vectorQueryTool, o prompt e uma memória. Como você pode ver, o código que precisamos colocar em prática para conectar o Elasticsearch a um agente é mínimo.

Conclusão

Este artigo demonstrou a simplicidade e o poder de integrar o Elasticsearch ao framework Mastra para criar aplicações sofisticadas de IA agentiva. Especificamente, detalhamos a criação de um agente RAG capaz de realizar busca semântica em um corpus de dados de filmes de ficção científica indexados no Elasticsearch.

O principal aprendizado é a contribuição direta da Elastic para o projeto open source Mastra, fornecendo suporte nativo para o Elasticsearch como um repositório vetorial. Essa integração reduz significativamente a barreira de entrada, como demonstra o código-fonte do Elasticsearch Agent. Usando o ElasticSearchVector e createVectorQueryTool, a configuração completa para conectar o Elasticsearch ao seu agente exige apenas algumas linhas de código de configuração.

O Elasticsearch oferece vários recursos avançados para aumentar a relevância dos resultados. Por exemplo, a busca híbrida aumenta significativamente a precisão ao combinar a busca lexical com a busca vetorial. Outro recurso interessante é a reclassificação usando os modelos Jina mais recentes, que podem ser aplicados ao final da busca híbrida. Para saber mais sobre essas técnicas, consulte os seguintes artigos do Elasticsearch Labs:

• Busca híbrida do Elasticsearch por Valentin Crettaz

• Uma introdução aos modelos Jina, sua funcionalidade e seus usos no Elasticsearch por Scott Martens

Também incentivamos você a explorar o exemplo fornecido e começar a construir seus próprios agentes baseados em dados com Mastra e Elasticsearch. Para mais informações sobre o Mastra, você pode consultar a documentação oficial aqui.

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 /elastic

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.

Recentemente, contribuímos para o projeto open source Google MCP Toolbox for Databases, adicionando suporte ao Elasticsearch como banco de dados.

Com esse novo recurso, agora você pode usar o Google MCP Toolbox para se conectar ao Elasticsearch e "conversar" diretamente com seus dados.

Elasticsearch

Precisamos ter uma instância do Elasticsearch em execução. Você pode ativar uma avaliação gratuita 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 do Google MCP Toolbox.

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

Instale o conjunto de dados de exemplo

Após a instalação, você pode fazer login no Kibana usando o nome do usuário elastic e a senha gerada pelo script start-local (armazenada em um arquivo .env).

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 de comércio eletrônico. Para cada pedido, temos as seguintes informações:

• Informações do cliente (nome, ID, data de nascimento, e-mail, etc.)

• Data do pedido

• ID do pedido

• Produtos (lista de todos os produtos com preço, quantidade, ID, categoria, desconto, etc.)

• 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”. Confira os detalhes na documentação aqui: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana.

O objetivo deste artigo é mostrar como é fácil configurar o Google MCP Toolbox para se conectar ao Elasticsearch e interagir com o índice kibana_sample_data_ecommerce usando linguagem natural.

Google MCP Toolbox

O Google MCP Toolbox é um servidor MCP open source projetado para facilitar a interação de aplicações e agentes de IA com bancos de dados de forma segura e eficiente. Antes chamado de "GenAI Toolbox for Databases", o projeto foi renomeado após adotar total compatibilidade com o Protocolo de Contexto de Modelo (MCP). Seu objetivo é eliminar o trabalho pesado tradicionalmente exigido ao conectar agentes a bancos de dados, lidando com agrupamento de conexões, autenticação, observabilidade e outras preocupações operacionais nos bastidores.

Essencialmente, o Toolbox permite que desenvolvedores definam ferramentas reutilizáveis e de alto nível que encapsulam interações com bancos de dados. Essas ferramentas podem então ser invocadas por qualquer cliente que cumpra o MCP — como um agente de IA — sem exigir que o cliente implemente consultas SQL de baixo nível ou gerencie conexões de banco de dados. Essa abordagem reduz drasticamente a quantidade de código padrão necessário para construir agentes conscientes de banco de dados, tornando possível integrar operações avançadas de dados em apenas algumas linhas de lógica de aplicação. Uma vez definida uma ferramenta, ela pode ser compartilhada entre vários agentes, frameworks ou linguagens (Figura 1).

Uma grande vantagem de usar o Toolbox é o modelo de segurança integrado. Fluxos de autenticação, como OAuth2 e OIDC, são aceitos de forma nativa, permitindo que os desenvolvedores evitem manipular ou armazenar credenciais confidenciais de bancos de dados em agentes. A plataforma também fornece recursos de observabilidade, incluindo métricas e rastreamento, no OpenTelemetry, que é essencial para depuração, monitoramento e implantações de produção. No geral, o MCP Toolbox serve como uma interface unificada, segura e extensível para interagir com seus dados de qualquer sistema habilitado pelo MCP.

Como instalar o MCP Toolbox

Você pode instalar o servidor MCP Toolbox no Linux usando o seguinte comando:

Para instalá-lo no macOS ou Windows, siga as instruções detalhadas aqui.

Configure o Toolbox para Elasticsearch

Para configurar o MCP Toolbox para Elasticsearch, precisamos criar um arquivo tools.yaml , conforme segue:

Você precisa trocar o valor <insert-here-api-key> por uma chave API válida do Elasticsearch. Se você estiver rodando o Elasticsearch localmente usando o start-local, pode encontrar a chave API no arquivo .env gerado pelo start-local, sob a variável ES_LOCAL_API_KEY . Se você estiver usando o Elastic Cloud, poderá gerar uma chave de API seguindo o procedimento descrito aqui.

As ferramentas anteriores contêm a seguinte consulta ES|QL para Elasticsearch:

Se você não conhece o ES|QL, é uma linguagem de consulta desenvolvida pela Elastic, semelhante ao SQL, que pode ser usada para buscar em um ou mais índices. Saiba mais sobre ES|QL na documentação oficial aqui.

A consulta acima busca todos os pedidos armazenados no índice kibana_sample_data_ecommerce que contêm o nome do cliente especificado, usando o parâmetro ?name (o ponto de interrogação indica um parâmetro).

O nome do cliente é definido na configuração YAML anterior usando a string de tipo e a descrição "O nome do cliente".

Essa ferramenta pode ser usada para responder a perguntas sobre os pedidos de um cliente - por exemplo: Quantos pedidos o cliente Foo fez em outubro de 2025?

As descrições das ferramentas e seus parâmetros são essenciais para extrair as informações relevantes da solicitação em linguagem natural do usuário. Essa extração é realizada usando o recurso de chamada de função de um modelo de linguagem grande (LLM). Na prática, um LLM pode determinar qual função (ferramenta) precisa ser executada para obter as informações necessárias, juntamente com os parâmetros apropriados para essa função.

Para saber mais sobre chamadas de função, sugerimos o artigo Chamadas de função do OpenAI com Elasticsearch, de Ashish Tiwari.

Execute o servidor Toolbox

Você pode executar o MCP Toolbox usando o arquivo tools.yaml anterior com o seguinte comando:

O parâmetro –ui executa uma aplicação web em http://127.0.0.1:5000/ui (Figura 2).

Você pode selecionar Ferramentas > customer-orders e inserir o nome do cliente no campo Nome do parâmetro (por exemplo, Gwen Sanders) e clicar no botão Executar. Você deve ver uma resposta JSON conforme a Figura 3.

A configuração está concluída, e o MCP Toolbox pode executar a ferramenta customer-orders para se comunicar com o Elasticsearch, rodando o ES|QL.

Usando o MCP Toolbox com Gemini CLI

Podemos usar qualquer cliente MCP para nos comunicar com o MCP Toolbox for Databases. Por exemplo, podemos usar o Gemini CLI, uma ferramenta de linha de comando, para usar o Gemini. Você pode instalar o Gemini CLI seguindo as instruções descritas aqui.

Gemini CLI oferece uma extensão pré-configurada para MCP Toolbox, disponível em gemini-cli-extensions/mcp-toolbox. Você pode instalar esta extensão executando o seguinte comando:

Após a instalação, você precisa ir para o diretório em que armazenou o arquivo de configuração tools.yaml do MCP Toolbox e executar a CLI do Gemini da seguinte forma (essa etapa é necessária para que a CLI do Gemini seja configurada automaticamente com o MCP Toolbox):

Você deve ver uma saída conforme a Figura 4.

Você pode verificar se a MCP Toolbox está conectada usando o seguinte comando:

Você deve ver a mcp_toolbox com as ferramentas de pedidos de clientes listadas (Figura 5).

Se o MCP Toolbox estiver conectado à interface de comando Gemini, agora podemos tentar fazer algumas perguntas, como: "Me dê os pedidos da cliente Gwen Sanders." A CLI Gemini então solicitará permissão para executar a ferramenta de pedidos do cliente ao servidor mcp_toolbox (veja a Figura 6).

Após a confirmação, a CLI Gemini executará a solicitação para a MCP Toolbox, recebendo uma resposta JSON como resultado e usando para formatar a resposta (Figura 7).

A resposta da Gemini CLI emitirá um relatório indicando que Gewn Sanders fez apenas um pedido de 2 produtos, totalizando 132 euros.

SDKs do MCP Toolbox

O Google MCP Toolbox também oferece um SDK para acessar todas as funcionalidades de um programa escrito em Go, Python e Javascript.

Por exemplo, o Python SDK está disponível no Github na seguinte página: https://github.com/googleapis/mcp-toolbox-sdk-python.

Precisamos criar um agente simples para conectar à MCP Toolbox. Precisamos instalar os seguintes pacotes:

E crie um novo projeto de agente usando o comando a seguir:

Isso criará um novo diretório chamado my_agent com um arquivo agent.py.

Atualize my_agent/agent.py com o seguinte conteúdo para conectar ao Toolbox:

Crie um arquivo .env com sua chave API do Google:

Por fim, podemos executar o agente e observar os resultados. Para executar o agente, você pode executar o seguinte comando:

Ou pode servi-lo por meio de uma interface web:

Em ambos os casos, você pode interagir com a MCP Toolbox usando uma interface de perguntas e respostas. Por exemplo, você pode fazer a pergunta anterior: Me dê os pedidos da cliente Gwen Sanders.

Para saber mais sobre os diferentes SDKs, consulte esta página de documentação.

Conclusão

Neste artigo, demonstramos a integração com o Elasticsearch para o Google MCP Toolbox for Databases. Usando um arquivo de configuração YAML simples, podemos definir um conjunto de ferramentas que traduzem perguntas de linguagem natural em consultas do Elasticsearch usando a linguagem ES|QL.

Mostramos como interagir com os conjuntos de dados kibana_sample_data_ecommerce, que contém pedidos de um website de e-commerce. Com esse arquivo de configuração, basta executar o servidor MCP Toolbox e conectar a ele a partir de qualquer cliente MCP.

Por fim, demonstramos como usar o Gemini CLI como cliente para conectar-se ao MCP Toolbox for Databases e consultar os dados de comércio eletrônico armazenados no Elasticsearch. Executamos uma consulta em linguagem natural para obter informações sobre pedidos de um cliente específico identificado pelo nome.

À medida que o ecossistema MCP continua crescendo, esse padrão — definições leves de ferramentas apoiadas por uma infraestrutura segura e pronta para produção — gera novas oportunidades para criar agentes cada vez mais capazes e com reconhecimento de dados com o mínimo esforço. Seja experimentando localmente com os conjuntos de dados de amostra da Elastic ou integrando capacidades de buscar em uma aplicação maior, o MCP Toolbox tem uma base confiável e extensível para interagir com os dados do Elasticsearch usando linguagem natural.

Para saber mais sobre o desenvolvimento de aplicações de IA agêntica, leia o artigo Criando fluxos de trabalho de IA agêntica com Elasticsearch, de Anish Mathur e Dana Juratoni.

Para saber mais informações sobre o Google MCP Toolbox, visite https://googleapis.github.io/genai-toolbox/getting-started/introduction/.

ES|QL

ES|QL é uma nova linguagem de consulta do Elasticsearch introduzida na versão 8.11.0. Neste momento, está disponível em versão de pré-visualização técnica. Ele oferece uma maneira poderosa de filtrar, transformar e analisar dados armazenados no Elasticsearch.

Ele utiliza "pipes" (|) para manipular e transformar dados passo a passo. Essa abordagem permite aos usuários compor uma série de operações, onde o resultado de uma operação se torna a entrada para a próxima, possibilitando transformações e análises de dados complexas.

Por exemplo, a seguinte consulta retorna os 3 primeiros documentos (linhas) do índice sample_data :

Caso de uso: recursos ES|QL no cliente PHP oficial

Para ilustrar os recursos do ES|QL desenvolvidos no cliente PHP oficial, armazenamos no Elasticsearch um arquivo CSV com 81.828 livros (54,4 MB) contendo as seguintes informações:

Extraímos esta lista do conjunto de dados público de avaliações de livros da Amazon.

Criamos um índice books com os seguintes mapeamentos do Elasticsearch:

O valor rating é a média das classificações das avaliações extraídas do arquivo Books_rating.csv de 2,9 GB.

Aqui você encontra o script PHP que usamos para importar todos os livros em massa para o Elasticsearch. A operação em lote levou 7 segundos e consumiu 28 MB de RAM usando o PHP 8.2.17. Com o mapeamento proposto, o tamanho do índice no Elasticsearch é de aproximadamente 62 MB.

Mapear resultados ES|QL para um objeto PHP ou classe personalizada

Podemos executar uma consulta ES|QL em PHP usando o endpoint esql()->query() . O resultado desta consulta é uma estrutura de dados em forma de tabela. Isso é expresso em JSON usando os campos columns e values . No campo columns temos a definição name e type .

Aqui está um exemplo de consulta ES|QL para recuperar os 10 melhores livros escritos por Stephen King, ordenados pela classificação das avaliações dos usuários:

O resultado JSON do Elasticsearch tem a seguinte aparência:

Neste exemplo, temos 6 propriedades (autor, descrição, editora, classificação, título, ano) relacionadas a um livro e 10 resultados, todos livros de Stephen King.

Uma lista de todos os tipos suportados em ES|QL é apresentada aqui.

O objeto de resposta $result pode ser acessado como uma matriz, uma string ou como um objeto (veja aqui para mais informações).

Utilizando a interface de objeto, podemos acessar os valores por meio de propriedades e índices. Por exemplo, $result->values[0][4] retorna o título (4) do primeiro livro (0) da lista, $result->values[1][3] retorna a pontuação de classificação (3) do segundo livro (1), etc. Lembre-se, o índice de um array em PHP começa em zero.

Essa interface pode ser suficiente para alguns casos de uso, mas na maioria das vezes preferimos obter um array de objetos como resultado.

Para mapear o resultado em uma matriz de objetos, podemos usar o novo recurso mapTo() do elasticsearch-php.

Essa função está disponível diretamente no objeto de resposta do Elasticsearch. Isso significa que você pode acessá-lo da seguinte forma:

Se você tiver uma classe Book personalizada, poderá mapear o resultado usando-a, da seguinte forma:

Se sua classe tiver outras propriedades além das incluídas no resultado ES|QL, isso também funcionará. A função mapTo() usará apenas as propriedades retornadas como colunas do resultado ES|QL.

Você pode baixar todos os exemplos relatados neste artigo aqui.