<![CDATA[Tomás Murúa - Elasticsearch Labs]]> <![CDATA[Tomás Murúa - Elasticsearch Labs]]> https://static-www.elastic.co/v3/assets/bltefdd0b53724fa2ce/blt1121c0bf0e8a6e65/6a88da6340a1841030ef456f/search-labs-thumbnail.png https://www.elastic.co/pt/search-labs/author/tomas-murua https://www.elastic.co/pt/search-labs/author/tomas-murua Mon, 21 Sep 2026 02:51:27 GMT <![CDATA[Criar um conector do ChatGPT com o Elasticsearch para consultar problemas no GitHub]]> Recentemente, a OpenAI anunciou o recurso de conectores personalizados para o ChatGPT nos planos Pro/Business/Empresarial e Edu. Além dos conectores prontos para uso para acessar dados no Gmail, GitHub, Dropbox etc. É possível criar conectores personalizados usando servidores MCP.

Os conectores personalizados permitem que você combine seus conectores ChatGPT existentes com fontes adicionais de dados, como o Elasticsearch, para obter respostas abrangentes.

Neste artigo, criaremos um servidor MCP que conecta o ChatGPT a um índice Elasticsearch contendo informações sobre problemas internos e solicitações de pull do GitHub. Isso permite que consultas em linguagem natural sejam respondidas usando os dados do seu Elasticsearch.

Implantaremos o servidor MCP usando o FastMCP no Google Colab com ngrok para obter um URL público ao qual o ChatGPT possa se conectar, eliminando a necessidade de uma configuração de infraestrutura complexa.

Para uma visão geral do MCP e seu ecossistema, consulte O Estado Atual do MCP.

Pré-requisitos

Antes de começar, você precisará de:

  • Cluster do Elasticsearch (8.X ou superior)

  • Chave de API do Elasticsearch com acesso de leitura ao seu índice

  • Conta do Google (para o Google Colab)

  • Conta Ngrok (versão gratuita funciona)

  • Conta do ChatGPT com plano Pro/Empresarial/Business ou Edu

Entendendo os requisitos do conector MCP do ChatGPT

Os conectores MCP do ChatGPT exigem a implementação de duas ferramentas: search e fetch. Para mais detalhes, consulte OpenAI Docs.

Ferramenta de busca

Retorna uma lista de resultados relevantes do seu índice Elasticsearch com base em uma consulta do usuário.

O que ele recebe:

  • Uma única string com a consulta de linguagem natural do usuário.

  • Exemplo: "Encontre problemas relacionados à migração do Elasticsearch."

O que ele retorna: 

  • Um objeto com uma chave result contendo um array de objetos de resultado. Cada resultado inclui:

    • id - Identificador único do documento

    • title - Título da issue ou do PR

    • url - Link para o problema/PR

Na nossa implementação:

return { "results": [ { "id": "PR-612", "title": "Fix memory leak in WebSocket notification service", "url": "https://internal-git.techcorp.com/pulls/612" }, # ... more results ] }

Ferramenta de recuperação

Recupera o conteúdo completo de um documento específico.

O que ele recebe:

  • Uma única string com o ID do documento Elasticsearch do resultado de busca

  • Exemplo: "Me dê os detalhes do PR-578."

O que ele retorna:

  • Um objeto de documento completo com:

    • id - Identificador único do documento

    • title - Título da issue ou do PR

    • text - Complete a descrição e os detalhes do problema/PR

    • url - Link para o problema/PR

    • type - Tipo de documento (issue, pull_request)

    • status - Status atual (aberto, em_andamento, resolvido)

    • priority - Nível de prioridade (baixo, médio, alto, crítico)

    • assignee - Pessoa designada para o problema/PR

    • created_date - Quando foi criado

    • resolved_date - Quando foi resolvido (se aplicável)

    • labels - Tags associadas ao documento

    • related_pr - ID de pull request relacionado

return { "id": "PR-578", "title": "Security hotfix: Patch SQL injection vulnerabilities", "text": "Description: CRITICAL SECURITY FIX for ISSUE-1889. Patches SQL...", "url": "https://internal-git.techcorp.com/pulls/578", "type": "pull_request", "status": "closed", "priority": "critical", "assignee": "sarah_dev", "created_date": "2025-09-19", "resolved_date": "2025-09-19", "labels": "security, hotfix, sql", "related_pr": null }

Observação: este exemplo usa uma estrutura plana onde todos os campos estão no nível raiz. Os requisitos do OpenAI são flexíveis e também permitem objetos de metadados aninhados.

Questões do GitHub e conjunto de dados PRs

Para este tutorial, vamos usar um conjunto de dados interno do GitHub contendo problemas e solicitações de pull. Isso representa um cenário em que você deseja consultar dados privados e internos por meio do ChatGPT.

O conjunto de dados pode ser encontrado aqui. E atualizaremos o índice dos dados usando a bulk API.

Esse conjunto de dados inclui:

  • Problemas com descrições, status, prioridade e responsáveis

  • Solicitações de pull com alterações de código, revisões e informações de implantação

  • Relações entre problemas e PRs (por exemplo, PR-578 corrige o ISSUE-1889)

  • Rótulos, datas e outros metadados

Mapeamentos de índice

O índice usa os seguintes mapeamentos para permitir a pesquisa híbrida com o ELSER. A text_semantic é usada para busca semântica, enquanto outros campos permitem a busca por palavras-chave.

{ "mappings": { "properties": { "id": { "type": "keyword" }, "title": { "type": "text" }, "text": { "type": "text" }, "text_semantic": { "type": "semantic_text", "inference_id": ".elser-2-elasticsearch" }, "url": { "type": "keyword" }, "type": { "type": "keyword" }, "status": { "type": "keyword" }, "priority": { "type": "keyword" }, "assignee": { "type": "keyword" }, "created_date": { "type": "date", "format": "iso8601" }, "resolved_date": { "type": "date", "format": "iso8601" }, "labels": { "type": "keyword" }, "related_pr": { "type": "keyword" } } } }

Construa o servidor MCP

Nosso servidor MCP implementa duas ferramentas seguindo as especificações da OpenAI, usando busca híbrida para combinar correspondência semântica e de texto para obter melhores resultados.

Ferramenta de busca

Utiliza busca híbrida com RRF (Reciprocal Rank Fusion), combinando buscar semântica com correspondência de texto:

@mcp.tool() async def search(query: str) -> Dict[str, List[Dict[str, Any]]]: """ Search for internal issues and PRs using hybrid search (semantic + text with RRF). Returns list with id, title, and url per OpenAI spec. """ if not query or not query.strip(): return {"results": []} logger.info(f"Searching for: '{query}'") try: # Hybrid search with RRF (Reciprocal Rank Fusion) response = es_client.search( index=ELASTICSEARCH_INDEX, size=10, source=["id", "title", "url", "type", "priority"], retriever={ "rrf": { "retrievers": [ { # Semantic search with ELSER "standard": { "query": { "semantic": { "field": "text_semantic", "query": query } } } }, { # Text search (BM25) for keyword matching "standard": { "query": { "multi_match": { "query": query, "fields": [ "title^3", "text^2", "assignee^2", "type", "labels", "priority" ], "type": "best_fields", "fuzziness": "AUTO" } } } } ], "rank_window_size": 50, "rank_constant": 60 } } ) results = [] if response and 'hits' in response: for hit in response['hits']['hits']: source = hit['_source'] results.append({ "id": source.get('id', hit['_id']), "title": source.get('title', 'Unknown'), "url": source.get('url', '') }) logger.info(f"Found {len(results)} results") return {"results": results} except Exception as e: logger.error(f"Search error: {e}") raise ValueError(f"Search failed: {str(e)}")

Pontos principais:

  • Busca híbrida com RRF: combina busca semântica (ELSER) e busca por texto (BM25) para melhores resultados.

  • Consulta multi-correspondência: busca em múltiplos campos com aumento de relevância (title^3, text^2, assignee^2). O símbolo de caret (^) multiplica as pontuações de relevância, priorizando as correspondências nos títulos em detrimento do conteúdo.

  • Correspondência inexata: fuzziness: AUTO lida com erros de digitação e ortografia, permitindo correspondências aproximadas.

  • Ajuste dos parâmetros do RRF:

    • rank_window_size: 50 - Especifica quantos resultados principais de cada recuperador (semântico e textual) são considerados antes da mesclagem.

    • rank_constant: 60 - Esse valor determina quanta influência os documentos em conjuntos de resultados individuais têm sobre o resultado final classificado.

  • Retorna somente os campos obrigatórios: id, title, url de acordo com a especificação da OpenAI e evita a exposição desnecessária de campos adicionais.

Ferramenta de recuperação

Recupera detalhes do documento pelo ID do documento, quando existe:

@mcp.tool() async def fetch(id: str) -> Dict[str, Any]: """ Retrieve complete issue/PR details by ID. Returns id, title, text, url. """ if not id: raise ValueError("ID is required") logger.info(f"Fetching: {id}") try: # Search by the 'id' field (not _id) since IDs are stored as a field response = es_client.search( index=ELASTICSEARCH_INDEX, body={ "query": { "term": { "id": id # Search by your custom 'id' field } }, "size": 1 } ) if not response or not response['hits']['hits']: raise ValueError(f"Document with id '{id}' not found") hit = response['hits']['hits'][0] source = hit['_source'] result = { "id": source.get('id', id), "title": source.get('title', 'Unknown'), "text": source.get('text', ''), "url": source.get('url', ''), "type": source.get('type', ''), "status": source.get('status', ''), "priority": source.get('priority', ''), "assignee": source.get('assignee', ''), "created_date": source.get('created_date', ''), "resolved_date": source.get('resolved_date', ''), "labels": source.get('labels', ''), "related_pr": source.get('related_pr', '') } logger.info(f"Fetched: {result['title']}") return result except Exception as e: logger.error(f"Fetch error: {e}") raise ValueError(f"Failed to fetch '{id}': {str(e)}")

Pontos principais:

  • Buscar por campo de ID do documento: Utiliza consulta de termo no campo personalizado id

  • Retorna o documento completo: inclui o campo text completo com todo o conteúdo

  • Estrutura plana: Todos os campos no nível da raiz, correspondendo à estrutura de documentos do Elasticsearch.

Implantar no Google Colab

Usaremos o Google Colab para executar nosso servidor MCP e o ngrok para expô-lo publicamente, permitindo que o ChatGPT se conecte a ele.

Etapa 1: Abra o notebook do Google Colab

Acesse nosso notebook pré-configurado Elasticsearch MCP para ChatGPT.

Etapa 2: Configure suas credenciais

Você precisará de três informações:

  • URL do Elasticsearch: seu URL do cluster do Elasticsearch.

  • Chave da API do Elasticsearch: Chave da API com permissão de leitura do seu índice.

  • Token de autenticação Ngrok: token grátis do ngrok. Vamos usar o ngrok para expor a URL do MCP à internet para que o ChatGPT possa se conectar a ela.

Obter seu token ngrok

  1. Cadastre-se para uma conta gratuita em ngrok

  2. Acesse seu painel do ngrok

  3. Copie seu token de autenticação.

Adicionando segredos ao Google Colab

No notebook do Google Colab:

  1. Clique no ícone de chave na barra lateral esquerda para abrir Secrets.

  2. Adicione estes três segredos:

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443 ELASTICSEARCH_API_KEY=your-api-key NGROK_TOKEN=your-ngrok-token

3. Habilitar o acesso ao notebook para cada segredo

Adicionar segredos ao Google Collab

Passo 3: Execute o notebook

  1. Clique em Runtime e depois em Executar tudo para executar todas as células

  2. Aguarde o servidor iniciar (cerca de 30 segundos)

  3. Procure a saída mostrando seu URL público do ngrok

4. A saída exibirá algo como:

A saída da execução de um notebook no Google Collab

Conectar-se ao ChatGPT

Agora vamos conectar o servidor MCP à sua conta do ChatGPT.

  1. Abra o ChatGPT e vá para Configurações.

  2. Navegue até Conectores. Se você estiver usando uma conta Pro, precisará ativar o modo de desenvolvedor nos conectores.

Conectando o servidor MPC a uma conta do ChatGPT

Se você está usando o ChatGPT em empresas ou negócios, precisa disponibilizar o conector para seu local de trabalho.

3. Clique em Criar.

Adicionando um conector ao ChatGPT

Observação: nos espaços de trabalho Business, Empresarial e Edu, somente os proprietários, administradores e usuários com a respectiva configuração ativada (para Empresarial/Edu) podem adicionar conectores personalizados. Usuários com a função de membro padrão não têm permissão para adicionar conectores personalizados.

Após um conector ser adicionado e habilitado por um proprietário ou usuário administrador, ele fica disponível para todos os membros do espaço de trabalho.

4. Insira as informações necessárias e sua URL ngrok que termina em /sse/. Repare no "/" após "sse". Não vai funcionar sem ele:

  • Nome: Elasticsearch MCP

  • Descrição: MCP personalizado para pesquisar e recuperar informações internas do GitHub.

Criar um Conector MCP Elastic

5. Pressione Criar para salvar o MCP personalizado.

Salvar o conector MCP personalizado clicando em criar

A conexão será instantânea se seu servidor estiver em execução. Não é necessária autenticação adicional, pois a chave da API do Elasticsearch está configurada no seu servidor.

Teste o servidor MCP

Antes de fazer perguntas, você precisa selecionar qual conector o ChatGPT deve usar.

Selecionar qual conector o ChatGPT deve usar

Prompt 1: Buscar por problemas

Pergunte: "Encontre problemas relacionados à migração do Elasticsearch" e confirme a chamada da ferramenta de ações.

Peça ao ChatGPT "Encontre problemas relacionados à migração do Elasticsearch" e confirme a chamada da ferramenta de ações.

O ChatGPT chamará a ferramenta search com sua consulta. Você pode ver que ele está procurando as ferramentas disponíveis, se preparando para chamar a ferramenta Elasticsearch e confirma com o usuário antes de tomar qualquer medida em relação à ferramenta.

Solicitação de chamada de ferramenta:

{ "query": "Elasticsearch migration issues" }

Resposta da ferramenta:

{ "results": [ { "id": "PR-598", "title": "Elasticsearch 8.x migration - Application code changes", "url": "https://internal-git.techcorp.com/pulls/598" }, { "id": "ISSUE-1712", "title": "Migrate from Elasticsearch 7.x to 8.x", "url": "https://internal-git.techcorp.com/issues/1712" }, { "id": "RFC-045", "title": "Design Proposal: Microservices Migration Architecture", "url": "https://internal-git.techcorp.com/rfcs/045" } // ... 7 more results ] }

O ChatGPT processa os resultados e os apresenta em um formato natural e conversacional.

Como o ChatGPT processa os resultados da solicitação de chamada da ferramenta e da resposta à chamada da ferramenta

Nos bastidores

Prompt: "Encontrar problemas relacionados à migração do Elasticsearch"

1. Chamadas do ChatGPT search(“Elasticsearch migration”)

2. O Elasticsearch realiza uma busca híbrida

  • A busca semântica compreende conceitos como "atualização" e "compatibilidade de versões".

  • A busca de texto encontra correspondências exatas para "Elasticsearch" e "migração".

  • O RRF combina e classifica os resultados de ambas as abordagens

3. Retorna os 10 melhores eventos de correspondência com id, title, url

4. O ChatGPT identifica "ISSUE-1712: migrar do Elasticsearch 7.x para o 8.x" como o resultado mais relevante

Prompt 2: Obter todos os detalhes

Perguntar: "Informe detalhes sobre o ISSUE-1889"

O ChatGPT reconhece que você quer informações detalhadas sobre um problema específico, aciona a ferramenta fetch e confirma com o usuário antes de tomar qualquer medida em relação à ferramenta.

O ChatGPT reconhece que você quer informações detalhadas sobre um problema específico e aciona a ferramenta fetch, confirmando com o usuário antes de tomar qualquer medida em relação à ferramenta.

Solicitação de chamada de ferramenta:

{ "id": "ISSUE-1889" }

Resposta da ferramenta:

{ "id": "ISSUE-1889", "title": "SQL injection vulnerability in search endpoint", "text": "Description: Security audit identified SQL injection vulnerability in /api/v1/search endpoint. User input from query parameter is not properly sanitized before being used in raw SQL query. Severity: HIGH - Immediate action required Affected Code: - File: services/search/query_builder.py - Line: 145-152 - Issue: String concatenation used instead of parameterized queries Investigation: - @security_team_alice: Confirmed exploitable with UNION-based injection - @sarah_dev: Checking all other endpoints for similar patterns - @john_backend: Found 3 more instances in legacy codebase Remediation: - Rewrite using SQLAlchemy ORM or parameterized queries - Add input validation and sanitization - Implement WAF rules as additional layer - Security regression tests Comments: - @tech_lead_mike: Stop all other work, this is P0 - @sarah_dev: PR-578 ready with fixes for all 4 vulnerable endpoints - @alex_devops: Deployed hotfix to production 2025-09-19 at 14:30 UTC - @security_team_alice: Verified fix, conducting full pentest next week Resolution: All vulnerable endpoints patched. Added pre-commit hooks to catch raw SQL queries. Security training scheduled for team.", "url": "https://internal-git.techcorp.com/issues/1889", "type": "issue", "status": "closed", "priority": "critical", "assignee": "sarah_dev", "created_date": "2025-09-18", "resolved_date": "2025-09-19", "labels": "security, vulnerability, bug, sql", "related_pr": "PR-578" }

O ChatGPT sintetiza as informações e as apresenta claramente.

Como o ChatGPT sintetiza as informações e as apresenta Como o ChatGPT apresenta as informações

Nos bastidores

Prompt: “Informe mais detalhes sobre ISSUE-1889”

  1. Chamadas do ChatGPT fetch(“ISSUE-1889”)

  2. O Elasticsearch recupera o documento completo

  3. Retorna um documento completo com todos os campos no nível raiz

  4. O ChatGPT sintetiza as informações e responde com citações adequadas.

Conclusão

Neste artigo, criamos um servidor MCP personalizado que conecta o ChatGPT ao Elasticsearch usando ferramentas MCP dedicadas de busca e recuperação, permitindo consultas em linguagem natural sobre dados privados.

Este padrão MCP funciona para qualquer índice Elasticsearch, documentação, produtos, log ou quaisquer outros dados que você queira consultar por meio de linguagem natural.

]]> https://www.elastic.co/search-labs/blog/chatgpt-connector-mcp-server-github-elasticsearch https://www.elastic.co/search-labs/blog/chatgpt-connector-mcp-server-github-elasticsearch Mon, 01 Dec 2025 00:00:00 GMT <![CDATA[Criando um agente de IA para RH com Elastic Agent Builder e GPT-OSS]]> Introdução

Este artigo mostrará como criar um agente de IA para RH usando GPT-OSS e Elastic Agent Builder. O agente pode responder às suas perguntas sem enviar dados para a OpenAI, Anthropic ou qualquer serviço externo.

Usaremos o LM Studio para disponibilizar o GPT-OSS localmente e conectá-lo ao Elastic Agent Builder.

Ao final deste artigo, você terá um agente de IA personalizado capaz de responder a perguntas em linguagem natural sobre os dados de seus funcionários, mantendo o controle total sobre suas informações e modelo.

Pré-requisitos

Para ler este artigo, você precisa de:

Por que usar GPT-OSS?

Com um LLM local, você tem o controle para implantá-lo em sua própria infraestrutura e ajustá-lo para atender às suas necessidades específicas. Tudo isso mantendo o controle sobre os dados que você compartilha com o modelo e, claro, sem precisar pagar nenhuma taxa de licença a um fornecedor externo.

A OpenAI lançou o GPT-OSS em 5 de agosto de 2025, como parte de seu compromisso com o ecossistema de modelos abertos.

O modelo de parâmetros 20B oferece:

  • capacidades de utilização da ferramenta

  • Inferência eficiente

  • Compatível com o SDK OpenAI

  • Compatível com fluxos de trabalho agentes

Comparação de referência:

Arquitetura da solução

A arquitetura é executada inteiramente em sua máquina local. O Elastic (executado em um contêiner Docker) se comunica diretamente com seu LLM local por meio do LM Studio, e o Elastic Agent Builder usa essa conexão para criar agentes de IA personalizados que podem consultar os dados de seus funcionários.

Para obter mais detalhes, consulte esta documentação.

Construindo um agente de IA para RH: Etapas

Dividiremos a implementação em 5 etapas:

  1. Configure o LM Studio com um modelo local.

  2. Implante o Elastic local com o Docker.

  3. Crie o conector OpenAI no Elastic

  4. Carregar dados de funcionários no Elasticsearch

  5. Crie e teste seu agente de IA.

Etapa 1: Configurar o LM Studio com GPT-OSS 20B

O LM Studio é um aplicativo fácil de usar que permite executar grandes modelos de linguagem localmente em seu computador. Ele fornece um servidor de API compatível com OpenAI, facilitando a integração com ferramentas como o Elastic, sem um processo de configuração complexo. Para obter mais detalhes, consulte a documentação do LM Studio.

Primeiro, baixe e instale o LM Studio a partir do site oficial. Após a instalação, abra o aplicativo.

Na interface do LM Studio:

  1. Acesse a aba de pesquisa e procure por “GPT-OSS”.

  2. Selecione o openai/gpt-oss-20b da OpenAI

  3. Clique em baixar

O tamanho deste modelo deverá ser de aproximadamente 12,10 GB. O download pode demorar alguns minutos, dependendo da sua conexão com a internet.

Após o download do modelo:

  1. Acesse a aba do servidor local.

  2. Selecione o openai/gpt-oss-20b

  3. Use a porta padrão 1234

  4. No painel direito, acesse Carregar e defina o Comprimento do Contexto para 40K ou mais.

5. Clique em Iniciar servidor

Você deverá ver isso se o servidor estiver em execução.

[LM STUDIO SERVER] Success! HTTP server listening on port 1234 [LM STUDIO SERVER] Supported endpoints: [LM STUDIO SERVER] -> GET http://localhost:1234/v1/models [LM STUDIO SERVER] -> POST http://localhost:1234/v1/responses [LM STUDIO SERVER] -> POST http://localhost:1234/v1/chat/completions [LM STUDIO SERVER] -> POST http://localhost:1234/v1/completions [LM STUDIO SERVER] -> POST http://localhost:1234/v1/embeddings Server started.

Etapa 2: Implante o Elastic local com o Docker

Agora vamos configurar o Elasticsearch e o Kibana localmente usando o Docker. A Elastic fornece um script prático que lida com todo o processo de configuração. Para obter mais detalhes, consulte a documentação oficial.

Execute o script start-local

Execute o seguinte comando no seu terminal:

curl -fsSL https://elastic.co/start-local | sh

Este script irá:

  • Baixe e configure o Elasticsearch e o Kibana.

  • Inicie ambos os serviços usando o Docker Compose.

  • Ative automaticamente uma licença de avaliação Platinum de 30 dias.

Resultado esperado

Aguarde a seguinte mensagem e salve a senha e a chave da API exibidas; você precisará delas para acessar o Kibana:

🎉 Congrats, Elasticsearch and Kibana are installed and running in Docker! 🌐 Open your browser at http://localhost:5601 Username: elastic Password: KSUlOMNr 🔌 Elasticsearch API endpoint: http://localhost:9200 🔑 API key: cnJGX0pwb0JhOG00cmNJVklUNXg6cnNJdXZWMnM4bncwMllpQlFlUTlWdw== Learn more at https://github.com/elastic/start-local

Acesse o Kibana

Abra seu navegador e acesse:

http://localhost:5601

Faça login utilizando as credenciais obtidas na saída do terminal.

Habilitar o Construtor de Agentes

Após fazer login no Kibana, navegue até Gerenciamento > IA > Construtor de Agentes e ative o Construtor de Agentes.

Etapa 3: Crie o conector OpenAI no Elastic

Agora vamos configurar o Elastic para usar seu LLM local.

Conectores de acesso

  1. Em Kibana

  2. Acesse Configurações do projeto > Gerenciamento

  3. Em Alertas e insights, selecione Conectores.

  4. Clique em Criar conector

Configure o conector

Selecione OpenAI na lista de conectores. O LM Studio utiliza o SDK da OpenAI, o que o torna compatível.

Preencha os campos com estes valores:

  • Nome do conector: LM Studio - GPT-OSS 20B

  • Selecione um provedor OpenAI: Outro (Serviço compatível com OpenAI)

  • URL: http://host.docker.internal:1234/v1/chat/completions

  • Modelo padrão: openai/gpt-oss-20b

  • Chave da API: testkey-123 (qualquer texto funciona, pois o LM Studio Server não requer autenticação).

Para finalizar a configuração, clique em Salvar e testar.

Importante: Ative a opção “Habilitar chamada de função nativa”; isso é necessário para que o Construtor de Agentes funcione corretamente. Se você não habilitar isso, você receberá um erro No tool calls found in the response .

Teste a conexão

O Elastic deve testar a conexão automaticamente. Se tudo estiver configurado corretamente, você verá uma mensagem de sucesso como esta:

Resposta.

{ "status": "ok", "data": { "id": "chatcmpl-flj9h0hy4wcx4bfson00an", "object": "chat.completion", "created": 1761189456, "model": "openai/gpt-oss-20b", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello! 👋 How can I assist you today?", "reasoning": "Just greet.", "tool_calls": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 69, "completion_tokens": 23, "total_tokens": 92 }, "stats": {}, "system_fingerprint": "openai/gpt-oss-20b" }, "actionId": "ee1c3aaf-bad0-4ada-8149-118f52dad757" }

Etapa 4: Carregar os dados dos funcionários no Elasticsearch

Agora vamos carregar o conjunto de dados de funcionários de RH para demonstrar como o agente trabalha com dados confidenciais. Eu gerei um conjunto de dados fictício com essa estrutura.

Estrutura do conjunto de dados

{ "employee_id": "0f4dce68-2a09-4cb1-b2af-6bcb4821539b", "full_name": "Daffi Stiebler", "email": "lscutchings0@huffingtonpost.com", "date_of_birth": "1975-06-20T15:39:36Z", "hire_date": "2025-07-28T00:10:45Z", "job_title": "Physical Therapy Assistant", "department": "HR", "salary": "108455", "performance_rating": "Needs Improvement", "years_of_experience": 2, "skills": "Java", "education_level": "Master's Degree", "manager": "Carl MacGibbon", "emergency_contact": "Leigha Scutchings", "home_address": "5571 6th Park" }

Criar o índice com mapeamentos

Primeiro, crie o índice com os mapeamentos adequados. Observe que estamos usando campos semantic_text para alguns campos-chave; isso possibilita recursos de busca semântica em nosso índice.

​​PUT hr-employees { "mappings": { "properties": { "@timestamp": { "type": "date" }, "employee_id": { "type": "keyword" }, "full_name": { "type": "text", "copy_to": "employee_semantic" }, "email": { "type": "keyword" }, "date_of_birth": { "type": "date", "format": "iso8601" }, "hire_date": { "type": "date", "format": "iso8601" }, "job_title": { "type": "text", "copy_to": "employee_semantic" }, "department": { "type": "text", "copy_to": "employee_semantic" }, "salary": { "type": "double" }, "performance_rating": { "type": "text", "copy_to": "employee_semantic" }, "years_of_experience": { "type": "long" }, "skills": { "type": "text", "copy_to": "employee_semantic" }, "education_level": { "type": "text", "copy_to": "employee_semantic" }, "manager": { "type": "text", "copy_to": "employee_semantic" }, "emergency_contact": { "type": "keyword" }, "home_address": { "type": "keyword" }, "employee_semantic": { "type": "semantic_text" } } } }

Indexar com API em lote

Copie e cole o conjunto de dados nas suas Ferramentas de Desenvolvedor no Kibana e execute-o:

POST hr-employees/_bulk {"index": {}} {"employee_id": "57728b91-e5d7-4fa8-954a-2384040d3886", "full_name": "Filide Gane", "email": "vhallahan1@booking.com", "job_title": "Business Systems Development Analyst", "department": "Marketing", "salary": "$52330.27", "performance_rating": "Meets Expectations", "years_of_experience": 12, "skills": "Java", "education_level": "Bachelor's Degree", "date_of_birth": "2000-02-07T16:49:32Z", "hire_date": "2023-11-07T13:03:16Z", "manager": "Freedman Kings", "emergency_contact": "Vilhelmina Hallahan", "home_address": "75 Dennis Junction"} {"index": {}} {"employee_id": "...", ...}

Verifique os dados

Execute uma consulta para verificar:

GET hr-employees/_search

Etapa 5: Crie e teste seu agente de IA

Com tudo configurado, é hora de criar um agente de IA personalizado usando o Elastic Agent Builder. Para obter mais detalhes, consulte a documentação da Elastic.

Adicione o conector

Antes de podermos criar nosso novo agente, precisamos configurar nosso construtor de agentes para usar nosso conector personalizado chamado LM Studio - GPT-OSS 20B , porque o padrão é o Elastic Managed LLM. Para isso, precisamos acessar Configurações do Projeto > Gerenciamento > Configurações do GenAI; agora selecionamos a que criamos e clicamos em Salvar.

Construtor de Agentes de Acesso

  1. Acesse a seção de Agentes.

  2. Clique em Criar um novo agente

Configure o agente

Para criar um novo agente, os campos obrigatórios são o ID do Agente, o Nome de Exibição e as Instruções de Exibição.

Mas existem mais opções de personalização, como as Instruções Personalizadas, que orientam o comportamento do seu agente e a forma como ele interagirá com as suas ferramentas, de forma semelhante a um prompt do sistema, mas para o nosso agente personalizado. As etiquetas ajudam a organizar seus agentes, a cor do avatar e o símbolo do avatar.

Os agentes que escolhi para o nosso agente, com base no conjunto de dados, são: ID do agente: hr_assistant

Instruções personalizadas:

You are an HR Analytics Assistant that helps answer questions about employee data. When responding to queries: - Provide clear, concise answers - Include relevant employee details (name, department, salary, skills) - Format monetary values with currency symbols - Be professional and maintain data confidentiality

Rótulos: Human Resources e GPT-OSS

Nome de exibição: HR Analytics Assistant

Descrição da tela:

A specialized AI assistant for Human Resources that helps analyze employee data, compensation, performance metrics, and talent management. Ask questions about employees, departments, salaries, or performance analytics.

Com todos os dados inseridos, podemos clicar em Salvar nosso novo agente.

Teste o agente

Agora você pode fazer perguntas em linguagem natural sobre os dados de seus funcionários, e o GPT-OSS 20B entenderá a intenção e gerará uma resposta apropriada.

Incitar:

Which employee is the one with the highest salary in the hr-employees index?

Responder:

O processo do Agente foi o seguinte:

1. Compreenda sua pergunta usando o conector GPT-OSS.

2. Gere a consulta Elasticsearch apropriada (usando as ferramentas integradas ou ES|QL personalizado).

3. Recuperar registros de funcionários correspondentes

4. Apresentar os resultados em linguagem natural com formatação adequada.

Diferentemente da busca lexical tradicional, o agente baseado em GPT-OSS entende a intenção e o contexto, facilitando a localização de informações sem a necessidade de conhecer os nomes exatos dos campos ou a sintaxe da consulta. Para obter mais detalhes sobre o processo de pensamento do agente, consulte este artigo.

Conclusão

Neste artigo, criamos um agente de IA personalizado usando o Agent Builder da Elastic para conectar-se ao modelo GPT-OSS da OpenAI em execução localmente. Ao implantar o Elastic e o LLM em sua máquina local, essa arquitetura permite que você aproveite os recursos de IA generativa, mantendo o controle total sobre seus dados, tudo isso sem enviar informações para serviços externos.

Utilizamos o GPT-OSS 20B como experimento, mas os modelos oficialmente recomendados para o Elastic Agent Builder podem ser consultados aqui. Se você precisar de recursos de raciocínio mais avançados, existe também a variante com 120 parâmetros , que apresenta melhor desempenho em cenários complexos, embora exija uma máquina com especificações mais altas para ser executada localmente. Para obter mais detalhes, consulte a documentação oficial da OpenAI.

]]> https://www.elastic.co/search-labs/blog/build-an-ai-agent-hr-elastic-agent-builder-gpt-oss https://www.elastic.co/search-labs/blog/build-an-ai-agent-hr-elastic-agent-builder-gpt-oss Wed, 26 Nov 2025 00:00:00 GMT <![CDATA[Painéis de controle com inteligência artificial: da visão ao Kibana]]> O Kibana Lens torna o arrastar e soltar de dashboards muito simples, mas quando você precisa de dezenas de painéis, o número de cliques aumenta. E se você pudesse esboçar um painel de controle, tirar uma captura de tela e deixar um profissional de Direito concluir todo o processo para você?

Neste artigo, vamos fazer isso acontecer. Criaremos um aplicativo que captura uma imagem de um painel, analisa nossos mapeamentos e, em seguida, gera um painel sem que precisemos usar o Kibana!

Passos:

  1. Contexto e fluxo de trabalho do aplicativo

  2. Preparar dados

  3. Configuração LLM

  4. Funções do aplicativo

Contexto e fluxo de trabalho do aplicativo

A primeira ideia que me veio à mente foi deixar o LLM gerar todo o formato NDJSON dos objetos salvos pelo Kibana e, em seguida, importá-los para o Kibana.

Experimentamos alguns modelos:

  • Gemini 2.5 pro

  • GPT o3 / o4-mini-high / 4.1

  • Soneto 4 de Claude

  • Grok 3

  • Deepseek (Deepthink R1)

E para as sugestões, começamos com algo tão simples quanto:

You are an Elasticsearch Saved-Object generator (Kibana 9.0). INPUTS ===== 1. PNG screenshot of a 4-panel dashboard (attached). 2. Index mapping (below) – trimmed down to only the fields present in the screenshot. 3. Example NDJSON of *one* metric visualization (below) for reference. TASK ==== Return **only** a valid NDJSON array that recreates the dashboard exactly: * 2 metric panels (Visits, Unique Visitors) * 1 pie chart (Most used OS) * 1 vertical bar chart (State Geo Dest) * Use index pattern `kibana_sample_data_logs`. * Preserve roughly the same layout (2×2 grid). * Use `panelIndex` values 1-4 and random `id` strings. * Kibana version: 9.0

Apesar de termos analisado poucos exemplos e explicações detalhadas sobre como construir cada visualização, não tivemos sucesso. Se você estiver interessado nessa experiência, pode encontrar detalhes aqui.

O resultado com essa abordagem foi a visualização dessas mensagens ao tentar carregar os arquivos produzidos pelo LLM no Kibana:

Isso significa que o JSON gerado é inválido ou está mal formatado. Os problemas mais comuns foram o LLM produzir NDJSON incompleto, apresentar parâmetros incorretos ou retornar JSON comum em vez de NDJSON, independentemente de quanto nos esforçássemos para forçar o contrário.

Inspirados por este artigo – onde os modelos de pesquisa funcionaram melhor do que o método freestyle do LLM – decidimos fornecer modelos ao LLM em vez de solicitar a geração do arquivo NDJSON completo e, em seguida, usar os parâmetros fornecidos pelo LLM no código para criar as visualizações adequadas. Essa abordagem não decepcionou, além de ser previsível e extensível, já que agora o código realiza o trabalho pesado, e não o LLM.

O fluxo de trabalho da aplicação será o seguinte:

Para simplificar, omitiremos parte do código, mas você pode encontrar o código funcional da aplicação completa neste notebook.

Pré-requisitos

Antes de começar o desenvolvimento, você precisará do seguinte:

  1. Python 3.8 ou superior

  2. Um ambiente Python Venv

  3. Uma instância do Elasticsearch em execução, juntamente com seu endpoint e chave de API.

  4. Uma chave de API da OpenAI armazenada na variável de ambiente com o nome OPENAI_API_KEY:

export OPENAI_API_KEY="your-openai-api-key"

Preparar dados

Para os dados, vamos manter a simplicidade e usar os logs de amostra da Elastic. Você pode aprender como importar esses dados para o seu cluster aqui.

Cada documento inclui detalhes sobre o host que enviou as solicitações ao aplicativo, juntamente com informações sobre a própria solicitação e seu status de resposta. Segue abaixo um exemplo de documento:

{ "agent": "Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24", "bytes": 8509, "clientip": "70.133.115.149", "extension": "css", "geo": { "srcdest": "US:IT", "src": "US", "dest": "IT", "coordinates": { "lat": 38.05134111, "lon": -103.5106908 } }, "host": "cdn.elastic-elastic-elastic.org", "index": "kibana_sample_data_logs", "ip": "70.133.115.149", "machine": { "ram": 5368709120, "os": "osx" }, "memory": null, "message": "70.133.115.149 - - [2018-08-30T23:35:31.492Z] \"GET /styles/semantic-ui.css HTTP/1.1\" 200 8509 \"-\" \"Mozilla/5.0 (X11; Linux i686) AppleWebKit/534.24 (KHTML, like Gecko) Chrome/11.0.696.50 Safari/534.24\"", "phpmemory": null, "referer": "http://twitter.com/error/john-phillips", "request": "/styles/semantic-ui.css", "response": 200, "tags": [ "success", "info" ], "@timestamp": "2025-07-03T23:35:31.492Z", "url": "https://cdn.elastic-elastic-elastic.org/styles/semantic-ui.css", "utc_time": "2025-07-03T23:35:31.492Z", "event": { "dataset": "sample_web_logs" }, "bytes_gauge": 8509, "bytes_counter": 51201128 }

Agora, vamos obter os mapeamentos do índice que acabamos de carregar, kibana_sample_data_logs:

INDEX_NAME = "kibana_sample_data_logs" es_client = Elasticsearch( [os.getenv("ELASTICSEARCH_URL")], api_key=os.getenv("ELASTICSEARCH_API_KEY"), ) result = es_client.indices.get_mapping(index=INDEX_NAME) index_mappings = result[list(result.keys())[0]]["mappings"]["properties"]

Vamos passar os mapeamentos junto com a imagem que carregaremos posteriormente.

Configuração LLM

Vamos configurar o LLM para usar saída estruturada para receber uma imagem como entrada e obter um JSON com as informações necessárias para passar à nossa função e gerar os objetos JSON.

Instalamos as dependências:

pip install elasticsearch pydantic langchain langchain-openai -q

O Elasticsearch nos ajudará a recuperar os mapeamentos de índice. Pydantic permite definir esquemas em Python para depois solicitar que o LLM os siga, e LangChain é a estrutura que facilita a chamada de LLMs e ferramentas de IA.

Criaremos um esquema Pydantic para definir a saída desejada do LLM. O que precisamos saber da imagem é o tipo de gráfico, campo, título da visualização e título do painel:

class Visualization(BaseModel): title: str = Field(description="The dashboard title") type: List[Literal["pie", "bar", "metric"]] field: str = Field( description="The field that this visualization use based on the provided mappings" ) class Dashboard(BaseModel): title: str = Field(description="The dashboard title") visualizations: List[Visualization]

Para a entrada de imagem, enviaremos um painel que acabei de desenhar:

Agora declaramos a chamada do modelo LLM e o carregamento da imagem. Essa função receberá os mapeamentos do índice do Elasticsearch e uma imagem do painel que desejamos gerar.

Com with_structured_output podemos usar nosso esquema Pydantic Dashboard como o objeto de resposta que o LLM produzirá. Com o Pydantic, podemos definir modelos de dados com validação, o que garante que a saída do modelo linear linear (LLM) corresponda à estrutura esperada.

Para converter a imagem para base64 e enviá-la como entrada, você pode usar um conversor online ou fazer isso por meio de código.

prompt = f""" You are an expert in analyzing Kibana dashboards from images for the version 9.0.0 of Kibana. You will be given a dashboard image and an Elasticsearch index mapping. Below are the index mappings for the index that the dashboard is based on. Use this to help you understand the data and the fields that are available. Index Mappings: {index_mappings} Only include the fields that are relevant for each visualization, based on what is visible in the image. """ message = [ { "role": "user", "content": [ {"type": "text", "text": prompt}, { "type": "image", "source_type": "base64", "data": image_base64, "mime_type": "image/png", }, ], } ] try: llm = init_chat_model("gpt-4.1-mini") llm = llm.with_structured_output(Dashboard) dashboard_values = llm.invoke(message) print("Dashboard values generated by the LLM successfully") print(dashboard_values) except Exception as e: print(f"Failed to analyze image and match fields: {str(e)}")

O LLM já possui contexto sobre os dashboards do Kibana, então não precisamos explicar tudo no prompt, apenas alguns detalhes para garantir que ele não se esqueça de que está trabalhando com o Elasticsearch e o Kibana.

Vamos analisar a pergunta:

Seção

Razão

Você é especialista em analisar dashboards do Kibana a partir de imagens para a versão 9.0.0 do Kibana.

Ao reforçar isso no Elasticsearch e na versão do Elasticsearch, reduzimos a probabilidade de o LLM gerar parâmetros antigos/inválidos.

Você receberá uma imagem do painel de controle e um mapeamento do índice do Elasticsearch.

Explicamos que a imagem se refere a painéis de controle para evitar quaisquer interpretações errôneas por parte do LLM.

Abaixo estão os mapeamentos de índice para o índice no qual o painel se baseia. Use-os para ajudá-lo a entender os dados e os campos disponíveis. Mapeamentos de índice: {index_mappings}

É crucial fornecer os mapeamentos para que o LLM possa selecionar campos válidos dinamicamente. Caso contrário, poderíamos codificar os mapeamentos diretamente aqui, o que é muito rígido, ou confiar na imagem que contém os nomes de campo corretos, o que não é confiável.

Inclua apenas os campos relevantes para cada visualização, com base no que está visível na imagem.

Precisávamos adicionar esse reforço porque, às vezes, o programa tenta adicionar campos que não são relevantes para a imagem.

Isso retornará um objeto com uma matriz de visualizações para exibir:

"Dashboard values generated by the LLM successfully title=""Client, Extension, OS, and Response Keyword Analysis""visualizations="[ "Visualization(title=""Count of Client IP", "type="[ "metric" ], "field=""clientip"")", "Visualization(title=""Extension Keyword Distribution", "type="[ "pie" ], "field=""extension.keyword"")", "Visualization(title=""Most Used OS", "type="[ "bar" ], "field=""machine.os.keyword"")", "Visualization(title=""Response Keyword Distribution", "type="[ "bar" ], "field=""response.keyword"")" ]

Processando a resposta do LLM

NósCriamos um painel de exemplo 2x2 e o exportamos em JSON usando a API "Obter um painel". Em seguida, armazenamos os painéis como modelos de visualização (pizza, barra, métrica), onde podemos substituir alguns parâmetros para criar novas visualizações com campos diferentes, dependendo da pergunta.

Você pode ver os arquivos JSON do modelo aqui. Observe como alteramos os valores dos objetos que queremos substituir posteriormente por {variable_name}

Com as informações fornecidas pelo LLM, podemos decidir qual modelo usar e quais valores substituir.

fill_template_with_analysis receberão os parâmetros para um único painel, incluindo o modelo JSON da visualização, um título, um campo e as coordenadas da visualização na grade.

Em seguida, substituirá os valores do modelo e retornará a visualização JSON final.

def fill_template_with_analysis( template: Dict[str, Any], visualization: Visualization, grid_data: Dict[str, Any], ): template_str = json.dumps(template) replacements = { "{visualization_id}": str(uuid.uuid4()), "{title}": visualization.title, "{x}": grid_data["x"], "{y}": grid_data["y"], } if visualization.field: replacements["{field}"] = visualization.field for placeholder, value in replacements.items(): template_str = template_str.replace(placeholder, str(value)) return json.loads(template_str)

Para simplificar, teremos coordenadas estáticas que atribuiremos aos painéis que o LLM decidir criar e produziremos um painel de controle em grade 2x2, como na imagem acima.

# Filling templates fields panels = [] grid_data = [ {"x": 0, "y": 0}, {"x": 12, "y": 0}, {"x": 0, "y": 12}, {"x": 12, "y": 12}, ] i = 0 for vis in dashboard_values.visualizations: for vis_type in vis.type: template = templates.get(vis_type, templates.get("bar", {})) filled_panel = fill_template_with_analysis(template, vis, grid_data[i]) panels.append(filled_panel) i += 1

Dependendo do tipo de visualização decidido pelo LLM, escolheremos um modelo de arquivo JSON e substituiremos as informações relevantes usando fill_template_with_analysis , depois adicionaremos o novo painel a uma matriz que usaremos posteriormente para criar o painel de controle.

Quando o painel estiver pronto, usaremos a API Criar um painel para enviar o novo arquivo JSON ao Kibana e gerar o painel:

try: dashboard_id = str(uuid.uuid4()) # post request to create the dashboard endpoint url = f"{os.getenv('KIBANA_URL')}/api/dashboards/dashboard/{dashboard_id}" dashboard_config = { "attributes": { "title": dashboard_values.title, "description": "Generated by AI", "timeRestore": True, "panels": panels, # Visualizations with the values generated by the LLM "timeFrom": "now-7d/d", "timeTo": "now", }, } headers = { "Content-Type": "application/json", "kbn-xsrf": "true", "Authorization": f"ApiKey {os.getenv('ELASTICSEARCH_API_KEY')}", } requests.post( url, headers=headers, json=dashboard_config, ) # Url to the generated dashboard dashboard_url = f"{os.getenv('KIBANA_URL')}/app/dashboards#/view/{dashboard_id}" print("Dashboard URL: ", dashboard_url) print("Dashboard ID: ", dashboard_id) except Exception as e: print(f"Failed to create dashboard: {str(e)}")

Para executar o script e gerar o painel de controle, execute o seguinte comando no console:

python <file_name>.py

O resultado final será semelhante a este:

Conclusão

Os profissionais com formação em Letras demonstram suas fortes habilidades visuais ao realizar tarefas de conversão de texto em código ou ao transformar imagens em código. A API de dashboards também permite transformar arquivos JSON em dashboards e, com um LLM e algum código, podemos transformar imagens em um dashboard do Kibana.

O próximo passo é melhorar a flexibilidade dos elementos visuais do painel de controle, utilizando diferentes configurações de grade, tamanhos e posições do painel. Além disso, oferecer suporte a visualizações e tipos de visualização mais complexos seria uma adição útil a este aplicativo.

]]> https://www.elastic.co/search-labs/blog/ai-powered-dashboards https://www.elastic.co/search-labs/blog/ai-powered-dashboards Wed, 16 Jul 2025 00:00:00 GMT