Todos os anos, os desastres naturais forçam gestores de emergência, comandantes militares e autoridades de segurança pública a tomar decisões de alto risco em prazos reduzidos. Essas decisões tradicionalmente dependem de árvores de chamadas, planilhas e conhecimento institucional distribuído entre dezenas de pessoas. A sobrecarga de coordenação por si só consome um tempo precioso.

Este post demonstra como a Elastic pode viabilizar um sistema de coordenação responsivo e baseado em agentes para resposta a desastres que detecta uma ameaça, avalia a logística e toma medidas automaticamente. Para tornar isso concreto, criamos uma simulação: um furacão fictício de Categoria 4 que ameaça a costa de Hampton Roads aciona o realojamento automatizado de mais de 137.000 pessoas em sete instalações militares.

Aviso: Este é um cenário totalmente fictício criado para fins de demonstração. O furacão ELARA-26 não existe. Os locais das instalações são baseados em dados geográficos reais e disponíveis publicamente (o conjunto de dados Military Installations, Ranges, and Training Areas [MIRTA] do Departamento de Defesa dos EUA [DoD]), mas todos os dados operacionais, como contagem de pessoal, capacidade de alojamento, ativos, e-mails de contato e perfis de missão, são totalmente fictícios. Nada nesta demonstração reflete prontidão militar, capacidade ou procedimentos operacionais reais.

Por que a resposta automatizada a desastres requer coordenação geoespacial e agêntica

Quando um desastre natural ameaça a infraestrutura crítica, o desafio de coordenação é imediato:

• Quais instalações estão na zona de impacto?

• Quantas pessoas precisam se deslocar?

• Para onde eles podem ir, e essas instalações têm capacidade?

• Quem precisa ser notificado agora?

Essas perguntas não esperam. Nem as respostas deveriam.

Implantar o pipeline: pré-requisitos e configuração

Siga as instruções aqui no repositório de exemplo para implantar um cluster local da Elastic com o Elastic Inference Service (EIS) via Cloud Connect.

Como funciona o pipeline agêntico de resposta a desastres do Elasticsearch

O pipeline tem sete camadas que trabalham juntas de ponta a ponta:

1. Ingestão de dados: eventos de desastre do Global Disaster Alert and Coordination System (GDACS) enviados para o Elasticsearch

2. Pipeline de ingestão: GeoJSON é ingerido e normalizado para o Elastic Common Schema (ECS).

3. Enriquecimento geoespacial: O polígono da área afetada pelo evento é comparado aos limites indexados de instalações militares.

4. Alerting: Uma regra de detecção do Kibana é acionada quando um desastre afeta qualquer instalação.

5. Automação de fluxo de trabalho: O alerta aciona um fluxo de trabalho do Kibana que inicia uma conversa com um agente de IA.

6. Raciocínio da IA: o agente analisa as instalações afetadas, seus ativos e as instalações de apoio mais próximas para determinar a realocação de todos os ativos e do pessoal.

7. Notificações por e-mail: o agente envia e-mails para todos os destinatários referentes à entrada e saída de pessoal e/ou ativos.

Vamos examinar cada camada.

Etapa 1: indexação de instalações militares com limites geográficos

A base é o conjunto de dados DoD MIRTA de source.coop/seerai/hifld. Este conjunto de dados fornece um geo_shape do tipo Point para cada instalação; coordenadas de centroide em vez de polígonos de limites completos.

Cada documento de instalação no índice mitra-facilities é enriquecido com dados de perfil operacional (todos fictícios), além do que o MIRTA fornece:

Esse índice rico é o que permite ao agente de IA tomar decisões inteligentes de alocação; não apenas "aqui estão as bases próximas," mas "aqui estão bases com capacidade de alojamento disponível, tipos de missão compatíveis e a logística para receber os ativos que chegam."

Etapa 2: ingerindo e normalizando eventos do GDACS

O GDACS publica GeoJSON em tempo real para terremotos, ciclones tropicais, inundações, incêndios florestais, vulcões e secas. Ingerimos esse feed em um fluxo de dados (logs-gdacs.events-*) usando um pipeline de ingestão personalizado que normaliza o GeoJSON bruto para campos do ECS.

O pipeline de ingestão do GDACS faz várias coisas que valem a pena notar:

Extração de geometria: O centróide é armazenado como um geo_point para exibição no mapa, e o polígono de impacto é armazenado como um geo_shape em gdacs.affected_area, que é o campo usado posteriormente para consultas de interseção.

Normalização da gravidade: cada tipo de desastre tem uma escala de gravidade diferente. Um ciclone tropical é medido pela velocidade do vento em km/h; um terremoto, pela magnitude Richter. O pipeline mapeia todos eles para uma pontuação normalizada de 0–100:

A pontuação de gravidade normalizada é então mapeada para um rótulo severity_level (low, medium, high, critical) usado para o mapeamento de gravidade do alerta na regra de detecção.

Alinhamento ao ECS: event.kind: alert, event.category: threat, registros de data e hora mapeados para event.start/event.end, e um _id estável baseado em fingerprint para desduplicação.

Passo 3: enriquecimento geoespacial: encontrar instalações afetadas no momento da indexação

A política enrich geo_match do Elasticsearch compara o polígono do desastre com todos os limites de instalação no momento da indexação, sem a necessidade de uma junção no momento da consulta. Em vez de consultar no momento da busca, usamos um processador enrich no pipeline de ingestão para comparar o polígono de impacto do desastre com todos os limites de instalação à medida que o documento é indexado.

A política de enriquecimento é uma política geo_match:

O processador é executado no final do pipeline de ingestão:

O INTERSECTS captura qualquer instalação cujo limite toque ou sobreponha o polígono do desastre e até mesmo interseções parciais. O resultado é que cada documento de evento do GDACS é armazenado com um array aninhado affected_facilities que nos informa exatamente quais instalações estão na zona de impacto. Nenhuma consulta de junção é necessária.

Etapa 4: regra de detecção: alerta sobre impacto nas instalações

Uma regra de detecção do Kibana monitora o fluxo de dados logs-gdacs.events-* e é disparada quando um evento do GDACS tiver sido enriquecido com pelo menos uma instalação afetada:

A regra é executada em uma programação de hora em hora (abrangendo uma janela de now-1h a now) e usa o mapeamento dinâmico de gravidade; o campo gdacs.severity_level calculado pelo pipeline de ingestão determina automaticamente a gravidade do alerta.

A gravidade do alerta também determina a pontuação de risco por meio do mapeamento de campos:

Quando a regra dispara, ela passa todo o contexto do alerta, incluindo o array affected_facilities enriquecido com nomes, tipos e locais de instalação, para um fluxo de trabalho subsequente do Kibana.

Etapa 5: Automação do fluxo de trabalho: conectando o alerta ao agente

Os fluxos de trabalho do Kibana cuidam da transição da detecção para a resposta. O fluxo de trabalho de resposta a desastres naturais é acionado pelo alerta:

Toda a carga útil do alerta (tipo de desastre, gravidade, área afetada e a lista de instalações impactadas) é encaminhada ao agente de IA como contexto inicial. O agente cuida do restante.

Etapa 6: o agente de IA: dos dados à ação coordenada

O agente mitra.response recebe o payload completo do alerta e, em um único loop agêntico, avalia o escopo, localiza instalações receptoras, aloca pessoal e envia notificações de evacuação e recebimento, tudo sem intervenção humana.

O agente tem duas ferramentas disponíveis:

• mitra.nearest_facilityconsulta o índice mitra-facilities usando uma consulta geo_shape, classificada por distância de uma determinada coordenada, retornando até 50 instalações ativas próximas com capacidade disponível.

• mitra.send_email itera sobre um array JSON de objetos de instalações e envia notificações formatadas de evacuação ou recebimento.

O conjunto de instruções do agente define um fluxo de trabalho claro:

1. Avalie a situação. Analise o alerta, identifique as instalações afetadas e determine a abrangência do desastre.

2. Faça um inventário do que precisa ser movido. Contagem de pessoal, ativos críticos, requisitos de alojamento por instalação.

3. Encontre as instalações de destino. Chame mitra.nearest_facility para cada instalação afetada, filtrando as instalações que ainda estão na zona de perigo.

4. Tome decisões de alocação. Analise soluções de instalação única em comparação com instalações múltiplas, compatibilidade entre ramos, capacidade de alojamento e suporte a ativos.

5. Envie e-mails de coordenação. Envie ordens de evacuação para as instalações de origem e notificações de recebimento para as instalações receptoras.

6. Gere um relatório de resumo. Gera um breve resumo de todas as instalações afetadas, do total de pessoas, dos ativos transferidos, das instalações de destino e de quaisquer preocupações para o chat para revisão.

A lógica de alocação do agente segue restrições do mundo real: não exceder a capacidade de alojamento, preferir relocações do mesmo ramo quando possível, usar bases conjuntas para o excedente de diferentes ramos e priorizar a distância para minimizar o tempo de deslocamento.

A ferramenta de instalação mais próxima

A consulta do fluxo de trabalho subjacente usa geo_shape com um filtro circle e classificação por _geo_distance:

A capacidade disponível é calculada no momento da consulta por meio de um campo com script que calcula a capacidade de alojamento menos a contagem atual de pessoal. O agente usa isso para alocar pessoal entre os destinos sem exceder os limites.

Furacão ELARA-26: coordenação agêntica de 137.000 pessoas, de ponta a ponta

O furacão ELARA-26 é uma tempestade de categoria 4 (ventos máximos de 213 km/h) com previsão de atingir a costa na região de Hampton Roads, na Virgínia. Quando o evento do GDACS é ingerido, o polígono da área afetada intercepta sete grandes instalações militares na região. A regra de detecção dispara. O fluxo de trabalho inicia uma conversa com o agente.

Em um único loop agêntico, o agente:

• Identificou sete instalações na zona de impacto, com um total combinado de 137.372 pessoas.

• Chamou mitra.nearest_facility para encontrar instalações receptoras fora da trajetória da tempestade.

• Distribuiu o pessoal entre nove instalações receptoras com base na capacidade de alojamento disponível e na distância.

• Gerou e enviou ordens de evacuação para todas as sete instalações afetadas.

• Gerou e enviou notificações de recebimento para todas as nove instalações receptoras.

• Produziu um resumo completo de coordenação, semelhante ao mostrado abaixo:

Instalações evacuadas:

Instalação

Pessoal

Estação Naval de Norfolk

50.000

Base expedicionária conjunta Little Creek-Fort Story

18.000

Naval Air Station Oceana

15.355

Naval Air Station Oceana Dam Neck Annex

17.509

Reserva Militar Estadual NG Camp Pendleton

9.707

Base Conjunta Langley-Eustis

15.000

Naval Weapons Station Yorktown

11.801

Instalações receptoras:

Instalação

Distância

Pessoal ingressante

Fort Gregg-Adams

97 km

~40.000

Base do Corpo de Fuzileiros Navais de Quantico

148 km

~30.000

Naval Support Facility Indian Head

151 km

~30.000

Base Conjunta Andrews

180 km

~30.000

Naval Air Station Patuxent River

141 km

~10.000

NG MTA Camp Butner

174 km

~5.000

Local de treinamento NG Bethany Beach

209 km

~4.707

Rivanna Station

140 km

~7.500

Centro de suprimentos Def Gen

22 km

~6.000

Os ativos realocados incluem veículos de transporte, helicópteros, barcos de patrulha, unidades médicas, veículos de engenharia, geradores, reboques de água, kits de abrigo e sistemas de comunicação.

Notificações automatizadas por e-mail

Depois que o agente finalizou seu plano de alocação, ele chamou mitra.send_email e enviou 16 e-mails de uma só vez; ou seja, ordens de evacuação para todas as sete instalações afetadas e notificações de recebimento para todas as nove instalações receptoras. Cada mensagem incluía a instalação de destino, a quantidade de pessoal que chegaria, os ativos a serem movidos e um contato de coordenação. O que teria levado horas de ligações em cadeia foi concluído automaticamente no momento em que o agente terminou de raciocinar.

Estendendo a resposta agêntica a desastres com RAG e fundamentação em políticas

Esta demo é puramente baseada em dados estruturados, como números de capacidade, distâncias e status operacional. Os recursos de busca semântica e retrieval augmented generation (RAG) da Elastic podem tornar o agente significativamente mais inteligente, com duas adições:

Recuperação de respostas históricas: indexe relatórios pós-ação anteriores, resumos de incidentes da Agência Federal de Gestão de Emergências (FEMA) e registros de resposta a desastres como embeddings vetoriais. Quando ocorre um novo evento, o agente pode recuperar semanticamente como eventos semelhantes foram tratados, embasando decisões de alocação com conhecimento institucional, em vez de se basear apenas em cálculos de capacidade.

Fundamentação em políticas e doutrinas: indexe diretrizes de gerenciamento de emergências do DoD, planos de continuidade de operações de instalações e orientações do comandante. O agente pode recuperar e citar as políticas reais que regem uma resposta, garantindo que cada decisão seja fundamentada em doutrina, em vez de inferência.

Ambos seguem a mesma abordagem nativa da Elastic:; um pipeline de inferência gera embeddings em tempo de indexação, e uma ferramenta de busca semântica é exposta ao agente. O pipeline de coordenação permanece o mesmo. O agente simplesmente fica mais inteligente.

Por que o Elasticsearch é a plataforma certa para a resposta agêntica no setor público

Este não é um chatbot. Não é um dashboard. É um sistema responsivo de fluxo de trabalho agêntico, que detectou uma ameaça, raciocinou sobre um problema logístico complexo e coordenou a realocação de 137.000 pessoas sem intervenção humana. Esse tipo de resultado só é possível porque todos os recursos dos quais ele depende estão em uma única plataforma unificada.

O suporte geoespacial do Elasticsearch (geo_point, geo_shape, políticas de enriquecimento e classificação baseada em distância) lida com o raciocínio espacial que torna a detecção de interseções e a consulta de instalações possíveis em escala. A busca semântica e os embeddings vetoriais ancoram os agentes na realidade, garantindo que o raciocínio da IA seja baseado no que realmente está em seus dados, em vez de suposições alucinadas. O mecanismo de detecção do Kibana, os fluxos de trabalho, o Agent Builder e as ferramentas do Agent Builder conectam tudo em um pipeline que vai do evento bruto à ação coordenada, sem a necessidade de nenhum código de integração externo.

Nenhuma outra plataforma reúne tudo isso como a Elastic. A combinação de indexação em tempo real, precisão geoespacial, recuperação semântica e orquestração por agentes, tudo em uma única pilha de tecnologia, com segurança e observabilidade de nível empresarial integradas, é o que diferencia a Elastic de ferramentas que fazem bem uma dessas coisas, mas exigem que você reúna o restante por conta própria.

Resposta geoespacial agêntica para gerenciamento de emergências, bombeiros, aplicação da lei e saúde pública

A mesma arquitetura se aplica onde quer que pessoas, instalações e eventos em tempo real se cruzem. Os dados específicos mudam. O pipeline não.

Gerenciamento de emergências: a FEMA e os órgãos estaduais de gerenciamento de emergências podem mapear locais de abrigo, áreas de mobilização e populações vulneráveis em relação aos polígonos de clima severo do National Weather Service (NWS), acionando o pré-posicionamento automatizado de recursos antes que uma tempestade atinja a costa.

Serviços de bombeiros e emergência médica: os corpos de bombeiros podem sobrepor localizações de unidades e zonas de resposta a perímetros de incêndios florestais ou clusters de incêndios estruturais, encaminhando automaticamente solicitações de ajuda mútua para as unidades disponíveis mais próximas com o equipamento adequado.

Aplicação da lei: as agências podem correlacionar locais de incidentes ativos com zonas escolares, infraestrutura crítica e posições de policiais, disparando notificações de bloqueio baseadas em localização geográfica ou despacho de recursos sem esperar pela triagem manual.

Segurança nas escolas públicas: os distritos escolares podem monitorar feeds de ameaças em tempo real em relação aos limites do campus. Quando uma ameaça cruza o perímetro de uma escola, um agente pode notificar imediatamente a administração, iniciar comunicações de confinamento e coordenar a resposta das forças policiais, tudo antes que um atendente pegue o telefone.

Saúde pública: os departamentos de saúde podem cruzar dados de vigilância de doenças ou zonas de risco ambiental com a localização de clínicas, camadas de densidade populacional e estoques de depósitos de suprimentos para direcionar recursos para onde são mais necessários.

Setor

Caso de uso

Recurso da Elastic

Gerenciamento de emergências

Corresponda os locais de abrigo aos polígonos de clima severo do NWS

Enriquecimento de geo_shape + fluxos de trabalho do Kibana

Bombeiros e EMS

Sobreponha as localizações das unidades aos perímetros de incêndios florestais

roteamento geoespacial + consulta de instalação mais próxima

Aplicação da lei

Correlacione incidentes com zonas escolares e posições de policiais

regras de alerta com reconhecimento geográfico + despacho de agentes

Segurança nas escolas públicas

Monitore feeds de ameaças em relação aos perímetros do campus

regras de detecção + notificação automatizada

Saúde pública

Corresponda zonas de perigo a locais de clínicas e depósitos de suprimentos

busca semântica + enriquecimento geoespacial

Os dados são diferentes em cada cenário. O padrão subjacente de ingerir, enriquecer no momento da indexação, detectar interseção, acionar resposta agêntica e agir é o mesmo. A Elastic oferece às organizações do setor público a plataforma para criar uma vez e adaptar em qualquer lugar.

O lançamento e a disponibilização de quaisquer recursos ou funcionalidades descritos neste artigo ficam a exclusivo critério da Elastic. Os recursos ou funcionalidades não disponíveis no momento podem não ser disponibilizados no prazo previsto ou nem chegar a ser disponibilizados.

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.

Neste artigo, exploraremos os benefícios de criar um servidor MCP do Elasticsearch personalizado e mostraremos como criar um servidor em TypeScript que conecte o Elasticsearch a aplicativos com LLM.

Por que criar um servidor MCP do Elasticsearch personalizado?

A Elastic oferece algumas alternativas para servidores MCP:

• Servidor MCP do Elastic Agent Builder para Elasticsearch 9.2+

• Servidor MCP do Elasticsearch para versões mais antigas (Python)

Se você precisar de mais controle sobre como o servidor MCP interage com o Elasticsearch, a criação do seu próprio servidor personalizado oferece a flexibilidade de adaptá-lo exatamente às suas necessidades. Por exemplo, o endpoint MCP do Agent Builder é limitado a consultas em Elasticsearch Query Language (ES|QL), enquanto um servidor personalizado permite usar o Query DSL completo. Você também tem controle sobre como os resultados são formatados antes de serem passados para o LLM e pode integrar etapas adicionais de processamento, como o resumo com tecnologia OpenAI que implementaremos neste tutorial.

Ao final deste artigo, você terá um servidor MCP no TypeScript que busca informações armazenadas em um índice do Elasticsearch, resume essas informações e fornece citações. Usaremos o Elasticsearch para recuperação, o modelo gpt-4o-mini da OpenAI para resumir e gerar citações, e o Claude Desktop como cliente MCP e UI para receber consultas dos usuários e dar respostas. O resultado é um assistente de conhecimento interno que ajuda os engenheiros a entender e sintetizar as práticas recomendadas nos documentos técnicos de sua organização.

Pré-requisitos:

• Node.js 20 +

• Elasticsearch

• Chave de API da OpenAI

• Claude Desktop

O que é MCP?

O MCP é um padrão aberto, criado pela Anthropic, que oferece conexões seguras e bidirecionais entre LLMs e sistemas externos, como o Elasticsearch. Você pode ler mais sobre a situação atual do MCP neste artigo.

O cenário de MCP está em constante evolução, com servidores disponíveis para uma ampla gama de casos de uso. Além disso, é fácil criar seu próprio servidor MCP personalizado, como mostraremos neste artigo.

Clientes do MCP

Há uma longa lista de clientes MCP disponíveis, cada um com as próprias características e limitações. Por simplicidade e popularidade, usaremos o Claude Desktop como nosso cliente MCP. Ele servirá como interface de chat na qual os usuários poderão fazer perguntas em linguagem natural e que invocará automaticamente as ferramentas expostas pelo nosso servidor MCP para buscar documentos e gerar resumos.

Criando um servidor MCP do Elasticsearch

Usando o TypeScript SDK, podemos criar um servidor que entende como consultar nossos dados do Elasticsearch com base em uma entrada de consulta do usuário.

Aqui estão os passos deste artigo para integrar o servidor MCP do Elasticsearch com o cliente Claude Desktop:

1. Configure o servidor MCP para o Elasticsearch.

2. Carregue o servidor MCP no Claude Desktop.

3. Faça o teste.

Configure o servidor MCP para o Elasticsearch

Para começar, vamos iniciar uma aplicação de nó:

Isso criará um arquivo package.json e, com ele, poderemos começar a instalar as dependências necessárias para essa aplicação.

• @elastic/elasticsearch nos dará acesso à biblioteca Elasticsearch Node.js.

• @modelcontextprotocol/sdk fornece as ferramentas de núcleo para criar e gerenciar um servidor MCP, registrar ferramentas e lidar com a comunicação com clientes MCP.

• openai permite a interação com modelos OpenAI para gerar resumos ou respostas em linguagem natural.

• zodajuda a definir e validar esquemas estruturados para dados de entrada e saída em cada ferramenta.

ts-node, @types/node, e typescript serão usados durante o desenvolvimento para digitar o código e compilar os scripts.

Configurar o conjunto de dados

Para fornecer os dados que o Claude Desktop pode consultar usando nosso servidor MCP, usaremos um conjunto de dados fictício de base de conhecimento interna. Veja como será um documento desse conjunto de dados:

Para ingerir os dados, preparamos um script que cria um índice no Elasticsearch e carrega o conjunto de dados nele. Você pode encontrá-lo aqui.

Servidor MCP

Crie um arquivo chamado index.ts e adicione o seguinte código para importar as dependências e lidar com as variáveis de ambiente:

Além disso, vamos inicializar os clientes para lidar com as chamadas do Elasticsearch e do OpenAI:

Para tornar nossa implementação mais robusta e garantir entrada e saída estruturadas, definiremos esquemas usando zod. Isso nos permite validar dados em tempo de execução, detectar erros com antecedência e facilitar o processamento de forma programática das respostas da ferramenta:

Saiba mais sobre saídas estruturadas aqui.

Agora vamos inicializar o servidor MCP:

Definição das ferramentas MCP

Com tudo configurado, podemos começar a escrever as ferramentas que serão expostas pelo nosso servidor MCP. Esse servidor expõe duas ferramentas:

• search_docs: Busca por documentos no Elasticsearch usando busca de texto completo.

• summarize_and_cite: Resume e sintetiza informações de documentos previamente recuperados para responder a uma pergunta do usuário. Essa ferramenta também adiciona citações que referenciam os documentos fonte.

Juntas, essas ferramentas formam um fluxo de trabalho simples de "recuperar e resumir", em que uma ferramenta busca documentos relevantes e a outra usa esses documentos para gerar uma resposta resumida e citada.

Formato de resposta da ferramenta

Cada ferramenta pode aceitar parâmetros de entrada arbitrários, mas deve responder com a seguinte estrutura:

• Conteúdo: esta é a resposta da ferramenta em um formato não estruturado. Este campo geralmente é usado para retornar texto, imagens, áudio, links ou embeddings. Para esta aplicação, ele será usado para retornar texto formatado com as informações geradas pelas ferramentas.

• structuredContent: Esse é um retorno opcional usado para fornecer os resultados de cada ferramenta em um formato estruturado. É útil para fins programáticos. Embora não seja usado neste servidor MCP, pode ser útil caso você queira desenvolver outras ferramentas ou processar os resultados programaticamente.

Com essa estrutura em mente, vamos nos aprofundar em cada ferramenta em detalhes.

Ferramenta de Busca de Documentos

Esta ferramenta realiza uma busca de texto completo no índice do Elasticsearch para recuperar os documentos mais relevantes com base na consulta do usuário. Ele destaca correspondências-chave e oferece uma visão geral rápida com pontuações de relevância.

Configuramos fuzziness: “AUTO” para ter uma tolerância variável de erros de digitação com base no comprimento do token que está sendo analisado. Também definimos title^2 para aumentar a pontuação dos documentos onde a correspondência ocorre no campo de título.

Ferramenta summarize_and_cite

Esta ferramenta gera um resumo baseado em documentos recuperados na busca anterior. Usa o modelo gpt-4o-mini da OpenAI para sintetizar as informações mais relevantes e responder à pergunta do usuário, fornecendo respostas derivadas diretamente dos resultados da busca. Além do resumo, também retorna metadados de citação para os documentos de origem usados.

Por fim, precisamos iniciar o servidor usando stdio. Isso significa que o cliente MCP se comunicará com nosso servidor lendo e escrevendo nos fluxos padrão de entrada e saída. Stdio é a opção de transporte mais simples e funciona bem para servidores MCP locais lançados como subprocessos pelo cliente. Adicione o seguinte código ao final do arquivo:

Agora compile o projeto usando o seguinte comando:

Isso criará uma pasta dist e, dentro dela, um arquivo index.js.

Carregue o servidor MCP no Claude Desktop

Siga este guia para configurar o servidor MCP com o Claude Desktop. No arquivo de configuração Claude, precisamos definir os seguintes valores:

O valor args deve apontar para o arquivo compilado na pasta dist. Você também precisa definir as variáveis de ambiente no arquivo de configuração com exatamente os mesmos nomes definidos no código.

Faça o teste

Antes de executar cada ferramenta, clique em Busca e Ferramentas para garantir que as ferramentas estejam ativadas. Aqui você também pode ativar ou desativar cada uma delas:

Por fim, vamos testar o servidor MCP no chat do Claude Desktop e começar a fazer perguntas:

Para a pergunta “Buscar documentos sobre métodos de autenticação e controle de acesso por função”, a ferramenta search_docs é executada e retorna os seguintes resultados:

A resposta é: "Ótimo! Encontrei 5 documentos relevantes sobre métodos de autenticação e controle de acesso por função. Eis o que foi encontrado:"

A chamada de ferramenta retorna os documentos fonte como parte da carga útil de resposta, que são posteriormente usados para gerar citações.

Também é possível encadear várias ferramentas em uma única interação. Neste caso, o Claude Desktop analisa a pergunta do usuário e determina que precisa primeiro chamar search_docs para recuperar documentos relevantes e depois passar esses resultados para summarize_and_cite para gerar a resposta final, tudo isso sem exigir prompts separados do usuário:

Neste caso, para a consulta “Quais são as principais recomendações para melhorar a autenticação e o controle de acesso em nossos sistemas? Inclua referências.”, obtivemos os seguintes resultados:

Como na etapa anterior, podemos ver a resposta de cada ferramenta para esta pergunta:

Nota: Se aparecer um submenu perguntando se você aprova o uso de cada ferramenta, selecione Permitir sempre ou Permitir uma vez.

Conclusão

Os servidores MCP representam um passo significativo rumo à padronização das ferramentas LLM para aplicações locais e remotas. Embora a compatibilidade total ainda esteja em andamento, estamos avançando nessa direção.

Neste artigo, aprendemos como criar um servidor MCP personalizado em TypeScript que conecta o Elasticsearch a aplicações baseadas em LLM. Nosso servidor expõe duas ferramentas: search_docs para recuperar documentos relevantes usando Query DSL; e summarize_and_cite para gerar resumos com citações via modelos OpenAI e Claude Desktop como UI.

O futuro da compatibilidade entre diferentes provedores de clientes e servidores parece promissor. As próximas etapas incluem adicionar mais funcionalidades e flexibilidade ao seu agente. Existe um artigo prático sobre como parametrizar suas consultas usando modelos de pesquisa para ter precisão e flexibilidade.

Esta postagem volta a se concentrar na questão: quais são as interfaces de busca que um agente precisa para construir o próprio contexto? Primeiro, ele aborda as vantagens entre ferramentas de linha de comando e ferramentas dedicadas de banco de dados. A partir daí, oferece um framework prático para encontrar as interfaces certas para as necessidades do seu agente.

O que "construir contexto" realmente significa para um agente?

Nos primeiros pipelines de Retrieval-Augmented Generation (RAG), o desenvolvedor projetou um pipeline de recuperação fixo, e o modelo de linguagem grande (LLM) era um receptor passivo do contexto. Essa limitação era fundamental: o contexto era recuperado em cada consulta, fosse necessário ou não, sem checar se realmente ajudava.

Com a transição para o RAG agêntico, os agentes agora têm acesso a um conjunto de ferramentas de busca para criar o próprio contexto. Por exemplo, tanto o Claude Code [1] quanto o Cursor [2] permitem que o agente escolha diferentes ferramentas de busca e até as combine para consultas encadeadas, dependendo do que a tarefa realmente exige.

Quais interfaces de busca existem para engenharia de contexto?

O contexto pode estar em diferentes locais, como na web, em um sistema de arquivos local ou em um banco de dados. O agente pode interagir com cada uma dessas fontes de dados fora de contexto em diferentes ferramentas:

• As ferramentas de linha de comando podem executar comandos de linha de comando e ter acesso ao sistema de arquivos local. Alguns exemplos de ferramentas de linha de comando integradas são a ferramenta bash da API Claude, a ferramenta exec do OpenClaw e a ferramenta de linha de comando do LangChain.

• Ferramentas de banco de dados dedicadas, como ferramentas de um servidor Model Context Protocol (MCP) (por exemplo, o servidor MCP do Elastic Agent Builder) ou ferramentas personalizadas (por exemplo, run_esql(query) ou db_list_index()), podem consultar bancos de dados.

• Ferramentas dedicadas de busca de arquivos podem buscar e ler arquivos locais (ou carregados), sem acesso total à linha de comando. Alguns exemplos de ferramentas integradas de busca de arquivos são o File Search Tool da API do Gemini e o File Search Tool da OpenAI.

• Ferramentas de busca na web podem recuperar informações da web.

• Ferramentas de memória armazenam e recuperam da memória de longo prazo (independentemente de como esteja armazenada).

Como você pode ver, a ferramenta shell é versátil e pode ser usada para recuperar contexto de diferentes fontes de dados, incluindo:

• Sistema de arquivos: o agente explora a estrutura de diretórios (ls, find), busca conteúdo relevante (grep, cat) e repete o processo até obter contexto suficiente.

• Banco de dados: o agente pode usar ferramentas de linha de comando (CLI) para banco de dados (p. ex., elasticsearch-sql-cli), chamar APIs HTTP via curl ou executar scripts. Isso é útil principalmente em combinação com as habilidades do agente, que são exemplos reutilizáveis e documentados inseridos no contexto do agente para orientar o uso correto das ferramentas (p. ex., Elastic Agent Skills para Elasticsearch).

• Web: o agente pode executar buscas na web usando o comando curl via API de um provedor de busca.

No entanto, a ferramenta de linha de comando dá acesso direto ao sistema e, portanto, exige medidas de segurança, como execução em ambiente sandbox isolado e logging de todos os comandos executados.

Quando usar as diferentes interfaces de busca

A interface de busca certa depende dos seus dados, dos seus padrões de consulta e do seu caso de uso. Esta seção serve como um ponto de partida prático.

Sistemas de arquivos não tornam bancos de dados obsoletos

A discussão entre sistemas de arquivos e bancos de dados não envolve a camada de armazenamento. Por exemplo, o LangChain explica que seu sistema de memória na verdade não armazena memória em um sistema de arquivos real. Em vez disso, ele armazena a memória em um banco de dados e a representa como um conjunto de arquivos para o agente [3].

Sistemas de arquivos são uma escolha natural para casos de uso nativos de arquivos, como agentes de codificação. Eles também funcionam bem como bloco de notas temporário ou memória de trabalho e para casos de usuário único ou agente único em que a concorrência não é preocupação. Nesses casos, um sistema de arquivos físico ou a representação dos dados como sistema de arquivos dá flexibilidade antes de se comprometer com uma interface específica.

Porém, o armazenamento no sistema de arquivos tem desvantagens reais, como concorrência fraca, aplicação manual de esquemas e transações atômicas. Esses fatores ficam mais evidentes quando sua aplicação precisa redimensionar ou migrar para um panorama multi-agente. Qualquer pessoa que ignore essas desvantagens está condenada a reinventar penosamente bancos de dados piores, sem as décadas de engenharia por trás da segurança das transações ou do controle de acesso que os bancos de dados de produção já oferecem. Além disso, na maioria dos contextos de negócios, você não escolhe usar o banco de dados, já que ele já existe, armazenando dados críticos para a empresa.

Ferramenta de linha de comando e sistema de arquivos

Ferramenta de linha de comando é o ponto de partida natural para buscas no sistema de arquivos. Atualmente, os agentes de codificação estão gerando um grande avanço no campo. Como eles trabalham com código em arquivos locais, são naturalmente casos de uso que envolvem muitos arquivos. Portanto, os LLMs são ajustados na fase pós-treinamento nas tarefas de codificação. É por isso que muitos LLMs são bons não só em escrever código como em usar comandos de linha de comando e navegar por sistemas de arquivos.

Usar uma ferramenta de linha de comando com CLIs integradas, como ls e grep, para encontrar arquivos é eficaz. Com grep, uma consulta como "Encontre todos os arquivos que importam matplotlib" é rápida, precisa e barata. Mas, quando o agente precisa lidar com consultas conceituais, como "Como nosso app lida com falhas na autenticação?", a correspondência de padrões com o grep pode atingir um teto muito rápido. Várias alternativas que trazem capacidades de busca semântica para a linha de comando surgiram para preencher essa lacuna, incluindo jina-grep.

No entanto, grep e muitas das alternativas de busca semântica funcionam em O(n) sobre o corpus. Nos casos de uso em bases de código, isso pode ser suficiente. No entanto, se seus dados aumentarem, a latência será perceptível. Nesse caso, é necessário um datastore indexado para manter o desempenho.

Ferramenta Shell + banco de dados

Outra forma de incluir aos seus dados mais recursos de busca, como busca semântica ou híbrida, é armazená-los em um banco de dados, como o Cursor. Além disso, quando os dados exigem junções relacionais complexas ou agregações, é indispensável uma interface de banco de dados.

Quando os dados estão em um banco de dados em vez de no sistema de arquivos, uma ferramenta de linha de comando pode funcionar como uma interface leve para banco de dados em determinados casos de uso. Se suas consultas forem simples o suficiente para uma CLI ou uma chamada de curl, uma ferramenta dedicada de banco de dados pode adicionar complexidade desnecessária.

Essa abordagem também é adequada nas fases iniciais de exploração, quando você ainda não sabe quais padrões de consulta seu agente realmente desenvolverá. Nesse caso, as habilidades do agente podem fornecer ao agente estrutura suficiente para realizar consultas corretamente, sem precisar se comprometer com uma ferramenta desenvolvida especificamente para isso. No entanto, quando o agente precisa de várias iterações para encontrar a maneira correta de consultar o banco de dados para tarefas repetitivas, a sobrecarga de tokens ao usar uma ferramenta de linha de comando como interface deixa de justificar a simplicidade de evitar mais uma ferramenta.

Ferramenta dedicada de banco de dados

Principalmente quando padrões de consulta repetidos são estruturados ou analíticos, ferramentas dedicadas a banco de dados são necessárias. Um post do blog da Vercel e da Braintrust comparou agentes com diferentes conjuntos de ferramentas de busca para tarefas reais de recuperação em dados semiestruturados, como chamados de suporte ao cliente e transcrições de chamadas de vendas (por exemplo: "Quantos problemas abertos mencionam 'segurança'?" ou "Encontre problemas onde alguém relatou um bug e depois alguém enviou um PR alegando corrigir.") [4].

Agentes com ferramentas dedicadas de banco de dados usavam menos tokens, eram mais rápidos e cometiam menos erros do que agentes com apenas uma ferramenta de linha de comando e um sistema de arquivos. A lição é que ferramentas diretas de banco de dados são a opção certa quando a consulta exige raciocínio analítico sobre dados semiestruturados.

Combinando interfaces de busca

Nenhuma interface de busca única lida bem com todas as consultas. Por exemplo, o Cursor combina ferramentas de linha de comando (para buscas via grep) e ferramentas de busca semântica e permite que o agente selecione a ferramenta certa com base nas instruções do usuário. Eles relatam que o agente escolhe o grep para buscar símbolos ou strings específicos, a busca semântica para perguntas conceituais ou comportamentais e ambos para tarefas exploratórias.

O experimento Vercel relata o mesmo: seu agente híbrido, com acesso tanto a uma ferramenta de linha de comando quanto a uma ferramenta de banco de dados dedicada, obteve o melhor desempenho entre todos os agentes testados, usando primeiro as ferramentas de banco de dados dedicadas e, em seguida, confirmando os resultados via busca no sistema de arquivos. No entanto, essa abordagem usa mais tokens e tempo para raciocinar sobre a escolha e validação da ferramenta.

Em ambos os exemplos, o padrão é o mesmo: a composição supera qualquer interface única, mas tem como contrapartida o aumento no custo e da latência.

Recomendações práticas para encontrar o conjunto certo de ferramentas

O conjunto certo de interfaces de busca é pequeno, específico e adequado aos padrões reais de consulta do seu agente. A prática recomendada atual é ter um agente com o mínimo de ferramentas possível, em vez de ter um agente com centenas de ferramentas MCP. Isso ocorre porque a desvantagem de expor todas as ferramentas possíveis de antemão enche a janela de contexto e confunde o agente sobre qual ferramenta realmente usar. Por exemplo, o Claude Code supostamente tem apenas cerca de 20 ferramentas.

Em vez disso, a ideia da divulgação progressiva é começar com um conjunto mínimo de ferramentas e deixar o agente descobrir outros recursos somente quando necessário. Pesquisas da Anthropic [5] e da Cursor [6] mostraram que essa abordagem gera uma economia de tokens entre 47%–85%. O Claude Code, por exemplo, implementa isso diretamente, permitindo que o agente descubra de forma incremental como consultar uma API ou um banco de dados, sem que esse conhecimento consuma contexto em cada chamada LLM.

Após saber os padrões de consulta do agente, você pode revisitar o conjunto de ferramentas de busca às quais o agente tem acesso como padrão. Uma forma útil de pensar sobre essa troca é o princípio "piso baixo, teto alto" para decidir quais ferramentas devem ser selecionadas. Ferramentas "teto alto" não limitam o potencial do agente. Por exemplo, uma ferramenta de linha de comando versátil permite que o agente escreva consultas completas ao banco de dados, inclusive as ambíguas, mas ao custo de sobrecarga no raciocínio, maior latência e menor confiabilidade.

Ferramentas de baixo piso são o oposto. São ferramentas especializadas que abrangem consultas específicas e são imediatamente acessíveis ao agente com o mínimo de sobrecarga de raciocínio, gerando menor custo e maior confiabilidade. Mas eles precisam de engenharia inicial, não conseguem cobrir todas as possíveis consultas e podem dificultar para o agente escolher a ferramenta certa.

Pense em cada ferramenta como parte de um espectro: ferramentas com baixo limiar de uso são fáceis para o agente usar corretamente, mas têm escopo limitado. Já as ferramentas com alto teto (maior potencial) são versáteis, mas exigem mais raciocínio para serem usadas.

A maioria dos agentes precisa de uma combinação de diferentes ferramentas de busca. Porém, cada ferramenta precisa justificar sua inclusão. Recomendamos começar com uma ferramenta de busca versátil (por exemplo, uma ferramenta search_database() ou uma ferramenta de linha de comando). Em seguida, reutilize os registros de comando que você já mantém para fins de segurança, a fim de monitorar o que seu agente realmente faz, incluindo chamadas de ferramentas, tentativas repetidas e número de chamadas por consulta de usuário. E, quando você notar um padrão de consulta se repetindo ou falhando, é hora de criar uma ferramenta específica para ele.

Resumo

O debate entre sistema de arquivos e banco de dados está desviando a atenção da verdadeira questão que os engenheiros deveriam se fazer: quais são as interfaces de busca adequadas que o agente precisa para construir o próprio contexto? A resposta mais provável é: nenhuma.

A ferramenta de linha de comando é versátil para interagir com diferentes fontes fora do contexto e, portanto, é um bom ponto de partida. Por outro lado, é menos eficiente e preciso nos casos de uso com consultas analíticas estruturadas do que ferramentas dedicadas a bancos de dados.

O objetivo é encontrar o conjunto mínimo de ferramentas de busca que lide bem com os padrões de consulta reais do seu agente. Comece com uma ferramenta de linha de comando e registre em log o que seu agente realmente faz. Quando um padrão de consulta se repetir e falhar, é hora de projetar ferramentas especializadas.

Referências

1. Thariq (Anthropic). Lessons from Building Claude Code: Seeing like an Agent (2026).

2. Cursor: Documentation. Semantic & agentic search (2026).

3. Harrison Chase (LangChain). How we built Agent Builder’s memory system (2026).

4. Ankur Goyal (Braintrust) and Andrew Qu (Vercel). Testing if "bash is all you need" (2026).

5. Anthropic. Introducing advanced tool use on the Claude Developer Platform (2025).

6. Cursor. Dynamic context discovery (2026).

Pré-requisitos

• Elasticsearch 9.3 ou Elastic Cloud Serverless: você pode criar uma implantação na nuvem seguindo essas instruções, ou você pode usar o start-local quickstart.

• Python 3.12: baixe o Python aqui.

• Hugging Face Token de acesso.

Chat completions usando um endpoint de inferência do Hugging Face

Primeiro, vamos construir um exemplo prático que conecta o Elasticsearch a um endpoint de inferência Hugging Face para gerar recomendações baseadas em IA a partir de uma coleção de artigos de blog. Para a base de conhecimento do app, usaremos um conjunto de dados de artigos de blog da empresa, que contém informações valiosas, mas frequentemente difíceis de navegar.

Com este endpoint, a busca semântica recupera os artigos mais relevantes para uma consulta específica, e um Hugging Face LLM gera recomendações curtas e contextuais com base nesses resultados.

Vamos dar uma olhada em uma visão geral do fluxo de informações que vamos criar:

Neste artigo, testaremos a capacidade do SmolLM3-3B decombinar seu tamanho compacto com fortes capacidades de raciocínio multíngue e chamada de ferramentas. Com base em uma consulta de busca, enviaremos todo o conteúdo correspondente (em inglês e espanhol) para o LLM para gerar uma lista de artigos recomendados com uma descrição personalizada com base na consulta de busca e nos resultados.

Veja como poderia ser a UI de um site de artigos com um sistema de geração de recomendações por IA.

Você pode encontrar a implementação completa desta aplicação no notebook vinculado.

Configuração de endpoints de inferência do Elasticsearch

Para usar o endpoint de inferência do Hugging Face no Elasticsearch, precisamos de dois elementos importantes: uma chave de API do Hugging Face e uma URL de endpoint do Hugging Face em execução. Ela deverá ficar assim:

O endpoint de inferência Hugging Face no Elasticsearch permite diferentes tipos de tarefas: text_embedding, completion, chat_completion, e rerank. Neste post do blog, usamos chat_completion porque precisamos que o modelo gere recomendações conversacionais baseadas nos resultados de busca e em um prompt do sistema. Esse endpoint nos permite realizar preenchimentos de chat diretamente do Elasticsearch de forma simples usando a API do Elasticsearch:

Isso servirá como o núcleo da aplicação, recebendo o prompt e os resultados de busca que passarão pelo modelo. Com a teoria explicada, vamos começar a implementar a aplicação.

Configurando o endpoint de inferência no Hugging Face

Para implantar o modelo Hugging Face, vamos usar implantações Hugging Face One-Click, um serviço fácil e rápido para implantar endpoints de modelos. Lembre-se de que este é um serviço pago, e seu uso pode incorrer em custos adicionais. Esta etapa criará a instância do modelo que será usada para gerar as recomendações dos artigos.

Você pode escolher um modelo do catálogo de um clique.

Vamos escolher o modelo SmolLM3-3B :

A partir daqui, pegue o URL do endpoint do Hugging Face:

Como mencionado na documentação de endpoints de inferência Hugging Face do Elasticsearch, a geração de texto requer um modelo compatível com a API OpenAI. Por esse motivo, precisamos anexar o subcaminho /v1/chat/completions à URL do endpoint Hugging Face. O resultado final ficará assim:

Com isso pronto, podemos começar a programar em um notebook Python.

Gerando a Chave API do Hugging Face

Crie uma conta Hugging Face e obtenha um token de API seguindo estas instruções. Você pode escolher entre três tipos de token: detalhado (recomendado para produção, pois fornece acesso apenas a recursos específicos); de leitura (para acesso somente leitura); ou de gravação (para acesso de leitura e gravação). Para este tutorial, um token de leitura é suficiente, já que só precisamos chamar o endpoint de inferência. Guarde esta chave para o próximo passo.

Configurando o endpoint de inferência do Elasticsearch

Primeiro, vamos declarar um cliente Elasticsearch Python:

Em seguida, vamos criar um endpoint de inferência no Elasticsearch que use o modelo Hugging Face. Esse endpoint nos permitirá gerar respostas com base nos posts do blog e no prompt passado para o modelo.

Conjunto de dados

O conjunto de dados contém os posts do blog que serão consultados, representando um conjunto de conteúdo multilíngue usado em todo o fluxo de trabalho:

Mapeamento do Elasticsearch

Com o conjunto de dados definido, precisamos criar um esquema de dados que se ajuste adequadamente à estrutura do post do blog. Os seguintes mapeamentos de índice serão usados para armazenar os dados no Elasticsearch:

Aqui, podemos ver com mais clareza como os dados são estruturados. Usaremos busca semântica para recuperar resultados baseados em linguagem natural, junto com a propriedade copy_to para copiar o conteúdo do campo para o campo semantic_text. Além disso, o campo title contém dois subcampos: o subcampo original armazena o título em inglês ou espanhol, dependendo do idioma original do artigo; e o subcampo translated_title está presente apenas para artigos em espanhol e contém a tradução para o inglês do título original.

Ingestão de dados

O seguinte trecho de código ingere o conjunto de dados de postagens do blog no Elasticsearch usando a bulk API:

Agora que os artigos já estão no Elasticsearch, precisamos criar uma função capaz de buscar no campo semantic_text:

Precisamos também de uma função que chame o endpoint de inferência. Neste caso, chamaremos o endpoint usando chat_completiontipo de tarefa para obter respostas de streaming:

Agora podemos escrever uma função que chama a função de busca semântica, junto com o endpoint de inferência chat_completions e o endpoint de recomendações, para gerar os dados que serão alocados nos cartões:

Finalmente, precisamos extrair as informações e formatá-las para serem impressas:

Vamos testar isso fazendo uma pergunta sobre as postagens do blog de segurança:

Aqui podemos ver os cartões no console gerados pelo fluxo de trabalho:

Você pode ver os resultados completos, incluindo todos os acertos e a resposta do LLM, neste arquivo.

Estamos pedindo artigos relacionados a: "Segurança e vulnerabilidades." Esta pergunta é usada como consulta de busca nos documentos armazenados no Elasticsearch. Os resultados recuperados são então passados para o modelo, que gera recomendações com base em seu conteúdo. Como podemos ver, o modelo fez um ótimo trabalho criando textos curtos envolventes que podem motivar o leitor a clicar.

Conclusão

Este exemplo mostra como Elasticsearch e Hugging Face podem ser combinados para criar um sistema centralizado rápido e eficiente para aplicações de IA. Essa abordagem reduz o esforço manual e oferece flexibilidade, graças ao extenso catálogo de modelos da Hugging Face. O uso do SmolLM3-3B, em particular, demonstra como modelos compactos e multilíngues ainda podem fornecer raciocínio significativo e geração de conteúdo quando combinados com busca semântica. Juntas, essas ferramentas oferecem uma base escalável e eficaz para construir análises inteligentes de conteúdo e aplicações multilíngues.

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.

Por isso, estamos tornando o Elastic Agent Skills open source: expertise nativa na plataforma para Elasticsearch, Kibana, Elastic observabilidade e Elastic Security. Adicione ao runtime do agente que você já usa e evolua seu agente de um "generalista" que precisa adivinhar muita sintaxe para um especialista com expertise real, como a capacidade de usar muitos dos padrões arquitetônicos das próprias equipes de engenharia da Elastic. Esta versão inicial de prévia técnica foca em habilidades com máxima compatibilidade com o Elastic Cloud Serverless, mas evoluirá logo para incluir suporte aprimorado para versões anteriores da plataforma.

Além disso, a Elastic está resolvendo esse problema dos dois lados. Para agentes na plataforma Elastic, o Elastic Agent Builder (agora disponível de forma geral) permite que você crie e converse com agentes de IA que herdam os controles de acesso aos seus dados, usem ferramentas integradas de busca e análise e trabalhem em contexto junto com seus dashboards, alertas e investigações. Estamos trabalhando muito para garantir experiências incríveis e agêntica na plataforma Elastic. Mas nem todo agente vive dentro da Elastic. Sua equipe já usa Cursor, Claude Code ou outros tempos de execução, e esses agentes também precisam usar a Elastic da maneira certa. É aí que entra o Agent Skills.

Por que os agentes enfrentam dificuldades com plataformas especializadas

Grandes modelos de linguagem (LLMs) são generalistas muito capazes. Eles podem escrever Python, explicar manifestos do Kubernetes e refatorar componentes do React porque os dados de treinamento são ricos em exemplos. Mas quando se trata de trabalho específico de plataforma, do tipo que envolve linguagens de consulta proprietárias, superfícies profundas de API e práticas recomendadas específicas do domínio, eles ficam aquém de maneiras previsíveis.

Para o Elasticsearch, a lacuna aparece concretamente:

• A linguagem de consulta do Elasticsearch (ES|QL) é um território novo. Os LLMs são treinados em SQL, mas o ES|QL é uma linguagem de consulta baseada em pipes com sintaxe diferente, funções distintas e semântica distinta. Os agentes escrevem consultas que parecem plausíveis, mas não são analisadas. Eles confundem WHERE com | WHERE, inventam funções que não existem e ignoram o modelo de composição baseado em pipes.

• As interfaces de API são amplas e abrangentes. Elasticsearch, Kibana e Elastic Security expõem centenas de APIs em busca, ingestão, alertas, regras de detecção, gerenciamento de casos, dashboards e muito mais. Um agente armado apenas com dados de treinamento gerais precisa adivinhar qual endpoint chamar, como é o corpo da solicitação e como lidar com a resposta. Ele erra com frequência suficiente para acabar com a confiança.

• Práticas recomendadas não estão nos dados de treinamento. Quando você deve usar semantic_text em vez de um pipeline de embedding personalizado? Como você deve estruturar um pipeline de ingestão para um CSV de 10GB? Qual é a sintaxe correta da regra de detecção para uma técnica MITRE ATT&CK®? Agentes de uso geral não têm conhecimento curado e estruturado de forma confiável e específico para Elastic, carregado por padrão. Eles teriam que procurar, e mesmo que encontrassem, documentos brutos nem sempre codificam as decisões e práticas recomendadas que profissionais habilidosos utilizam.

O resultado: os desenvolvedores passam mais tempo corrigindo a saída do agente do que passariam escrevendo o código eles mesmos. Essa é a experiência que ninguém esperava.

Habilidades de agentes: conhecimento de plataforma, empacotado para agentes

As habilidades do agente são diretórios independentes de instruções, scripts e material de referência que os tempos de execução do agente podem carregar de forma dinâmica. Quando uma habilidade está ativa, o agente tem acesso ao contexto certo na hora certa: sintaxe de consulta, padrões de API, lógica de validação, exemplos trabalhados, para que ele possa completar as tarefas corretamente na primeira tentativa.

Cada habilidade segue a especificação aberta do agentskills.io: uma pasta com um arquivo SKILL.md contendo metadados e instruções estruturadas. Nenhum formato proprietário, sem bloqueio. As habilidades funcionam em diferentes ambientes de execução de agentes, incluindo Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini CLI, Cline, Codex e muitos outros.

O que há na versão inicial v0.1.0?

O primeiro conjunto de habilidades abrange cinco áreas do Elastic Stack:

• Interação com APIs do Elasticsearch (busca, indexação, clustering)

• Crie e gerencie conteúdo do Kibana, como dashboards, alertas, conectores e muito mais

• Especialização em Elastic Observability

• Conhecimento especializado para o Elastic Security

• Criando agentes eficazes no Agent Builder

As habilidades podem ser combinadas

Habilidades não são monolíticas. Eles são modulares por natureza. Seu agente carrega apenas as habilidades relevantes para a tarefa em questão. Trabalhando em uma consulta ES|QL? A habilidade ES|QL é ativada. Precisa criar um dashboard a partir desses resultados? A habilidade do dashboard melhora. Está avaliando a integridade do seu aplicativo? A habilidade de avaliação de serviço entra em jogo. Está investigando um alerta de segurança? A triagem se conecta às habilidades de gerenciamento de casos e resposta à medida que a investigação avança.

Essa capacidade de composição significa que você não precisa de um único e enorme prompt que tente cobrir tudo. Cada habilidade carrega exatamente o contexto que seu domínio exige, nada mais, nada menos.

Para desenvolvedores que criam aplicativos de pesquisa e IA

Se você está carregando dados no Elasticsearch, escrevendo consultas ou migrando índices, as habilidades reduzem o ciclo de geração de código, ocorrência de erros e busca nos documentos para descobrir o que deu errado.

Peça ao seu agente para carregar um arquivo CSV. Ele usará uma ferramenta de ingestão de streaming que gerencia a contrapressão e infere mapeamentos a partir dos dados. Não é um loop _bulk feito manualmente que executa e fica sem memória ao processar o primeiro arquivo grande. Peça para ele consultar o ES|QL e descobrir os nomes reais de índice e esquemas de campos, escrever consultas válidas com sintaxe correta, fazer agregações apropriadas e seleção de recursos compatível com a versão, em vez de dar um palpite no estilo SQL que exige três rodadas de depuração. Ao solicitar a reindexação em todos os clusters, o sistema segue todo o fluxo de trabalho operacional: cria o destino com mapeamentos explícitos, ajusta as configurações para otimizar a taxa de transferência, executa a tarefa de forma assíncrona e restaura as configurações de produção ao terminar, em vez de chamar o método _reindex, que omite metade das etapas que um operador experiente seguiria.

Em vez de um agente que te dá um ponto de partida plausível que você precisa corrigir, você tem um que codifica a disciplina operacional que faz a saída funcionar.

Exemplos de impactos do uso das Habilidades do Elastic Agent

Eval

O que a habilidade alterou

es-audit-query-failed-logins

Usou os padrões de consulta do log de auditoria da funcionalidade em vez de busca genérica

es-authz-role-mapping-ldap

Emitiu a estrutura correta de chamadas de API para mapeamento de funções

esql-basic-query

Criou a sintaxe de pipe ES|QL no Query DSL

esql-error-handling

Priorize o esquema em vez de tentar adivinhar os nomes dos campos

esql-schema-discovery

Nunca adivinhou um nome de índice

es-ingest-csv-with-infer

Usou --infer-mappings sozinho, evitou combinar com --source-format cvs, o que causa um índice vazio

es-ingest-json-file

Abordagem robusta de ingestão utilizada, capaz de lidar com arquivos grandes

es-reindex-local-async

O índice de destino foi criado primeiro com réplicas: 0 e refresh_interval: "-1", depois foi feita a reindexação assíncrona. A referencia ignorou a preparação

es-security-403-privileges

Segui o fluxo de trabalho de diagnóstico da habilidade para erros de privilégio em vez de conselhos genéricos

Para equipes de segurança

As equipes de segurança repetem os mesmos fluxos de trabalho operacionais diariamente: triagem de alertas, ajuste de regras de detecção e gerenciamento de casos. As habilidades do agente codificam esse conhecimento processual para que seu agente de IA possa executar esses fluxos de trabalho corretamente, chamando as APIs certas na ordem certa com os nomes de campo corretos. Para um guia prático que leva você do zero a um ambiente de Elastic Security totalmente povoado sem sair do seu IDE, consulte Comece a usar o Elastic Security a partir do seu agente de IA.

Para equipes de observabilidade e operações

O novo Agent Skills for Elastic Observability reduz o trabalho operacional de instrumentar sistemas complexos, gerenciar SLOs, analisar dados complexos e avaliar a integridade dos serviços. A incorporação da expertise nativa da Elastic diretamente aos agentes de IA permite que as equipes executem fluxos de trabalho complexos de observabilidade usando uma linguagem natural simples. Isso permite que as equipes de SREs e operações resolvam incidentes com mais rapidez e mantenham sistemas confiáveis com mais facilidade. Saiba mais no blog.

Open source, especificações abertas, impulsionado pela comunidade

Estamos lançando o Agent Skills sob a licença Apache 2.0 porque acreditamos que o conhecimento dos agentes deve ser aberto. A especificação agentskills.io que as habilidades seguem é um padrão aberto, não um formato proprietário da Elastic. Queremos que as habilidades sejam um esforço comunitário e não um privilégio isolado.

Parte de um panorama maior

O Agent Skills é uma parte de uma iniciativa mais ampla para tornar o Elasticsearch a plataforma de dados mais amigável para agentes disponível. Para agentes que residem na plataforma Elasticsearch, o Agent Builder vai além, herdando os controles de acesso e permissões dos seus dados, fornecendo ferramentas integradas e personalizadas para pesquisa e análise, e permitindo que os usuários interajam com os agentes em contexto, juntamente com dashboards, alertas e investigações. Por fim, o suporte para habilidades chegará em breve ao Agent Builder, permitindo que o desenvolvedor tenha flexibilidade para aproveitar o Elastic Agent Skills, assim como as habilidades de qualquer outra fonte, para viabilizar chat seguro, com mais contexto e automação na plataforma Elasticsearch.

Para os agentes que residem em outros locais, estamos investindo no ecossistema aberto:

• Expansão do servidor Model Context Protocol (MCP): ampliação do endpoint MCP no Agent Builder com mais ferramentas além das operações atuais de busca, ES|QL e indexação.

• Melhorias na autenticação: facilitar a conexão segura dos agentes, com o objetivo de eliminar a necessidade de copiar e colar manualmente as chaves de API.

• Documentação legível por LLM: publicar arquivos llms.txt e AGENTS.md para que os agentes possam descobrir e entender as APIs da Elastic por conta própria.

• Uma interface de linha de comando (CLI) para fluxos de trabalho de agentes: ferramentas de linha de comando que facilitam o gerenciamento de conexões e as operações comuns dos agentes.

Habilidades são a camada que você pode usar hoje. O restante está chegando.

Começar

Antes de começar: os agentes de codificação de IA operam com credenciais reais, acesso real ao shell e com todas as permissões do usuário que os executa. Quando esses agentes são direcionados para fluxos de trabalho de segurança, os riscos são maiores: você está entregando a um sistema automatizado o acesso à lógica de detecção, ações de resposta e telemetria sensível. Cada perfil de risco de organização é diferente. Antes de habilitar fluxos de trabalho de segurança orientados por IA, avalie quais dados o agente pode acessar, quais ações ele pode realizar e o que acontece se ele se comportar de forma inesperada.

Instale o Elastic Agent Skills no tempo de execução do seu agente:

npx skills add elastic/agent-skills

Isso detecta automaticamente os runtimes instalados do agente e posiciona as habilidades no diretório de configuração correto. A partir daí, seu agente os coleta automaticamente.

Você também pode acessar diretamente o catálogo de habilidades e instalar habilidades individuais manualmente, copiando a pasta de habilidades para o diretório de configuração do agente.

Ainda não tem um cluster Elasticsearch? Inicie uma avaliação gratuita do Elastic Cloud. Leva cerca de um minuto para obter um ambiente totalmente configurado.

Explorar o projeto:

• Repositório de habilidades do agente

• Especificação agentskills.io

• Documentação do Elasticsearch

• Avaliação gratuita do Elastic Cloud

Integrações configuram entradas do Filebeat para realizar a coleta de dados. Para coletar dados de APIs HTTP, usamos a entrada HTTP JSON. No entanto, mesmo APIs básicas de listagem podem diferir bastante nos detalhes, e o modelo de transformações configuradas em YAML da entrada HTTP JSON pode tornar difícil e, às vezes, impossível expressar a lógica de coleta necessária.

A entrada em linguagem de expressão comum (CEL) foi introduzida para permitir uma interação mais flexível com as APIs HTTP. A CEL é uma linguagem projetada para ser incorporada em aplicações que exigem uma maneira rápida, segura e extensível de expressar condições e transformações de dados. A entrada CEL permite que um desenvolvedor de integrações escreva uma expressão capaz de ler configurações, controlar o próprio estado, fazer solicitações, processar respostas e, por fim, retornar eventos prontos para serem ingeridos.

Neste artigo, vamos analisar como a CEL difere de outras linguagens de programação, como a estendemos para a entrada CEL, e a flexibilidade e o poder que isso oferece para expressar sua lógica de coleta de dados.

CEL e como funciona na entrada

A CEL é uma linguagem de expressões. Não possui instruções. Quando você escreve CEL, não indica o que fazer escrevendo instruções, mas sim qual valor produzir ao escrever uma expressão. Cada expressão CEL produz um valor, e expressões menores podem ser combinadas em uma expressão maior para produzir um resultado de acordo com regras mais complexas. Mais adiante, veremos como usar expressões para coisas que podem ser escritas com instruções em outras linguagens.

CEL é intencionalmente uma linguagem não Turing completa. Não permite loops ilimitados. Posteriormente, veremos como você pode processar listas e mapas usando macros, mas, ao evitar loops ilimitados, a linguagem garante um tempo de execução previsível e limitado para expressões individuais.

A entrada CEL é configurada com um programa CEL (uma expressão) e algum estado inicial. O estado será fornecido como entrada para o programa. O programa é avaliado para produzir um estado de saída. Se o estado de saída incluir uma lista de eventos, esses serão removidos e publicados. O restante do estado de saída será usado como entrada para a próxima avaliação. Se o estado de saída incluir um ou mais eventos e a bandeira want_more: true, a próxima avaliação será realizada imediatamente; caso contrário, ele irá hibernar pelo restante do intervalo configurado antes de continuar. Veja um diagrama simplificado do fluxo de controle da entrada:

A saída de cada avaliação será passada como entrada para a próxima avaliação, enquanto a entrada for executada. Os dados de saída com a chave "cursor" serão mantidos no disco e recarregados após a reinicialização da entrada, mas o restante do estado não será preservado durante as reinicializações.

A linguagem CEL em si tem funcionalidade limitada e evita efeitos colaterais, mas é extensível. A implementação do cel-go acrescenta algumas funcionalidades, como sintaxe e tipos opcionais. A biblioteca Mito se baseia no cel-go e adiciona mais funcionalidades, incluindo a capacidade de fazer solicitações HTTP. A entrada da CEL usa a versão da CEL do Mito.

Trabalhando com Mito

Para criar ou fazer debug de uma integração usando a entrada CEL, o mais importante é entender qual estado de saída o seu programa CEL produzirá para um determinado estado de entrada. Durante o desenvolvimento, pode ser complicado executar o seu programa CEL pela entrada, cercado pela stack completa do Elastic. Uma maneira de ter um ciclo de feedback mais rápido é usar a ferramenta de linha de comando do Mito, que permite executar diretamente um programa CEL e ver a saída que ele produz para uma entrada específica.

Mito é escrito em Go e pode ser instalado da seguinte forma:

Quando você executa um programa CEL com o Mito, normalmente fornece a ele dois arquivos: um arquivo JSON com o estado de entrada inicial e outro arquivo com o código-fonte do seu programa CEL:

Para facilitar o copiar e colar, os exemplos neste artigo são escritos como comandos únicos que fazem com que o shell crie arquivos temporários em tempo real, agrupando o conteúdo de cada arquivo em <(echo '...content...'). No seu próprio desenvolvimento, trabalhar com arquivos reais será mais fácil.

Busca de dados de problemas do GitHub

O exemplo a seguir inclui um programa CEL completo que buscará dados sobre problemas na API do GitHub. Seu estado de entrada inicial tem uma URL para o endpoint da API e algumas informações sobre como se deve lidar com a paginação. O programa CEL usa os dados no estado de entrada para gerar uma solicitação. Ele decodificará a resposta, produzirá eventos a partir dela e os retornará como parte de seu estado de saída.

Sua primeira avaliação produz a seguinte saída:

Os eventos serão removidos e, quando executados na entrada CEL, serão publicados para ingestão. O restante da saída será fornecido para a próxima avaliação do programa CEL como seu estado de entrada.

Para entender como esse programa CEL funciona, vamos analisar alguns exemplos menores de CEL e discutir mais detalhes sobre como a entrada CEL funciona.

Noções básicas do CEL

Na linguagem CEL, não há declarações; só existem expressões. Cada expressão CEL bem-sucedida é avaliada para um valor final. Aqui está uma das menores expressões de CEL que você pode escrever, junto com sua saída:

Muitas expressões simples são intuitivas. Operações matemáticas são suportadas apenas em valores do mesmo tipo (por exemplo, int com int), então converta os tipos conforme necessário (aqui de int para double):

Não há variáveis na linguagem CEL, mas uma expressão pode receber um nome e ser usada em uma expressão maior com a ajuda da macro as de Mito. Neste exemplo, a expressão (1 + 1) avalia para o valor 2, e .as(n, ...) dá a esse valor o nome n para uso na expressão "one plus one is "+string(n):

Também é possível acumular informações em um mapa e utilizá-las posteriormente na expressão, como demonstrado aqui usando with:

Observe esse exemplo novamente. Note que a parte aninhada, ({ "data": data, "size": size(data), }), nos dá a forma do valor final. É um mapa com as chaves "data" e "size". Os valores dessas chaves dependem de data, que é definido pela parte externa da expressão. Ler as expressões da CEL de dentro para fora pode ajudar a ver o que elas vão retornar.

A CEL não possui instruções de fluxo de controle, como if, mas a ramificação condicional pode ser feita com o operador ternário:

Ciclos ilimitados e recursão não são compatíveis, pois a CEL não é uma linguagem de Turing completa. Isso torna o tempo de execução previsível e proporcional ao tamanho dos dados de entrada e à complexidade da expressão.

Embora ciclos ilimitados não sejam possíveis em expressões CEL individuais, você pode processar listas e mapas usando macros como map:

Nesta seção, abordamos:

• Strings, números, listas e mapas.

• Concatenação de strings.

• Operações matemáticas.

• Conversão de tipo.

• Condicionais.

• Nomeando subexpressões.

• Processando coleções.

Em seguida, veremos como fazer solicitações HTTP.

Requisições

O Mito estende a CEL com a capacidade de fazer requisições HTTP:

As requisições podem ser construídas explicitamente antes de serem executadas. Isso possibilita o uso de diferentes métodos HTTP e a adição de cabeçalhos e corpo da requisição.

Neste exemplo, criamos uma URL com a ajuda de format_query, adicionamos um cabeçalho à solicitação e analisamos o corpo da resposta com decode_json. Quando você receber a opção -log_requests, o Mito loga informações detalhadas no formato JSON sobre cada requisição e resposta.

Gestão do estado e avaliações

Agora que abordamos como fazer requisições e os fundamentos da CEL necessários para produzir o estado de saída desejado, vamos dar uma olhada mais detalhada no que devemos colocar no estado de saída e como isso nos permite direcionar o processamento posterior.

O programa CEL de uma integração precisa garantir que o estado de saída seja adequado para uso como entrada na próxima avaliação. A configuração define o estado inicial, que deve ser repetido na saída com quaisquer mudanças apropriadas. Uma maneira fácil de fazer isso é usar state.with({ ... }), para repetir o mapa de estados com algumas sobrescrições. Um padrão comum para programas pequenos é envolver o programa inteiro em state.with(), para que a propagação de estados não precise ser repetida em cada ramo que gera dados de saída (por exemplo, sucesso, erros).

Quando há valores de estado inicializados por uma avaliação em vez de codificados fixamente no estado inicial de entrada, o programa precisará verificar um valor existente antes de definir o inicial. Isso é algo em que o suporte para sintaxe e tipos opcionais pode ajudar. Ao usar um ponto de interrogação antes do nome do campo em uma chave de mapa, o acesso torna-se opcional: pode ou não resolver para um valor, mas acessos opcionais adicionais são possíveis e é fácil fornecer um padrão se não houver valor presente:

Nesse exemplo, o valor contador lido do estado é convertido para int porque todos os números são serializados no estado como números de ponto flutuante, de acordo com as convenções estabelecidas pelo tipo de Number do JSON e JavaScript. Também deve ser notado que "want_more": true é respeitado aqui pelo Mito, mas quando executado na entrada CEL, a avaliação só será repetida se a saída também contiver eventos.

É uma exigência dos programas CEL executados pela entrada CEL que retornem uma chave "events" no mapa de saída. O valor pode ser uma lista de mapas de eventos, uma lista vazia ou um único mapa de eventos. O caso de evento único geralmente é usado para erros. O evento será publicado pela entrada, mas seu valor também será log, e se definir um valor error.message , ele será usado para atualizar o status de saúde da Fleet da integração. Se seu programa gerar um único evento que não seja erro, é melhor agrupá-lo em uma lista.

Confira novamente a saída anterior do nosso programa de problemas do GitHub:

O programa gerenciou efetivamente o estado por:

• Repetindo valores de estado inicial em url, per_page e max_pages.

• Adicionando estados que devem ser mantidos durante reinícios em cursor.page.

• Eventos de retorno prontos para serem publicados na lista events.

• Solicitar reavaliação imediata com want_more: true.

Agora que você entende o acesso opcional e o gerenciamento de estado, bem como os conceitos básicos da CEL e as solicitações HTTP, o programa completo de problemas do GitHub deve estar legível. Tente executar o programa com o Mito e experimente algumas alterações.

Revisão e recursos

Neste artigo, analisamos o que é a CEL e como ela foi estendida na biblioteca Mito para uso na entrada CEL. Observamos a flexibilidade da CEL em um programa de exemplo que busca informações de problemas na API do GitHub e analisamos todos os detalhes necessários para entender esse programa, abrangendo o acesso às configurações no estado inicial, a interação com APIs HTTP, o retorno de eventos a serem ingeridos e o gerenciamento do estado para execuções posteriores do programa.

Para aprender mais e construir integrações usando a entrada da CEL, há vários recursos que valem a pena explorar:

• Entrada CEL - Documentação do Filebeat

• Documentação Mito

• Linguagem de expressão comum - website cel.dev

• Crie uma Integração - Documentação Elastic

E talvez o recurso mais valioso para criar integrações com a entrada CEL seja o código CEL das integrações existentes do Elastic, que pode ser encontrado no GitHub:

cel.yml.hbs arquivos no repositório de integrações Elastic - GitHub

Todos nós já vimos o crescimento dos agentes de IA. Eles são fantásticos em resumir textos, escrever trechos de código e responder a perguntas baseadas em documentação. Mas, para nós que trabalhamos com DevOps e engenharia de confiabilidade de sites (SRE), houve uma limitação frustrante. A maioria dos agentes está presa ao paradigma do call center, o que significa que eles podem ler, pensar e conversar, mas não conseguem entrar em contato e tocar na infraestrutura que deveriam estar gerenciando.

Para nosso último projeto de hackathon, decidimos eliminar essa limitação.

Nós construímos Infraestrutura Ampliada: um copiloto de infraestrutura que não apenas dá conselhos, mas também cria, implanta, monitora e corrige seu ambiente em tempo real.

O problema: copiar, formatar, colar

Os agentes padrão operam em um vácuo. Se o seu app for desativado e custar US$ 5 milhões para a empresa, um agente padrão poderá ler para você o manual de instruções para corrigi-lo. Mas você ainda precisa fazer o trabalho. Você terá que copiar o código, reformatá-lo para o seu ambiente e colá-lo no terminal.

Queríamos um agente que entendesse a diferença entre falar sobre o Kubernetes e configurar o Kubernetes.

O motor: o que é o Elastic Agent Builder?

Para construir isso, não começamos do zero. Construímos sobre o Elastic Agent Builder. Para quem não conhece, o Elastic Agent Builder é um framework projetado para desenvolver agentes rapidamente, e atua como a ponte entre um grande modelo de linguagem (LLM) (na nossa demonstração, usamos o Google Gemini) e dados privados armazenados no Elasticsearch.

O Agent Builder pode ser usado para IA conversacional, baseando-o em dados internos, como documentos ou registros. Mas seu recurso mais avançado é a capacidade de alocar ferramentas que permitem que o LLM saia da interface de bate-papo para realizar tarefas específicas. Vimos que, se levássemos esse recurso ao limite, poderíamos transformar o Agent Builder em uma potência de automação.

Fazendo funcionar: construindo a primeira versão

Quando começamos o projeto, sabíamos que queríamos que os agentes fossem capazes de mudar o mundo exterior. Tivemos uma ideia: e se construíssemos algum software "runner" (para executar qualquer comando que o agente pudesse imaginar no host)? E depois: e se os runners, o Elastic Agent Builder e o usuário estivessem em uma chamada tripla?

Começamos desenvolvendo um projeto em Python, os Runners de Infraestrutura Ampliada, que era essencialmente um loop while(true) que consultava a API de conversas do Elastic Agent Builder a cada segundo e verificava uma sintaxe especial que havíamos criado:

Depois, atualizamos o prompt para ensiná-lo nossa nova sintaxe de chamada de ferramenta. Bill é o mantenedor do FastMCP, o framework mais popular para a criação de servidores MCP (Model Context Protocol) em Python. Ele começou a trabalhar usando o cliente FastMCP com esse novo software de runner para montar servidores MCP e disponibilizar suas ferramentas ao runner. Quando o agente via isso, ele executava a chamada de ferramenta e enviava os resultados via POST de volta para a conversa como se o usuário tivesse enviado os resultados. Isso acionou o LLM para responder ao resultado, e seguimos em frente!

Foi ótimo, mas houve dois problemas principais:

1. O agente despejava todo esse JSON diretamente na conversa com o usuário.

2. A primeira vez que as mensagens ficaram visíveis pela API de conversas foi quando uma rodada de conversa foi concluída (ou seja, quando o LLM respondeu).

Então, começamos a descobrir como colocar isso em segundo plano.

Em seguida, passamos a dar ao agente uma ferramenta chamada call_external_tool com dois argumentos: o tool_name e os argumentos da ferramenta JSON em string. Essa chamada de ferramenta externa não retornava nada, mas, mais importante, seria visível na requisição GET para a API de conversas. Em seguida, demos permissão aos runners para escrever documentos diretamente no Elasticsearch, que o agente do Elastic Agent Builder poderia recuperar conforme necessário. O agente está sempre operando em resposta a uma mensagem do usuário, então precisamos iniciar o agente com uma mensagem de usuário para que ele busque os resultados e continue o processamento. Então pedimos aos agentes que inserissem uma pequena mensagem no chat para retomar a conversa:

Então, agora tínhamos chamadas de ferramentas externas. No entanto, devido ao segundo problema mencionado acima, tivemos que eliminar a parte final do pontapé inicial. Caso contrário, cada chamada de ferramenta externa exigiria uma rodada completa de conversas para recuperar os resultados!

Aprimorando: introduzindo fluxos de trabalho

Além das chamadas da linguagem de consulta Elasticsearch (ES|QL) e da ferramenta de busca de índice, os agentes do Agent Builder podem chamar ferramentas baseadas em fluxo de trabalho da Elastic. Fluxos de trabalho da Elastic oferecem uma forma flexível e fácil de gerenciar para executar uma sequência arbitrária e uma lógica de ações. Para nossos propósitos, tudo o que precisamos é que o fluxo de trabalho armazene uma solicitação de ferramenta externa para o Elasticsearch e retorne uma ID para pesquisar os resultados. Isso resulta na seguinte definição simples de fluxo de trabalho:

Com isso, em vez de depender da solicitação de chamada de ferramenta ser gravada na conversa, os runners podem simplesmente consultar o índice distributed-tool-requests do Elasticsearch para novas solicitações de ferramentas externas e registrar os resultados em outro índice do Elasticsearch com o execution.id fornecido.

Isso elimina os dois principais problemas mencionados acima:

1. O histórico de conversas não está mais saturado com a carga útil das chamadas de ferramentas externas.

2. Como os runners estão consultando o índice do Elasticsearch em vez do histórico de conversas, eles não são bloqueados pela rodada de conversa a ser concluída para que os pedidos externos de ferramentas fiquem visíveis.

O segundo ponto tem a grande vantagem de que o processamento das chamadas de ferramentas externas começa dentro da fase de pensamento do agente (e não quando a rodada de conversação é concluída). Isso nos permite instruir o LLM no prompt do sistema para sondar os resultados da ferramenta externa até que os resultados estejam disponíveis e elimina a necessidade da mensagem de inicialização. De modo geral, isso tem o efeito positivo de tornar a conversa mais natural: o LLM consegue processar várias solicitações de ferramentas externas em uma única rodada de conversa (em vez de exigir uma rodada de conversa para cada solicitação de ferramenta) e, portanto, consegue atender a solicitações de usuários mais complexas de uma só vez.

Juntando tudo

Para preencher a lacuna entre o LLM e o rack de servidores, desenvolvemos uma arquitetura específica usando as capacidades da ferramenta do Agent Builder:

1. Runners de infraestrutura ampliada: implantamos executantes leves dentro dos ambientes de destino (servidores, clusters Kubernetes, contas de nuvem). Esses executores são conectados diretamente à Elastic, usando endpoints seguros e segredos disponíveis apenas para cada um dos executores.

2. Recuperação ES|QL: o copiloto usa o ES|QL da Elastic para realizar buscas híbridas. Ele não procura apenas conhecimento; procura capacidades. Ele consulta os executores runners para ver quais ferramentas estão disponíveis (por exemplo, list_ec2_instances, install_helm_chart).

3. Execução do fluxo de trabalho: quando o agente decide sobre um curso de ação, ele cria um fluxo de trabalho estruturado.

4. Ciclo de feedback: os runners executam o comando no local e enviam os resultados de volta ao Elasticsearch. O copiloto lê o resultado do índice e decide o próximo passo.

A demonstração: da interrupção à observabilidade

No vídeo, apresentamos dois casos distintos que demonstram como essa arquitetura pode melhorar.

Caso 1: Resgate do DevOps

Começamos com um usuário entrando em pânico por causa de uma queda de 5 milhões de dólares causada por um ponto cego no cluster Kubernetes deles.

• O pedido: "como garantir que isso não aconteça de novo?"

• A ação: o agente não se limitou a oferecer um tutorial. Ele identificou o cluster, criou os espaços de nome necessários, gerou secrets do Kubernetes, instalou o OpenTelemetry Operator e forneceu na hora um link para um dashboard de APM em tempo real.

• O resultado: total observabilidade do Kubernetes e insights do aplicativo sem que o usuário escreva uma única linha de YAML.

Caso 2: Transferência de segurança

Uma regra fundamental da segurança da infraestrutura é que você só pode proteger o que pode ver. Ao realizar nosso resgate de DevOps, o agente vê uma oportunidade de melhorar a segurança do ambiente.

Com um alerta iniciado a partir de uma investigação anterior relacionada ao Elastic Observability, demonstramos como um profissional de segurança pode interagir diretamente com sua infraestrutura: primeiro, para enumerar os ativos e recursos em seu ambiente de nuvem; e, segundo, para implantar as ferramentas necessárias para que o ambiente esteja seguro.

• Descoberta: o copiloto enumerou os recursos da AWS para o profissional de segurança e identificou uma lacuna crítica: uma instância do Amazon Elastic Compute Cloud (EC2) e um cluster do Amazon Elastic Kubernetes Service (EKS) com endpoints públicos sem proteção de endpoint.

• Correção: com uma simples aprovação, o copiloto implantou a detecção estendida e resposta (XDR) e detecção e resposta na nuvem (CDR) do Elastic Security nos ativos vulneráveis, protegendo o ambiente em tempo real.

• Resultado: proteção dos ativos e recursos AWS implantados com segurança completa em tempo de execução.

O futuro: tudo ampliado

Esse projeto comprova que o Elastic Agent Builder pode ser o cérebro central para operações distribuídas. Não estamos limitados apenas à infraestrutura. Nossa tecnologia de runners cobre:

• Synthetics ampliados: diagnosticando erros TLS em executores globais.

• Desenvolvimento ampliado: criando pull requests e implementando CAPTCHAs em serviços frontend.

• Operações aprimoradas: para reconfiguração automática de resolvedores de DNS durante uma interrupção.

Veja você mesmo

Acreditamos que o futuro da IA não se resume apenas ao suporte por chat; envolve Infraestrutura Ampliada. Envolve um parceiro que possa implantar, consertar, observar e proteger ao seu lado.

Confira o código e use os executores distribuídos (GitHub) e o Elastic Agent Builder no Elastic Cloud Serverless hoje mesmo!

• Crie um projeto serverless no Elastic Cloud.

• Implante o código em um runner.

• Prepare o runner.

• Configure seu mcp.json.

• Execute o runner, que criará automaticamente seu agente e as ferramentas.

• Converse com um agente que pode raciocinar, planejar e executar ações nos seus runners distribuídos!

A equipe: Alex, Bill, Gil, Graham e Norrie

Os agentes estão ganhando força, impulsionados pelo potencial de entregar ganhos de eficiência e melhores experiências para os clientes. Mas, na prática, fornecer aos agentes o contexto correto é difícil, principalmente quando se trabalha com dados empresariais desorganizados e não estruturados. Os desenvolvedores precisam gerenciar ferramentas, prompts, estado, lógica de raciocínio, modelos e, principalmente, recuperar o contexto relevante das fontes comerciais para fornecer resultados e ações precisos. O Elastic Agent Builder oferece esses componentes essenciais para desenvolver agentes seguros, confiáveis e orientados ao contexto.

Principais funcionalidades do Agent Builder

O Agent Builder aproveita os investimentos de longo prazo da Elastic na relevância de busca e retrieval-augmented generation, e trabalha para tornar o Elasticsearch o melhor banco de dados vetorial para simplificar o desenvolvimento de agentes de IA contextuais e focados em dados.

O Agent Builder permite que você:

• Comece com um agente conversacional integrado que pode responder a perguntas, realizar análises e conduzir investigações sobre quaisquer dados no Elasticsearch.

• Passe de dados complexos não estruturados para um agente personalizado com uma experiência de desenvolvimento baseada em configuração.

• Aproveite a relevância de pesquisa híbrida de ponta por meio do ES|QL integrado ou de ferramentas personalizadas para melhorar a qualidade do contexto e a confiabilidade do agente.

• Execute fluxos de trabalho complexos (pré-visualização) como ferramentas reutilizáveis para enriquecer dados, atualizar registros, enviar mensagens e muito mais para automação baseada em regras.

• Conecte-se a fontes de dados fora do Elasticsearch usando fluxos de trabalho e MCP para correlacionar e combinar o contexto dos agentes.

• Integre-se a qualquer framework agêntico ou aplicação usando ferramentas integradas e personalizadas expostas via MCP, além da capacidade de conectar-se a MCPs externos (em pré-visualização), suporte para A2A e suporte completo à API.

• Amplie os recursos do Agent Builder com integração a soluções de terceiros, como o LlamaIndex para processamento complexo de documentos ou o Arcade.dev para acesso seguro e estruturado a ferramentas.

Para ampliar ainda mais a funcionalidade do Agent Builder, apresentamos o Elastic Workflows, nossos novos recursos de automação baseados em regras, agora em versão prévia técnica. Para tarefas organizacionais, os agentes às vezes precisam de certeza e confiabilidade de ações baseadas em regras, que geralmente são necessárias para implementar uma lógica comercial específica. O Elastic Workflows oferece aos agentes uma maneira simples e declarativa de orquestrar sistemas internos e externos para executar ações, coletar e transformar dados e contexto. Os fluxos de trabalho são totalmente componíveis, orientados a eventos e flexíveis, e podem ser expostos como ferramentas a um agente via MCP.

De dados a agentes em questão de minutos

Os agentes de desenvolvimento podem levar semanas de trabalho inicial para consolidar armazenamentos de dados separados, criar pipelines manuais, ajustar consultas e gerenciar orquestrações complexas. O Agent Builder reduz o tempo de desenvolvimento para os agentes, acabando com a necessidade de armazenamentos de dados separados, bancos de dados vetoriais, pipelines RAG, camadas de pesquisa, tradutores de consultas e orquestradores de ferramentas, permitindo que você se concentre na lógica do agente e na entrega do aplicativo.

O Agent Builder integra de forma nativa primitivas da plataforma Elasticsearch para agilizar o desenvolvimento de agentes.

• Comece com um agente conversacional integrado que pode conversar e raciocinar imediatamente com seus dados indexados.

• Integre agentes em aplicações, dashboards ou sistemas de CI/CD com acesso interativo via Kibana, APIs ou MCP e A2A.

• Crie com as ferramentas padrão para entender a estrutura dos seus dados, selecionar o índice apropriado, gerar consultas híbridas, semânticas e estruturadas otimizadas e criar visualizações configuráveis usando ES|QL com base em comandos em linguagem natural.

Para se aprofundar, veja um passo a passo prático e completo.

Crie com o Elasticsearch, uma plataforma de dados completa para engenharia de contexto

Para agentes de IA, a qualidade do contexto é essencial para fornecer raciocínio eficaz e reduzir os riscos de alucinação. Para muitos agentes de IA corporativa, os dados de negócios necessários para realizar uma tarefa são a peça fundamental de contexto. Como um armazenamento de dados altamente escalável, banco de dados vetorial e líder em relevância, o Elasticsearch já oferece muitas primitivas fortes de engenharia de contexto. A engenharia de contexto vai além da simples retrieval-augmented generation, permitindo que você personalize e redimensione como os dados são obtidos, ranqueados, filtrados e apresentados aos agentes, ajudando a reduzir ruído e ambiguidade.

O Elasticsearch oferece um mecanismo de contexto que combina busca lexical, busca vetorial e filtragem estruturada para recuperação de dados, o que melhora o desempenho do LLM ao garantir que o modelo opere em um contexto relevante e preciso. Essa capacidade é suportada por recuperação agêntica, juntamente com ferramentas integradas e lógica de busca que selecionam automaticamente os índices corretos e transformam a linguagem natural em consultas otimizadas para o contexto.

Com o Agent Builder, você garante que os agentes recebam primeiro o contexto mais útil com controles de relevância e classificação, permitindo que você ajuste a lógica de pontuação, classificação e filtragem. O Elasticsearch permite que você controle o que importa, por que importa e como é priorizado, em vez de depender de um comportamento opaco de recuperação. Tudo isso é sustentado pelo Elasticsearch como uma plataforma de dados escalável para armazenar e escalar todos os seus dados de texto, vetores, metadados, logs e muito mais em uma plataforma, facilitando o gerenciamento do contexto para os agentes.

Executar fluxos de trabalho complexos como ferramentas reutilizáveis

Enquanto agentes de IA permitem o raciocínio para tarefas complexas, grande parte da automação depende da execução confiável de ações baseadas em regras que aplicam lógica de negócios específica. O Elastic Workflows oferece uma maneira simples e declarativa de orquestrar sistemas internos e externos para realizar ações, coletar contexto ou dados e integrá-los como parte dos agentes. Definidos em YAML, os fluxos de trabalho são totalmente componíveis, permitindo que sejam tão simples ou complexos quanto o trabalho exigir. Isso oferece aos agentes uma maneira eficiente de agir em toda a plataforma e nas soluções do Elasticsearch, bem como com aplicativos de terceiros.

A integração de um fluxo de trabalho com o Agent Builder pode ser feita em três etapas (pré-requisito: habilitar fluxos de trabalho com detalhes fornecidos aqui)

1. Criar e salvar um novo fluxo de trabalho usando o editor simples baseado em YAML com autopreenchimento e testes integrados.

2. Crie uma nova ferramenta no Agent Builder com o tipo “Fluxo de trabalho” e informe uma descrição para ajudar o agente a determinar quando usar a ferramenta de fluxo de trabalho.

3. Adicione a ferramenta de fluxo de trabalho ao seu agente personalizado.

4. É isso aí! Agora o agente pode chamar o fluxo de trabalho dentro de uma conversa.

Seu agente, suas regras

O Agent Builder não te prende a um único paradigma de desenvolvimento. Em vez disso, ele foi projetado para permitir abordagens de desenvolvimento abertas e flexíveis para agentes com controle total de dados, relevância, modelos, interoperabilidade, security e design de agentes.

As definições de agentes personalizados permitem que você escolha exatamente quais ferramentas um agente pode acessar, incorpore avisos de sistema personalizados, adapte as instruções do agente e defina limites de segurança. Os agentes permanecem independentes do modelo, permitindo que você configure com flexibilidade um LLM preferido, tanto nativo quanto em todo o ecossistema, sem ficar preso a um único provedor.

Crie ferramentas extensíveis que encapsulem lógica específica do domínio (por exemplo, filtros de índice específicos, junções ES|QL, pipelines analíticos) e restrinja-as para uso seguro em produção. O suporte completo à API permite a interoperabilidade com outras frameworks de agentes, com suporte nativo ao Protocolo de Contexto do Modelo (MCP). A integração A2A significa que você pode expor seus agentes Elastic a outros frameworks, serviços e apps clientes, reutilizando a mesma lógica de engenharia de dados e contexto em todas as integrações.

O Agent Builder suporta desenvolvimento flexível e aberto e foi projetado para se integrar com frameworks e plataformas populares de agentes. Essas integrações podem ser essenciais para entregar agentes eficazes. Como descreve Sam Partee, cofundador da Arcade.dev,

"Sistemas agênticos falham hoje porque conectar IA a ferramentas e dados é algo complexo. O Elastic Agent Builder com Arcade.dev oferece aos desenvolvedores uma maneira estruturada e segura de lidar com a forma como os agentes recuperam o contexto, raciocinam e agem, levando os agentes da demonstração ao nível de produção."

O Agent Builder também aproveita a extensibilidade do Elasticsearch para lidar com dados complexos. Como descreve Jerry Liu, CEO da LlamaIndex ,

“Extrair o contexto empresarial de fontes de dados não estruturadas é fundamental para a criação de agentes eficazes. O Elastic Agent Builder combinado com o processamento de documentos complexos do LlamaIndex fortalece a camada fundamental de contexto, ajudando as equipes a recuperar, processar e preparar dados para que os agentes possam raciocinar com mais precisão e oferecer melhores resultados."

O que você pode construir?

O Agent Builder já está sendo usado para vários casos de uso. Abaixo estão alguns exemplos e arquiteturas de referência para começar a usar agentes:

• Automatizar infraestrutura: em cenários de suporte, os agentes têm sido usados para ler, pensar e conversar, mas até o momento, eles não conseguem acessar e tocar a infraestrutura que possam precisar gerenciar. A equipe de engenharia da Elastic criou um agente para gerenciamento automatizado de infraestrutura como parte de um hackathon. O agente investiga ativamente problemas com a infraestrutura da aplicação e age de forma automatizada. Ele usa fluxos de trabalho para otimizar configurações, responder a problemas e redimensionar recursos, tudo com base em uma compreensão inteligente dos logs de infraestrutura.

• Análise de ameaças à segurança: um agente de vulnerabilidade de segurança foi desenvolvido com Elastic Agent Builder, MCP e Elasticsearch. Ele automatiza a análise de ameaças correlacionando dados de segurança internos com inteligência de ameaças externa. O agente realiza buscas semânticas em incidentes e configurações históricas, amplia os resultados com dados da internet em tempo real e aplica o raciocínio LLM para avaliar a relevância ambiental, priorizar riscos e produzir medidas corretivas viáveis. Consulte a arquitetura de referência.

• Suporte técnico ao cliente: os agentes podem executar diversas tarefas de suporte, incluindo resumo de casos, identificação e criação de problemas duplicados e investigação técnica aprofundada. O Agent Builder permite isso com uma pesquisa híbrida de várias etapas para encontrar somente os problemas, soluções e procedimentos relacionados mais relevantes e formular hipóteses de causa raiz e planos de remediação. O Agent Builder pode simplificar a arquitetura de sistemas de suporte complexos e acelerar o tempo de entrega.

• Descoberta de produtos e conteúdo: o Agent Builder simplifica o processo de expor catálogos complexos de produtos para experiências conversacionais, ao mesmo tempo em que permite que as organizações mantenham flexibilidade para incluir a própria lógica e requisitos de negócios.

• Crie você mesmo: participe do Hackathon do Agent Builder, que ocorrerá de 22 de janeiro a 27 de fevereiro de 2026. Trabalhe com a comunidade para criar agentes de IA orientados por contexto e em várias etapas que combinem buscar, fluxos de trabalho, ferramentas e raciocínio para automatizar tarefas do mundo real*

Comece a criar agentes personalizados agora

Comece com um teste do Elastic Cloud e confira a documentação aqui. Para clientes existentes, o Agent Builder está disponível no Cloud Serverless e no nível Empresarial no Elastic Cloud Hosted e autogerenciado.

* Clique aqui para ver os termos, condições e requisitos de elegibilidade para o hackathon

Uma das maneiras pelas quais o vidro será quebrado é pela adoção de agentes de voz, que são agentes de IA que reconhecem a fala humana e sintetizam áudio gerado por computador. Com o crescimento das transcrições de baixa latência, modelos de linguagem grandes e rápidos (LLMs) e modelos de texto para fala que soam humanos, isso se tornou possível.

Os agentes de voz também precisam ter acesso a dados empresariais para se tornarem realmente valiosos. Neste artigo, aprenderemos como funcionam os agentes de voz e criaremos um para a ElasticSport, uma loja fictícia de equipamentos esportivos para atividades ao ar livre, usando LiveKit e Elastic Agent Builder. Nosso agente de voz será sensível ao contexto e funcionará com nossos dados.

Como funciona

Existem dois paradigmas no mundo dos agentes de voz: o primeiro usa modelos de fala para fala, e o segundo usa um pipeline de voz que consiste em fala para texto, LLM e texto para fala. Modelos de fala para fala têm os próprios benefícios, mas os pipelines de voz oferecem muito mais personalização das tecnologias usadas e de como o contexto é gerenciado, além de controle sobre o comportamento do agente. Vamos focar o modelo de pipeline de voz.

Principais componentes

Transcrição (fala para texto)

A transcrição é o ponto de entrada no pipeline de voz. O componente de transcrição recebe como entrada quadros de áudio brutos, transcreve a fala em texto e gera esse texto como saída. O texto transcrito é armazenado em buffer até que o sistema detecte que a fala do usuário terminou, momento em que a geração do LLM é iniciada. Diversos fornecedores terceirizados oferecem transcrições de baixa latência. Ao selecionar um, leve em consideração a latência e a precisão da transcrição, e certifique-se de que ele suporte transcrições em fluxo contínuo.

Exemplos de APIs de terceiros: AssemblyAI, Deepgram, OpenAI, ElevenLabs

Detecção de curva

A detecção de turno é o componente do pipeline que detecta quando o falante termina de falar e a geração deve começar. Uma maneira comum de fazer isso é por meio de um modelo de detecção de atividade de voz (VAD), como o Silero VAD. O VAD utiliza níveis de energia do áudio para detectar quando o áudio contém fala e quando a fala terminou. No entanto, o VAD sozinho não consegue identificar a diferença entre pausa e fim da fala. Por isso, muitas vezes é combinado com um modelo de fim de enunciado que prevê se o falante terminou de falar, com base na transcrição intermediária ou no áudio bruto.

Exemplos (Hugging Face): livekit/turn-detector, pipecat-ai/smart-turn-v3

Agente

O agente é o núcleo de um pipeline de voz. É responsável por entender a intenção, reunir o contexto certo e formular uma resposta em formato de texto. O Elastic Agent Builder, com suas capacidades integradas de raciocínio, biblioteca de ferramentas e integração de fluxos de trabalho, é um agente capaz de trabalhar sobre seus dados e interagir com serviços externos.

LLM (texto para texto)

Ao selecionar um LLM para o Elastic Agent Builder, há duas características principais a considerar: benchmarks de raciocínio de LLM e tempo até o primeiro token (TTFT).

Benchmarks de raciocínio indicam quão bem o LLM consegue gerar respostas corretas. Os benchmarks a serem considerados são aqueles que avaliam a adesão à conversa em múltiplos turnos e os benchmarks de inteligência, como o MT-Bench e o conjunto de dados Humanity's Last Exam, respectivamente.

Os benchmarks TTFT avaliam a rapidez com que o modelo produz seu primeiro token de saída. Existem outros tipos de benchmarks de latência, mas a TTFT é particularmente importante para agentes de voz, pois a síntese de áudio pode começar assim que o primeiro token é recebido, resultando em menor latência entre os turnos, uma conversa com sensação natural.

Normalmente, é preciso fazer uma troca entre essas duas características porque modelos mais rápidos geralmente têm um desempenho pior em benchmarks de raciocínio.

Exemplos (Hugging Face): openai/gpt-oss-20b, openai/gpt-oss-120b

Síntese (texto para fala)

A parte final do pipeline é o modelo de conversão de texto em fala. Esse componente é responsável por converter a saída de texto do LLM em fala audível. Semelhante ao LLM, a latência é uma característica a ser observada ao selecionar um provedor de texto para fala. A latência de texto para fala é medida pelo tempo até o primeiro byte (TTFB). Esse é o tempo que leva para receber o primeiro byte de áudio. Menor TTFB também reduz a latência de giro.

Exemplos: ElevenLabs, Cartesia, Rime

Construção do pipeline de voz

O Elastic Agent Builder pode ser integrado a um pipeline de voz em vários níveis diferentes:

1. Ferramentas apenas do Agent Builder: fala para texto → LLM (com ferramentas Agent Builder) → texto para fala

2. Agent Builder como MCP: fala para texto → LLM (com acesso ao Agent Builder via MCP) → texto para fala

3. Agent Builder como núcleo: conversão de fala em texto → Agent Builder → conversão de texto em fala

Para este projeto, escolhi o Agent Builder como abordagem núcleo. Com essa abordagem, toda a funcionalidade do Agent Builder e dos fluxos de trabalho pode ser utilizada. O projeto usa o LiveKit para orquestrar a conversão de fala em texto, detecção de turnos e conversão de texto em fala, e implementa um node LLM personalizado que se integra diretamente ao Agent Builder.

Agente de voz do suporte da Elastic

Criaremos um agente de voz de suporte personalizado para uma loja de esportes fictícia chamada ElasticSport. Os clientes poderão ligar para a linha de ajuda, solicitar recomendações de produtos, encontrar detalhes do produto, verificar o status do pedido e receber as informações do pedido por mensagem de texto. Para isso, primeiro precisamos configurar um agente personalizado e criar ferramentas para executar a Elasticsearch linguagem de consulta (ES|QL) e fluxos de trabalho.

Configurando o agente

Prompt

O prompt orienta o agente qual a personalidade que deve ter e como responder. É importante ressaltar que há alguns prompts específicos de voz que garantem que as respostas sejam sintetizadas em áudio adequadamente e que os mal-entendidos sejam recuperados de forma graciosa.

Fluxos de trabalho

Vamos adicionar um pequeno fluxo de trabalho para enviar um SMS pela API de mensagens do Twilio. O fluxo de trabalho será exposto ao agente personalizado como uma ferramenta, resultando em uma experiência de usuário em que o agente poderá enviar um SMS ao chamador durante a chamada. Isso permite que o autor da chamada, por exemplo, pergunte: "Você pode enviar os detalhes sobre X por texto?"

Ferramentas ES|QL

As ferramentas a seguir permitem que o agente forneça respostas relevantes fundamentadas em dados reais. O repositório de exemplo contém um script de configuração para iniciar o Kibana com conjuntos de dados de produtos, pedidos e base de conhecimento.

• Product.search

O conjunto de dados de produtos contém 65 produtos fictícios. Este é um documento de exemplo:

Os campos de nome e descrição são mapeados como semantic_text, permitindo que o LLM use busca semântica via ES|QL para recuperar produtos relevantes. A consulta de busca híbrida realiza correspondência semântica em ambos os campos, com um peso um pouco maior aplicado às correspondências no campo do nome usando um boost.

A consulta primeiro recupera os 20 melhores resultados classificados pela pontuação inicial de relevância. Esses resultados são então reclassificados com base no campo de descrição usando o modelo de inferência .rerank-v1-elasticsearch e, finalmente, reduzidos para os cinco produtos mais relevantes.

• Knowledgebase.search

Os conjuntos de dados da base de conhecimento contêm documentos do seguinte formato, onde os campos de título e conteúdo são armazenados como texto semântico:

E a ferramenta usa uma consulta semelhante à ferramentaproduct.search:

• Orders.search

A última ferramenta que adicionaremos é aquela usada para recuperar pedidos por order_id:

Após configurar o agente e anexar esses fluxos de trabalho e ES|QL para o agente, o agente pode ser testado dentro do Kibana.

Além de construir um agente de suporte ElasticSport, o agente, fluxos de trabalho e ferramentas podem ser adaptados a outros casos de uso, como um agente de vendas que qualifica leads, um agente de serviço para reparos residenciais, reservas para um restaurante ou um agente de agendamento de consultas.

A parte final é conectar o agente que acabamos de criar com modelos LiveKit, texto para fala e fala para texto. O repositório (link no fim do artigo) contém um node personalizado do LLM Elastic Agent Builder que pode ser usado com o LiveKit. Basta trocar o AGENT_ID pelo seu e vinculá-lo com sua instância Kibana.

Para começar

Confira o código e experimente você mesmo aqui.

Afinal, tudo no contexto influencia as respostas da IA. O princípio Lixo entra, lixo saí continua válido.

Neste artigo, vamos apresentar o que as memórias de curto e longo prazo significam para agentes de IA, especificamente:

• A diferença entre memória de curto e longo prazo.

• Como elas se relacionam com as técnicas de Retrieval-Augmented Generation (RAG) com bancos de dados vetoriais, como o Elasticsearch, e por que é necessário um gerenciamento cuidadoso da memória.

• Os riscos de negligenciar a memória, incluindo transbordamento de contexto e envenenamento do contexto.

• Boas práticas, como a eliminação do contexto, o resumo e a recuperação apenas do que é relevante, visam manter a memória de um agente útil e segura.

• Por fim, vamos abordar como a memória pode ser compartilhada e propagada em sistemas multiagente para permitir que agentes colaborem sem confusão usando o Elasticsearch.

Memória de curto prazo versus memória de longo prazo em agentes de IA

Memória de curto prazo em um agente de IA geralmente se refere ao contexto conversacional imediato ou estado — essencialmente, o histórico atual da conversa ou mensagens recentes na sessão ativa. Isso inclui a consulta mais recente do usuário e as trocas de mensagens recentes. É muito semelhante à informação que uma pessoa mantém em mente durante uma conversa em andamento.

Frameworks de IA frequentemente mantêm essa memória transitória como parte do estado do agente (por exemplo, usando um mecanismo de ponto de verificação para armazenar o estado da conversa, conforme abordado por este exemplo do LangGraph). A memória de curto prazo tem escopo de sessão, ou seja, existe em uma única conversa ou tarefa e é redefinida ou apagada quando a sessão termina, a menos que seja explicitamente salva em outro lugar. Um exemplo de memória de curto prazo ligada a sessões seria o chat temporáriodisponível no ChatGPT.

A memória de longo prazo, por outro lado, refere-se a informações que persistem ao longo de conversas ou sessões. Este é o conhecimento que um agente retém ao longo do tempo, fatos que aprendeu anteriormente, preferências do usuário ou quaisquer dados que pedimos para ele lembrar permanentemente.

A memória de longo prazo geralmente é implementada armazenando e recuperando dados de uma fonte externa, como um arquivo ou banco de dados vetorial fora do contexto imediato da janela. Diferentemente do histórico de chats de curto prazo, a memória de longo prazo não é incluída automaticamente em todas as solicitações. Em vez disso, com base em um determinado cenário, o agente deve recordá-lo ou recuperá-lo quando as ferramentas relevantes forem invocadas. Na prática, a memória de longo prazo pode incluir informações de perfil do usuário, respostas ou análises anteriores produzidas pelo agente, ou uma base de conhecimento que o agente pode consultar.

Por exemplo, se você tiver um agente de planejamento de viagens, a memória de curto prazo conterá detalhes da consulta de viagem atual (datas, destino, orçamento) e quaisquer perguntas subsequentes feitas durante o chat; enquanto a memória de longo prazo poderá armazenar as preferências gerais de viagem do usuário, itinerários anteriores e outros dados compartilhados em sessões anteriores. Quando o usuário retornar posteriormente, o agente poderá recorrer a esse histórico (por exemplo, o usuário adora praias e montanhas, tem um orçamento médio de 100.000 rúpias indianas, possui uma lista de lugares para visitar antes de morrer e prefere vivenciar história e cultura em vez de atrações voltadas para crianças), de modo que não trate o usuário como uma folha em branco a cada vez.

A memória de curto prazo (histórico de chats) fornece contexto e continuidade imediatos, enquanto a memória de longo prazo fornece um contexto mais amplo que o agente pode usar quando necessário. Os frameworks de agentes de IA mais avançados permitem ambas as coisas: mantêm o controle dos diálogos recentes para manter o contexto e oferecem mecanismos para consultar ou armazenar informações em um repositório de longo prazo. O gerenciamento da memória de curto prazo garante que ela permaneça dentro da janela de contexto, enquanto o gerenciamento da memória de longo prazo ajuda o agente a basear as respostas com base em interações e personalidades anteriores.

Memória e RAG na engenharia de contexto

Como damos a um agente de IA uma memória útil de longo prazo na prática?

Uma abordagem proeminente para a memória de longo prazo é a memória semântica, frequentemente implementada por meio de retrieval-augmented generation (RAG). Isso envolve acoplar o LLM a um armazenamento de conhecimento externo ou a um datastore habilitado por vetor, como o Elasticsearch. Quando o LLM precisa de informações além do que está no prompt ou em seu treinamento integrado, ele realiza uma recuperação semântica contra o Elasticsearch e injeta os resultados mais relevantes no prompt como contexto. Dessa forma, o contexto efetivo do modelo inclui não apenas a conversa recente (memória de curto prazo), mas também fatos pertinentes de longo prazo obtidos em tempo real. O LLM então fundamenta sua resposta tanto em seu próprio raciocínio quanto nas informações recuperadas, combinando efetivamente memória de curto prazo e memória de longo prazo para produzir uma resposta mais precisa e consciente do contexto.

O Elasticsearch pode ser usado para implementar memória de longo prazo para agentes de IA. Aqui está um exemplo de alto nível de como o contexto pode ser recuperado do Elasticsearch para memória de longo prazo.

Dessa forma, o agente "se lembra" pesquisando dados relevantes em vez de armazenar tudo em seu prompt limitado, onde isso leva a diferentes riscos.

Usar RAG com o Elasticsearch ou qualquer armazenamento vetorial oferece múltiplos benefícios:

Primeiro, ele amplia o conhecimento do modelo além do limite de treinamento. O agente pode recuperar informações atualizadas ou dados específicos do domínio que o LLM talvez não conheça. Isso é crucial para perguntas sobre eventos recentes ou tópicos especializados.

Em segundo lugar, recuperar o contexto sob demanda ajuda a reduzir alucinações, especialmente porque os LLMs não são treinados com dados proprietários ou altamente especializados relativos ao seu caso de uso específico, o que é muito provável que os exponha a alucinações. Em vez de o LLM adivinhar ou inventar novas informações, como tem sido incentivado pela avaliação, conforme destacado em um artigo recente da OpenAI (Why Language Models Hallucinate), o modelo pode ser fundamentado em referências factuais do Elasticsearch. Naturalmente, o LLM depende da confiabilidade dos dados no armazenamento vetorial para realmente evitar desinformação e os dados relevantes são recuperados de acordo com as medidas de relevância do núcleo.

Terceiro, o RAG permite que um agente trabalhe com bases de conhecimento muito maiores do que qualquer coisa que você poderia encaixar em um prompt. Em vez de inserir documentos inteiros, como longos artigos de pesquisa ou documentos de políticas, na janela de contexto e correr o risco de sobrecarga ou de informações irrelevantes contaminarem o raciocínio do modelo, o RAG se baseia em fragmentação. Documentos grandes são divididos em partes menores e semanticamente significativas, e o sistema recupera apenas os poucos trechos mais relevantes para a consulta. Dessa forma, o modelo não precisa de um contexto de um milhão de tokens para parecer conhecedor; ele só precisa de acesso aos pedaços certos de um corpus muito maior.

Vale ressaltar que, com o aumento das janelas de contexto do LLM (alguns modelos agora suportam centenas de milhares ou até milhões de tokens), surgiu um debate sobre se o RAG está "morto". Por que não enviar todos os dados para o prompt? Se você pensa da mesma forma, consulte este maravilhoso artigo de meus colegas Jeffrey Rengifo e Eduard Martin, Longer context ≠ better: Why RAG still matters. Isso evita o problema de "lixo entra, lixo sai": o LLM fica focado nos poucos pedaços que importam, em vez de passar por meio de ruído.

Dito isso, integrar o Elasticsearch ou qualquer armazenamento vetorial em uma arquitetura de agente de IA fornece memória de longo prazo. O agente armazena conhecimento externamente e o recolhe como contexto de memória quando necessário. Isso poderia ser implementado como uma arquitetura, onde, após cada consulta do usuário, o agente realiza uma busca no Elasticsearch por informações relevantes e então adiciona os principais resultados ao prompt antes de chamar o LLM. A resposta também pode ser salva de volta no armazenamento de longo prazo se contiver informações novas úteis (criando um ciclo de retroalimentação de aprendizado). Ao usar essa memória baseada em recuperação, o agente permanece informado e atualizado, sem precisar condensar tudo o que sabe em cada prompt, mesmo que a janela de contexto suporte um milhão de tokens. Essa técnica é uma pedra angular da engenharia de contexto, combinando os pontos fortes da recuperação de informação e da IA generativa.

Aqui está um exemplo de um estado gerenciado de conversa em memória usando o sistema de ponto de verificação do LangGraph para memória de curto prazo durante a sessão. (Consulte nosso app de engenharia de contexto de suporte).

Veja como ele armazena pontos de verificação:

Para a memória de longo prazo, veja como realizamos a busca semântica no Elasticsearch para recuperar conversas anteriores relevantes usando embeddings de vetor após resumir e a indexar pontos de verificação no Elasticsearch.

Agora que exploramos como a memória de curto prazo e a memória de longo prazo são indexadas e buscadas usando os pontos de verificação do LangGraph no Elasticsearch, vamos tirar um tempo para entender por que a indexação e o despejo das conversas completas podem ser arriscados.

Riscos de não gerenciar a memória de contexto

Como estamos falando muito sobre engenharia de contexto, junto com memória de curto e longo prazo, vamos entender o que acontece se não gerenciarmos bem a memória e o contexto de um agente.

Infelizmente, muitas coisas podem dar errado quando o contexto de uma IA se torna extremamente longo ou contém informações erradas. À medida que as janelas de contexto aumentam, surgem novos modos de falha, como:

• Envenenamento de contexto

• Distração contextual

• Confusão de contexto

• Conflito de contexto

• Vazamento de contexto e conflitos de conhecimento

• Alucinações e desinformação

Vamos analisar esses problemas e outros riscos que surgem do gerenciamento inadequado de contexto:

Envenenamento de contexto

O envenenamento do contexto refere-se a quando informações incorretas ou prejudiciais acabam no contexto e "envenenam" as saídas subsequentes do modelo. Um exemplo comum é uma alucinação do modelo que é tratada como fato e inserida no histórico da conversa. O modelo pode então construir sobre esse erro em respostas posteriores, agravando o erro. Em ciclos iterativos de agentes, uma vez que uma informação falsa entra no contexto compartilhado (por exemplo, em um resumo das notas de trabalho do agente), ela pode ser reforçada repetidamente.

Pesquisadores da DeepMind, no lançamento do relatório Gemini 2.5 (TL;DR, veja aqui), observaram o seguinte em um agente que jogava Pokémon: se o agente alucinasse um estado incorreto de jogo e isso fosse registrado em seu contexto (a memória de objetivos), o agente criaria estratégias sem sentido em torno de um objetivo impossível e ficaria preso. Em outras palavras, uma memória envenenada pode levar o agente pelo caminho errado indefinidamente.

O envenenamento de contexto pode acontecer inocentemente (por engano) ou até mesmo de forma mal-intencionada, por exemplo, por meio de ataques de injeção de prompt, onde um usuário ou terceiro introduz uma instrução oculta ou um fato falso que o agente então lembra e segue.

Contramedidas recomendadas:

Com base nos insights de Wiz, Zerlo e Anthropic, as contramedidas para envenenamento de contexto se concentram em evitar que informações ruins ou enganosas entrem no prompt, na janela de contexto ou no pipeline de recuperação de um LLM. Os principais passos incluem:

• Verifique o contexto constantemente: monitore a conversa ou o texto recuperado para qualquer coisa suspeita ou prejudicial, não apenas o prompt inicial.

• Use fontes confiáveis: pontue ou rotule documentos com base na credibilidade para que o sistema prefira informações confiáveis e ignore dados com pontuação baixa.

• Identifique dados incomuns: use ferramentas que detectem conteúdo estranho, fora de lugar ou manipulado, e remova-o antes que o modelo os utilize.

• Filtre entradas e saídas: adicione proteções de segurança para que textos prejudiciais ou enganosos não possam entrar facilmente no sistema ou ser repetidos pelo modelo.

• Mantenha o modelo atualizado com dados limpos: atualize regularmente o sistema com informações verificadas para combater qualquer dado errado que tenha escapado.

• Com supervisão humana: peça para as pessoas revisarem as saídas importantes ou compará-las com fontes conhecidas e confiáveis.

Hábitos simples do usuário também ajudam, como redefinir chats longos, compartilhar apenas informações relevantes, dividir tarefas complexas em etapas menores e manter anotações claras fora do modelo.

Juntas, essas medidas criam uma defesa em camadas que protege os LLMs contra envenenamento do contexto e mantém as saídas precisas e confiáveis.

Sem contramedidas mencionadas aqui, um agente pode lembrar-se de instruções, como ignorar diretrizes anterioresou fatos triviais inseridos por um invasor, levando a saídas prejudiciais.

Distração contextual

A distração de contexto ocorre quando um contexto se alonga tanto que o modelo foca demais no contexto, negligenciando o que aprendeu durante o treinamento. Em casos extremos, isso se assemelha ao esquecimento catastrófico; ou seja, o modelo efetivamente "esquece" seu conhecimento subjacente e fica excessivamente apegado à informação que lhe é apresentada. Estudos anteriores mostraram que LLMs frequentemente perdem o foco quando o prompt é extremamente longo.

O agente Gemini 2.5, por exemplo, suportava uma janela de um milhão de tokens, mas quando seu contexto crescia além de um certo ponto (na ordem de 100.000 tokens em um experimento), ele começava a se fixar em repetir suas ações passadas em vez de apresentar novas soluções. De certa forma, o agente tornou-se prisioneiro de sua extensa história. Ele continuava observando seu longo log de movimentos anteriores (o contexto) e imitando-os, em vez de usar seu conhecimento de treinamento subjacente para criar estratégias novas e inovadoras.

Isso é contraproducente. Queremos que o modelo use o contexto relevante para ajudar no raciocínio, não para sobrepor sua capacidade de pensar. Notavelmente, mesmo modelos com janelas enormes exibem essa deterioração de contexto: seu desempenho se degrada de forma não uniforme à medida que mais tokens são adicionados. Parece haver um orçamento de atenção. Como humanos com memória de trabalho limitada, um LLM tem uma capacidade finita para atender a tokens, e à medida que esse orçamento é esticado, sua precisão e foco caem.

Como mitigação, você pode evitar distração do contexto usando fragmentação, engenharia das informações corretas, resumo regular do contexto e técnicas de avaliação e monitoramento para medir a precisão da resposta usando pontuação.

Esses métodos mantêm o modelo baseado no contexto relevante e em seu treinamento subjacente, reduzindo o risco de distração e melhorando a qualidade geral do raciocínio.

Confusão de contexto

A confusão de contexto ocorre quando o conteúdo supérfluo no contexto é usado pelo modelo para gerar uma resposta de baixa qualidade. Um ótimo exemplo é fornecer a um agente um grande conjunto de ferramentas ou definições de API que ele pode usar. Se muitas dessas ferramentas não estiverem relacionadas à tarefa atual, o modelo ainda pode tentar usá-las de forma inadequada, simplesmente porque elas estão presentes no contexto. Experimentos descobriram que fornecer mais ferramentas ou documentos pode prejudicar o desempenho se não forem todos necessários. O agente começa a cometer erros, como chamar a função errada ou fazer referência a um texto irrelevante.

Em um caso, um pequeno modelo Llama 3.1 8B falhou em uma tarefa ao receber 46 ferramentas para considerar, mas teve sucesso quando recebeu apenas 19 ferramentas. As ferramentas extras criaram confusão, mesmo que o contexto estivesse dentro dos limites de duração. A questão subjacente é que qualquer informação no prompt será atendida pelo modelo. Se não souber ignorar algo, esse algo pode influenciar sua saída de maneiras indesejadas. Pedaços irrelevantes podem “roubar” parte da atenção do modelo e desviá-lo (por exemplo, um documento irrelevante pode fazer com que o agente responda a uma pergunta diferente da feita). A confusão de contexto frequentemente se manifesta como o modelo produzindo uma resposta de baixa qualidade que integra contextos não relacionados. Consulte o trabalho de pesquisa: Menos é mais: otimizando a chamada de funções para execução LLM em dispositivos de borda.

Isso nos lembra que mais contexto nem sempre é melhor, especialmente se não for selecionado para ser relevante.

Conflito de contexto

O conflito de contexto ocorre quando partes do contexto se contradizem, causando inconsistências internas que comprometem o raciocínio do modelo. Um conflito pode acontecer se o agente acumular várias informações que estão em conflito.

Por exemplo, imagine um agente que obteve dados de duas fontes: uma diz que o voo A parte às 17h, e a outra diz que o voo A parte às 18h. Se ambos os fatos estiverem presentes no contexto, o modelo inadequado não terá como saber qual está correto; poderá ficar confuso ou produzir uma resposta incorreta ou não similar.

O conflito de contexto também ocorre com frequência em conversas com várias interações, em que as tentativas anteriores de resposta do modelo ainda permanecem no contexto junto com informações refinadas posteriormente.

Um estudo realizado pela Microsoft e pela Salesforce mostra que, ao dividir uma consulta complexa em várias interações com o chatbot (adicionando detalhes gradualmente), a precisão final cai significativamente em comparação com a apresentação de todos os detalhes em uma única solicitação. Por quê? Porque as primeiras interações contêm respostas intermediárias parciais ou incorretas do modelo, e essas permanecem no contexto. Quando o modelo tenta responder posteriormente com todas as informações, sua memória ainda inclui as tentativas erradas, que entram em conflito com as informações corrigidas e o desviam do caminho. Basicamente, o contexto da conversa entra em conflito consigo mesmo. O modelo pode, sem querer, usar um contexto desatualizado (de uma interação anterior) que não se aplica depois que novas informações são adicionadas.

Em sistemas de agentes, o choque de contexto é especialmente perigoso, pois um agente pode combinar saídas de diferentes ferramentas ou subagentes. Se essas saídas discordarem, o contexto agregado será inconsistente. O agente pode, então, ficar travado ou produzir resultados sem sentido ao tentar conciliar as contradições. Evitar conflitos de contexto envolve garantir que o contexto seja novo e consistente,por exemplo, limpar ou atualizar qualquer informação desatualizada e não misturar fontes que não tenham sido verificadas quanto à consistência.

Vazamento de contexto e conflitos de conhecimento

Em sistemas onde múltiplos agentes ou usuários compartilham um estoque de memória, há o risco de informações transbordarem entre os contextos.

Por exemplo, se os dados de embeddings de dois usuários diferentes residirem no mesmo banco de dados vetorial sem o devido controle de acesso, um agente que responde à consulta do Usuário A pode, acidentalmente, recuperar parte da memória do Usuário B. Esse vazamento entre contextos pode expor informações privadas ou apenas criar confusão nas respostas.

De acordo com o OWASP Top 10 for LLM Applications, os bancos de dados vetoriais multilocatários devem se proteger contra esse tipo de vazamento:

De acordo com LLM08:2025 — Fraquezas em Vetores e Embeddings, um dos riscos comuns é o vazamento de contexto:

Outro aspecto é que um LLM pode ter dificuldade em substituir seu conhecimento integrado por novas informações da memória. Se o modelo foi treinado em algum fato e o contexto recuperado diz o oposto, o modelo pode ficar confuso sobre qual confiar. Sem um design adequado, o agente pode misturar contextos ou não conseguir atualizar o conhecimento antigo com novas evidências, levando a respostas desatualizadas ou incorretas.

Alucinações e desinformação

Embora a alucinação (o LLM inventando informações plausíveis, mas falsas) seja um problema conhecido, mesmo sem contextos longos, o gerenciamento inadequado da memória pode amplificá-lo. Você pode ter que se preocupar com o fato de que o LLM não está preparado para isso.

Se faltar um fato crucial na memória do agente, o modelo pode simplesmente preencher a lacuna com um palpite e, se esse palpite entrar no contexto (envenenando-o), o erro persistirá.

O relatório de segurança OWASP LLM (LLM09:2025 — Desinformação) destaca a desinformação como uma vulnerabilidade central: os modelos de aprendizagem de linguagem (LLMs) podem produzir respostas confiantes, porém fabricadas, e os usuários podem confiar excessivamente nelas. Um agente com uma memória de longo prazo ruim ou desatualizada pode citar com segurança algo que era verdadeiro no ano passado, mas é falso agora, a menos que sua memória seja mantida atualizada.

A dependência excessiva da saída da IA (seja pelo usuário ou pelo próprio agente em um loop) pode piorar isso. Se ninguém nunca conferir as informações na memória, o agente pode acumular falsidades. É por isso que o RAG é frequentemente usado para reduzir alucinações: ao recuperar uma fonte autoritativa, o modelo não precisa inventar fatos. Mas se sua recuperação extrair o documento errado (digamos, um que contenha informações erradas) ou se uma alucinação precoce não for eliminada, o sistema poderá propagar essa desinformação por meio de suas ações.

O resultado final: deixar de gerenciar a memória pode levar a saídas incorretas e enganosas, o que pode ser prejudicial, especialmente se os riscos forem altos (por exemplo, conselhos ruins em um domínio financeiro ou médico). Um agente precisa de mecanismos para verificar ou corrigir seu conteúdo de memória, não apenas confiar incondicionalmente em qualquer coisa que esteja no contexto.

Em resumo, dar a um agente de IA uma memória infinitamente longa ou despejar todas as coisas possíveis em seu contexto não é uma receita para o sucesso.

Práticas recomendadas para o gerenciamento de memória em aplicações LLM

Para evitar as armadilhas acima, os desenvolvedores e pesquisadores criaram uma série de práticas recomendadas para gerenciar o contexto e a memória nos sistemas de IA. Essas práticas visam manter o contexto de trabalho da IA enxuto, relevante e atualizado. Aqui estão algumas das principais estratégias, além de exemplos de como elas ajudam.

RAG: use contexto direcionado

Grande parte do conceito RAG já foi abordada na seção anterior, portanto, este texto serve como um conjunto conciso de lembretes práticos:

• Use recuperação direcionada, não carregamento em massa: recupere apenas os trechos mais relevantes em vez de enviar documentos inteiros ou históricos completos de conversas para o prompt.

• Considere o RAG como uma recuperação de memória sob demanda: busque o contexto apenas quando necessário, em vez de carregar tudo adiante entre as interações.

• Prefira estratégias de recuperação com base na relevância: abordagens como busca semântica top k, fusão de classificação recíproca ou filtragem de carga de ferramentas ajudam a reduzir o ruído e melhorar o aterramento.

• Janelas de contexto maiores não eliminam a necessidade do RAG: dois parágrafos altamente relevantes quase sempre são mais eficazes do que 20 páginas vagamente relacionadas.

Dito isso, o RAG não se trata de adicionar mais contexto; trata-se de adicionar o contexto certo.

Configuração de ferramentas

O carregamento de ferramentas consiste em fornecer a um modelo apenas as ferramentas de que ele realmente precisa para uma tarefa. O termo vem de jogos: você escolhe um carregamento que se adequa à situação. Muitas ferramentas atrasam você; as erradas causam falhas. LLMs se comportam da mesma forma, segundo o artigo Menos é mais. Depois que você passa por ~30 ferramentas, as descrições começam a se sobrepor e o modelo fica confuso. Depois de ~100 ferramentas, o fracasso é quase garantido. Isso não é um problema de janela de contexto, é confusão de contexto.

Uma solução simples e eficaz é o RAG-MCP. Em vez de inserir todas as ferramentas no prompt, as descrições das ferramentas são armazenadas em um banco de dados vetorial e somente as mais relevantes são recuperadas por solicitação. Na prática, isso mantém o carregamento pequeno e focado, encurta drasticamente os prompts e pode melhorar a precisão da seleção de ferramentas em até 3 vezes.

Modelos menores batem nessa barreira ainda mais cedo. A pesquisa mostra que um modelo 8B falha com dezenas de ferramentas, mas tem sucesso assim que o equipamento é cortado. Selecionar ferramentas dinamicamente, às vezes primeiro com um LLM, raciocinar sobre o que ele acha que precisa, pode aumentar o desempenho em 44%, além de reduzir o consumo de energia e a latência. A conclusão é que a maioria dos agentes precisa apenas de algumas ferramentas, mas à medida que seu sistema cresce, o carregamento de ferramentas e o RAG-MCP se tornam decisões de design de primeira ordem.

Eliminação de contexto: limite o tempo do histórico de chat

Se uma conversa continuar por várias interações, o histórico de chat acumulado pode ficar muito extenso, causando um excesso de contexto ou distraindo demais o modelo.

Aparar significa remover ou encurtar programaticamente as partes menos importantes do diálogo à medida que ele cresce. Uma forma simples é eliminar as interações mais antigas da conversa quando você atingir um determinado limite, mantendo apenas as N mensagens mais recentes. Uma eliminação mais sofisticada pode remover digressões irrelevantes ou instruções anteriores que não são mais necessárias. O objetivo é manter a janela de contexto desobstruída de notícias antigas.

Por exemplo, se o agente resolveu um subproblema há 10 interações e nós seguimos em frente desde então, podemos excluir essa parte do histórico do contexto (assumindo que não será mais necessário). Muitas implementações baseadas em chat fazem isso: elas mantêm uma janela móvel de mensagens recentes.

Aparar pode ser tão simples quanto "esquecer" as partes mais iniciais de uma conversa depois que elas foram resumidas ou consideradas irrelevantes. Ao fazer isso, reduzimos o risco de erros de excesso de contexto e também diminuímos a distração do contexto, para que o modelo não veja e se distraia com conteúdo antigo ou fora do tema. Essa abordagem é muito parecida com como os humanos podem não lembrar cada palavra de uma conversa de uma hora, mas manterão os destaques.

Se você está confuso sobre a eliminação de contexto, como destacado pelo autor Drew Breunig aqui, o uso do modelo Provence (`naver/provence-reranker-debertav3-v1`), um eliminador de contexto leve (1,75 GB), eficiente e preciso para resposta a perguntas, pode fazer a diferença. Ele pode reduzir documentos grandes apenas para o texto mais relevante para uma determinada consulta. Você pode chamá-lo em intervalos específicos.

Veja como invocamos o modelo 'provence-reranker' em nosso código para eliminar o contexto:

Usamos o modelo Provence reranker (`naver/provence-reranker-debertav3-v1`) para pontuar a relevância da frase. A filtragem baseada em limiar mantém as sentenças acima do limiar de relevância. Além disso, introduzimos um mecanismo de fallback, no qual retornamos ao contexto original se a eliminação falhar. Por fim, o logging de estatísticas acompanha a porcentagem de redução em modo detalhado.

Resumo do contexto: condense informações antigas em vez de descartá-las completamente

O resumo é um complemento para redução. Quando a história ou a base de conhecimento se tornar muito grande, você pode usar o LLM para gerar um breve resumo dos pontos importantes e usar esse resumo no lugar do conteúdo completo daqui para frente, como fizemos no código acima.

Por exemplo, se um assistente de IA tiver tido uma conversa de 50 interações, em vez de enviar todas as 50 interações para o modelo na interação 51 (o que provavelmente não caberia), o sistema poderia pegar as interações de 1 a 40, fazer com que o modelo as resumisse em um parágrafo e, em seguida, fornecer apenas esse resumo mais as 10 últimas interações na próxima solicitação. Dessa forma, o modelo ainda sabe o que foi discutido sem precisar de todos os detalhes. Os primeiros usuários de chatbots faziam isso manualmente perguntando: "Você pode resumir o que discutimos até agora?" e então continuando em uma nova sessão com o resumo. Agora isso pode ser automatizado. O resumo não apenas economiza espaço na janela de contexto, mas também pode reduzir a confusão/distração do contexto ao eliminar detalhes extras e reter apenas os fatos mais importantes.

Veja como usamos modelos OpenAI (você pode usar qualquer LLMs) para condensar o contexto preservando todas as informações relevantes, eliminando redundância e duplicação.

É importante ressaltar que, quando o contexto é resumido, o modelo tem menos probabilidade de ser sobrecarregado por detalhes triviais ou erros passados (presumindo que o resumo seja preciso).

No entanto, o resumo deve ser feito com cuidado. Um resumo ruim pode omitir um detalhe crucial ou até mesmo introduzir um erro. É basicamente mais um prompt para o modelo ("resuma isso"), então ele pode alucinar ou perder nuances. A melhor prática é resumir de forma incremental e talvez manter alguns fatos canônicos sem resumo.

Ainda assim, tem se mostrado muito útil. No cenário do agente Gemini, resumir o contexto a cada ~100k tokens era uma forma de combater a tendência do modelo de se repetir. O resumo funciona como uma memória comprimida da conversa ou dos dados. Como desenvolvedores, podemos implementar isso fazendo com que um agente chame periodicamente uma função de resumo (talvez um LLM menor ou uma rotina dedicada) no histórico de conversas ou em um documento longo. O resumo resultante substitui o conteúdo original no prompt. Essa tática é amplamente usada para manter os contextos dentro de limites e destilar as informações.

Quarentena de contexto: isole contextos sempre que possível

Isso é mais relevante em sistemas de agentes complexos ou fluxos de trabalho de múltiplas etapas. A ideia da segmentação de contexto é dividir uma grande tarefa em tarefas menores e isoladas, cada uma com seu próprio contexto, de modo que você nunca acumule um contexto enorme que contenha tudo. Cada subagente ou subtarefa trabalha em uma parte do problema com um contexto focado e, em seguida, um agente, supervisor ou coordenador de nível superior integra os resultados.

A estratégia de pesquisa da Anthropic utiliza múltiplos subagentes, cada um investigando um aspecto diferente de uma questão, com suas próprias janelas de contexto, e um agente líder que lê os resultados sintetizados desses subagentes. Essa abordagem paralela e modular significa que nenhuma janela de contexto única fica excessivamente inchada. Também reduz a chance de mistura de informações irrelevantes, cada tópico permanece no tópico (sem confusão de contexto) e não carrega bagagem desnecessária ao responder sua subpergunta específica. De certa forma, é como seguir fios de pensamento separados que só compartilham seus resultados, não todo o processo de pensamento.

Em sistemas multiagente, essa abordagem é essencial. Se o Agente A estiver lidando com a tarefa A e o Agente B estiver lidando com a tarefa B, não há motivo para que um dos agentes consuma o contexto completo do outro, a menos que seja realmente necessário. Em vez disso, os agentes podem trocar apenas as informações necessárias. Por exemplo, o Agente A pode passar um resumo consolidado de suas descobertas para o Agente B por meio de um agente supervisor, enquanto cada subagente mantém seu próprio thread de contexto dedicado. Essa configuração não exige supervisão; ela depende de um agente supervisor com ferramentas habilitadas e compartilhamento de contexto mínimo e controlado.

No entanto, projetar seu sistema de modo que agentes ou ferramentas operem com a sobreposição mínima necessária de contexto pode aumentar muito a clareza e o desempenho. Pense nisso como microsserviços para IA, cada componente lida com seu contexto e você passa mensagens entre eles de forma controlada, em vez de um contexto monolítico. Essas práticas recomendadas são frequentemente usadas em combinação. Além disso, isso dá a você a flexibilidade de cortar histórico trivial, resumir mensagens ou conversas antigas importantes, transferir os logs detalhados para o Elasticsearch para contexto de longo prazo e usar a recuperação para trazer de volta qualquer coisa relevante quando necessário.

Como mencionado aqui, o princípio orientador é que o contexto é um recurso limitado e precioso. Você quer que cada token do prompt ganhe seu valor, ou seja, ele deve contribuir para a qualidade da saída. Se algo na memória não está fazendo sua parte (ou pior, causando confusão ativamente), então deve ser eliminado, resumido ou mantido fora.

Como desenvolvedores, agora podemos programar o contexto da mesma forma que programamos o código, decidindo quais informações incluir, como formatá-las e quando omiti-las ou atualizá-las. Seguindo essas práticas, podemos fornecer aos agentes LLM o contexto necessário para executar tarefas sem incorrer nas falhas descritas anteriormente. O resultado são agentes que lembram do que deveriam, esquecem o que não precisam e recuperam o que precisam a tempo.

Conclusão

Memória não é algo que você adiciona a um agente; é algo que você projeta. A memória de curto prazo é o bloco de trabalho do agente, e a memória de longo prazo é seu armazenamento de conhecimento duradouro. O RAG serve de ponte entre os dois, transformando um armazenamento de dados passivo, como o Elasticsearch, em um mecanismo de recuperação ativo que pode ancorar as saídas e manter o agente atualizado.

Mas a memória é uma faca de dois gumes. No momento em que você deixa o contexto crescer sem controle, você gera envenenamento, distração, confusão e conflitos e, em sistemas compartilhados, até mesmo vazamento de dados. Por isso, o trabalho mais importante com a memória não é "armazenar mais", mas sim "selecionar melhor": recuperar seletivamente, eliminar agressivamente, resumir cuidadosamente e evitar misturar contextos não relacionados, a menos que a tarefa realmente o exija.

Na prática, uma boa engenharia de contexto se assemelha a um bom projeto de sistemas: contextos menores e suficientes, interfaces controladas entre os componentes e uma clara separação entre o estado bruto e o estado refinado que você realmente deseja que o modelo veja. Se feito corretamente, você não acaba com um agente que lembra de tudo — você acaba com um agente que lembra das coisas certas, na hora certa, pelo motivo certo.

O Elastic Agent Builder facilita a criação de agentes de IA conectados a dados. Mostraremos como fazer isso neste post do blog. Vamos passar por todos os passos necessários para criar um agente com uma ferramenta MCP que acesse os dados armazenados no Elastic. Depois, usaremos o Strands Agents SDK e os recursos Agent2Agent (A2A) para operar o agente. O Strands Agents SDK é uma plataforma de desenvolvimento de IA multiagente que você pode usar para criar apps agentes com código suficiente para garantir o resultado desejado.

Vamos construir um agente de IA que jogue RPS+, uma versão do clássico jogo Pedra, Papel e Tesoura com um diferencial: oferece aos jogadores algumas opções extras.

Pré-requisitos

Aqui está o que é necessário para seguir as etapas deste post do blog:

• Um editor de texto rodando no seu computador local

  • Visual Studio Code é o que usaremos para as instruções de exemplo neste post do blog

• Python 3.10 ou superior rodando no seu computador local

Crie um projeto serverless

A primeira coisa de que precisamos é de um projeto Elasticsearch Serverless, que inclua o Elastic Agent Builder.

Acesse cloud.elastic.co e crie um novo projeto Elasticsearch Serverless.

Crie um índice e adicione dados

Em seguida, adicionaremos alguns dados ao nosso projeto Elasticsearch. Abra as Ferramentas de desenvolvedor, onde podemos executar comandos para criar um novo índice e inserir alguns dados. Selecione Ferramentas de desenvolvedor no menu de navegação de nível superior.

Copie e cole o seguinte comando PUT na área de entrada de solicitações do console Ferramentas de desenvolvedor. Essa declaração cria um índice Elasticsearch chamado "game-docs".

Clique no botão Enviar solicitação que aparece no lado direito da declaração em Ferramentas de desenvolvedor. Você deve ver uma notificação confirmando que o índice game-docs foi criado na área de resposta das Ferramentas de desenvolvedor.

Um índice chamado game-docs é um ótimo lugar para armazenar os dados do jogo que estamos criando. Vamos colocar um documento chamado rps+-md nesse índice que contém todos os dados que nosso jogo requer. Copie e cole o seguinte comando PUT no console Ferramentas de desenvolvedor.

Clique no botão Enviar solicitação ao lado da declaração para executá-la e adicionar o documento rps+-md ao índice game-docs.

Agora devemos ter alguns dados para consultar e, com o Agent Builder, isso está mais simples do que nunca.

Selecione Agentes no menu de navegação principal.

Agora, é preciso perguntar ao Elastic AI Agent padrão: "Quais dados eu tenho?"

O Elastic AI Agent avalia os dados e retorna uma explicação concisa sobre os dados que possuímos.

Crie uma ferramenta

Ok, agora temos alguns dados no Elastic, vamos utilizá-los. O Agent Builder inclui suporte integrado para criar ferramentas MCP que ajudam os agentes a acessar os dados necessários para ter o contexto correto para a tarefa. Vamos criar uma ferramenta simples que recupere os dados do nosso jogo.

Clique no menu de ações do Agent Builder.

Selecione Ver todas as ferramentas nas opções do menu.

Clique + Nova Ferramenta.

No formulário Criar Ferramenta, selecione ES|QL.Selecione a ferramenta Tipo e insira os valores a seguir.

Para o ID da Ferramenta:

Para Descrição:

Para Configuração, insira a seguinte consulta na área de texto Mecanismo de consulta ES|QL:

O formulário Criar ferramenta que você preencheu deve ter esta aparência: Clique em Salvar para criar a ferramenta.

Temos uma ferramenta nova no suporte de ferramentas. As ferramentas não devem ficar num suporte; elas devem ser usadas. Vamos criar um agente que possa usar nossa nova ferramenta personalizada.

Crie um agente e atribua uma ferramenta a ele.

Criar um agente é muito simples com o Agent Builder. Você só precisa digitar as instruções do agente com alguns detalhes. Vamos criar um agente agora.

Clique no botão Gerenciar agentes.

Clique + Novo agente.

Insira as informações a seguir no formulário Novo Agente.

Para o ID do Agente, insira o texto abaixo:

Na área de texto de Instruções personalizadas, insira as seguintes instruções:

Para o Nome de exibição, insira o texto abaixo:

Para a Descrição de exibição, insira o texto abaixo:

Dê ao agente a ferramenta personalizada que criamos anteriormente, clicando na guia Ferramentas.

Selecione somente a ferramenta example.get_game_docs que criamos anteriormente.

Clique em Salvar para criar o novo agente.

Vamos testar nosso novo agente. Há um link prático para iniciar um bate-papo com qualquer agente da lista de agentes.

Basta digitar “iniciar jogo” e o jogo começará. Funciona!

O agente exibe a escolha de objeto de jogo na parte superior da resposta. Isso é útil porque podemos ver a escolha do agente e confirmar que o jogo está funcionando conforme o esperado. No entanto, saber a escolha do oponente antes de escolher não torna o jogo de Pedra, Papel e Tesoura muito divertido. Para aperfeiçoar e aprimorar o jogo até a forma final, podemos usar uma plataforma de orquestração de agentes que pode controlar agentes com código.

Agora é a hora do Strands Agents SDK.

Strands Agents SDK

Se você tem curiosidade em experimentar novas estruturas de desenvolvimento de agentes, então vale a pena dar uma chance ao Strands Agents SDK. O Strands Agents SDK foi lançado pela AWS (maio de 2025) como uma implementação open source em Python, e agora também existe uma versão em Typescript.

Começando com o Strands Agents SDK em Python

Preparem seus motores de programação, pois agora vamos percorrer o processo de clonagem e execução de um aplicativo de exemplo que usa Strands Agents para controlar o agente RPS+ por meio do protocolo A2A. Vamos criar uma versão aperfeiçoada do jogo RPS+ para que a escolha do agente seja revelada depois que você fizer a sua escolha, pois, afinal, é a adivinhação e o resultado surpreendente que tornam divertidos jogos como o Pedra, Papel e Tesoura.

No seu computador local, abra o Visual Studio Code e abra um novo terminal.

No terminal recém-aberto, execute o seguinte comando para clonar o repositório Elasticsearch Labs:

Execute o seguinte cd comando para alterar o diretório para o diretório elasticsearch-labs:

Em seguida, execute o seguinte comando para abrir o repositório no Visual Studio Code:

No Visual Studio File Explorer, expanda as pastas contenting-blog-content e agent-builder-a2a-strands-agents e abra o arquivo elastic_agent_builder_a2a_rps+.py. Veja a aparência do arquivo aberto no Visual Studio Code:

Aqui está o conteúdo de elastic_agent_builder_a2a_rps+.py que você deve ver no seu editor de texto:

Vamos revisar o que está acontecendo nesse código. Começando pelo método main(), o código começa acessando as variáveis de ambiente para a URL do agente e a Chave da API. Depois, usamos esses valores para criar um httpx client que podemos usar para obter o cartão de agente para o agente. O cliente então usa os detalhes do cartão do agente para enviar uma solicitação "iniciar jogo" ao agente. Uma coisa interessante a notar aqui é que incluímos um valor random_game_object como parte do pedido "start game". Esse valor é um número aleatório gerado com o módulo aleatório da biblioteca padrão do Python. A razão para fazer isso é que os poderosos LLMs (que possibilitam agentes de IA) não são bons em aleatoriedade. Não tema, Python vem pra salvar.

Continuando com o código, quando o agente responde à solicitação "iniciar jogo", o código remove a seleção de objeto de jogo do agente e a salva na variável agent_choice. O restante da resposta é exibido como texto para o usuário final. Em seguida, o usuário é solicitado a fornecer a entrada da sua escolha de objeto de jogo, que é enviada ao agente. O código então exibe a escolha do objeto de jogo do agente junto com a determinação final do agente sobre o resultado do jogo.

Definindo a URL do seu agente e a chave de API como variáveis de ambiente

Como o app de exemplo estará rodando no seu computador local, para nos comunicarmos com nosso agente Agent Builder, precisamos fornecer ao Strands Agents SDK uma URL A2A e uma chave API para o agente. O exemplo de app usa um arquivo chamado .env para armazenar esses valores.

Faça uma cópia do arquivo env.example e nomeie o novo arquivo como .env

Volte para o Elastic Agent Builder, onde podemos obter os dois valores que precisamos.

Selecione Exibir todas as ferramentas no menu de ação do Agent Builder no canto superior direito da página.

Clique no menu suspenso Servidor MCP na parte superior da página Ferramentas e selecione Copiar URL do Servidor MCP.

Cole o URL do servidor MCP no arquivo .env como um substituto para o valor do espaço reservado <YOUR-ELASTIC-AGENT-BUILDER-URL> . Agora precisamos fazer uma atualização no URL, ou seja, substituir o texto final “mcp” por “a2a”, pois o protocolo A2A é o que o Agent Strands SDK usará para se comunicar com o agente em execução no Elastic Agent Builder.

A URL editada deve ficar assim:

Outro valor que precisamos obter enquanto estamos aqui no Elastic Cloud é uma chave API. Clique em Elasticsearch na navegação de nível superior.

Clique no botão Copiar chave API para copiar a chave API.

Agora, de volta ao Visual Studio Code, cole a chave API no .env para substituir o texto provisório <YOUR-ELASTIC-API-KEY> . Seu arquivo .env deve ficar assim:

Execute o app de exemplo

Abra um novo terminal no Visual Studio Code.

Comece executando o seguinte comando cd no terminal:

Execute o seguinte comando para criar um ambiente virtual Python.

Dependendo do sistema operacional do seu computador local, execute o seguinte comando para ativar o ambiente virtual.

• MacOS/Linux

• Windows

O app de exemplo usa o Strands Agents SDK e agora estamos no ponto em que precisamos instalá-lo. Execute o seguinte comando para instalar o Strands Agents SDK junto com todas as dependências necessárias da biblioteca Python.

Hora de liberar a plataforma de lançamento e começar a contagem regressiva. Estamos prontos para executar este app. Afastem-se. Vamos executá-lo usando o seguinte comando:

Você deve ser desafiado com uma partida de RPS+. Parabéns e boa sorte!

Crie seus aplicativos de IA com contexto relevante

Construir um Agente de IA agora é uma habilidade disponível na sua caixa de ferramentas. E você já viu como é fácil usar agentes Elastic Agent Builder via A2A em frameworks de desenvolvimento de agentes como o Strands Agents SDK. Experimente a Elastic para criar agentes de IA conectados ao contexto relevante em seus dados personalizados.

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

O que é LangGraph

LangGraph é um framework para construir agentes de IA e orquestrá-los em um fluxo de trabalho para criar aplicações assistidas por IA. O LangGraph possui uma arquitetura de nós onde podemos declarar funções que representam tarefas e atribuí-las como nós do fluxo de trabalho. O resultado de múltiplos nós interagindo será um gráfico. O LangGraph faz parte do ecossistema mais amplo LangChain, que oferece ferramentas para construir sistemas de IA modulares e componíveis.

Para entender melhor por que o LangGraph é útil, vamos resolver uma situação problemática usando-o.

Visão geral da solução

Em uma empresa de capital de risco, os investidores têm acesso a um grande banco de dados com muitas opções de filtragem, mas quando se deseja combinar critérios, o processo se torna difícil e lento. Isso pode fazer com que algumas startups relevantes não sejam encontradas para investimento. Isso resulta em gastar muitas horas tentando identificar os melhores candidatos, ou até mesmo em perder oportunidades.

Com o LangGraph e o Elasticsearch, podemos realizar buscar filtradas utilizando linguagem natural, eliminando a necessidade de os usuários construírem manualmente solicitações complexas com dezenas de filtros. Para torná-lo mais flexível, o fluxo de trabalho decide automaticamente com base na entrada do usuário entre dois tipos de consultas:

• Consultas focadas em investimento: essas consultas visam aspectos financeiros e de financiamento de startups, como rodadas de financiamento, avaliação ou receita. Exemplo: "Encontre startups com financiamento Série A ou Série B entre US$ 8 milhões e US$ 25 milhões e receita mensal acima de US$ 500 mil."

• Consultas focadas no mercado: essas consultas concentram-se em verticais da indústria, mercados geográficos ou modelos de negócios, ajudando a identificar oportunidades em setores ou regiões específicos. Exemplo: “Encontre startups de fintech e saúde em São Francisco, Nova York ou Boston.”

Para manter a robustez das consultas, faremos com que o LLM crie modelos de busca em vez de consultas DSL completas. Assim, você sempre recebe a consulta que quer, e o LLM só precisa preencher as lacunas e não carregar a responsabilidade de construir a consulta que você precisa toda vez.

O que você precisa para começar

• APIKey do Elasticsearch

• APIKey do OpenAPI

• Node 18 ou mais recente

Instruções passo a passo

Nesta seção, vamos ver como o app ficará. Para isso, usaremos o TypeScript, um superconjunto do JavaScript que adiciona tipos estáticos para tornar o código mais confiável, fácil de manter e mais seguro, detectando erros precocemente e, ao mesmo tempo, permanecendo totalmente compatível com o JavaScript existente.

O fluxo dos nós terá a seguinte aparência:

A imagem acima é gerada pelo LangGraph e representa o fluxo de trabalho que define a ordem de execução e a lógica condicional entre nós:

• decideStrategy: utiliza um LLM para analisar a consulta do usuário e decidir entre duas estratégias de busca especializadas: focada em investimento ou focada no mercado.

• prepareInvestSearch: extrai valores de filtro da consulta e constrói um modelo pré-definido enfatizando parâmetros financeiros e relacionados ao financiamento.

• prepareMarketSearch: também extrai valores de filtro, mas constrói parâmetros dinamicamente enfatizando o mercado, o setor e o contexto geográfico.

• executeSearch: envia a consulta construída para o Elasticsearch usando um modelo de busca e recupera os documentos correspondentes de inicialização.

• visualizeResults: formata os resultados finais em um resumo claro e legível que mostra atributos-chave da startup, como financiamento, setor e receita.

Esse fluxo inclui uma ramificação condicional, funcionando como uma instrução “if”, que determina se deve usar o caminho de busca de investimentos ou de mercado com base na entrada do usuário. Essa lógica de decisão, conduzida pelo LLM, torna o fluxo de trabalho adaptável e sensível ao contexto, um mecanismo que exploraremos com mais detalhes nas próximas seções.

Estado do LangGraph

Antes de ver cada nó individualmente, precisamos entender como os nós se comunicam e compartilham dados. Para isso, o LangGraph nos permite definir o estado do fluxo de trabalho. Isso define o estado compartilhado que será passado entre os nós.

O estado funciona como um container compartilhado que armazena dados intermediários ao longo do fluxo de trabalho: começa com a consulta em linguagem natural do usuário, depois mantém a estratégia de busca selecionada, os parâmetros preparados para o Elasticsearch, os resultados de busca recuperados e, finalmente, a saída formatada.

Essa estrutura permite que cada nó leia e atualize o estado, garantindo um fluxo consistente de informações desde a entrada do usuário até a visualização final.

Configure o aplicativo

Todo o código desta seção pode ser encontrado no repositório elasticsearch-labs.

Abra um terminal na pasta em que o app estará localizado e inicialize um app Node.js com o comando:

Agora podemos instalar as dependências necessárias para este projeto:

• @elastic/elasticsearch: Nos ajuda a lidar com requisições do Elasticsearch, como ingestão e recuperação de dados.

• @langchain/langgraph: dependência de JS para fornecer todas as ferramentas LangGraph.

• @langchain/openaiCliente OpenAI LLM para LangChain.

• @langchain/núcleo: fornece os blocos de construção fundamentais para apps LangChain, incluindo modelos de prompt.

• dotenv: Dependência necessária para usar variáveis de ambiente em JavaScript.

• zod: Dependência para digitar dados.

@types/node tsx typescript nos permite escrever e executar o código TypeScript.

Agora, crie os seguintes arquivos:

• elasticsearchSetup.ts: Criará os mapeamentos de índice, carregará o conjunto de dados de um arquivo JSON e fará a ingestão dos dados no Elasticsearch.

• main.ts: incluirá o aplicativo LangGraph.

• .env: arquivo para armazenar as variáveis de ambiente

No arquivo .env, vamos adicionar as seguintes variáveis de ambiente:

O APIKey da OpenAPI não será usado diretamente no código; em vez disso, será usado internamente pela biblioteca @langchain/openai.

Toda a lógica relacionada à criação de mapeamentos, modelos de busca e ingestão de conjuntos de dados pode ser encontrada no arquivo elasticsearchSetup.ts. Nos próximos passos, vamos focar no arquivo main.ts . Além disso, você pode verificar o conjunto de dados para entender melhor como os dados aparecem no dataset.json.

Aplicativo LangGraph

No arquivo main.ts, vamos importar algumas dependências necessárias para consolidar a aplicação LangGraph. Neste arquivo, você também deve incluir as funções de nós e a declaração de estado. A declaração do gráfico será feita em um método main nos próximos passos. O arquivo elasticsearchSetup.ts conterá ajudantes Elasticsearch que vamos usar dentro dos nós em etapas futuras.

Como mencionado anteriormente, o cliente LLM será usado para gerar os parâmetros de busca do Elasticsearch com base na pergunta do usuário.

O método acima gera a imagem do gráfico em formato PNG e usa a API Mermaid.INK nos bastidores. Isso é útil se você quiser ver como os nós do app interagem entre si com uma visualização estilizada.

Nós do LangGraph

Agora vamos analisar cada nó em detalhes:

nó decideSearchStrategy

O node decideSearchStrategy analisa a entrada do usuário e determina se realiza uma buscar focada em investimento ou no mercado. Ele utiliza um LLM com um esquema de saída estruturado (definido com Zod) para classificar o tipo de consulta. Antes de tomar a decisão, o sistema recupera os filtros disponíveis do índice por meio de uma agregação, garantindo que o modelo tenha um contexto atualizado sobre setores, locais e dados de financiamento.

Para extrair os valores possíveis dos filtros e enviá-los ao LLM, vamos usar uma consulta de agregação para recuperá-los diretamente do índice do Elasticsearch. Essa lógica é alocada em um método chamado getAvailableFilters:

Com a consulta de agregação acima, temos os seguintes resultados:

Veja todos os resultados aqui.

Para ambas as estratégias, usaremos busca híbrida para detectar tanto a parte estruturada da pergunta (filtros) quanto as partes mais subjetivas (semântica). Aqui está um exemplo de ambas as consultas usando templates de busca:

Veja as consultas detalhadas no arquivo elasticsearchSetup.ts . No nó a seguir, será decidido qual das duas consultas será usada:

nós prepareInvestmentSearch e prepareMarketSearch

Ambos os nós usam uma função auxiliar compartilhada, extractFilterValues, que utiliza o LLM para identificar filtros relevantes mencionados na entrada do usuário, como setor, localização, estágio de financiamento, modelo de negócios, etc. Estamos usando este esquema para construir nosso modelo de busca.

Dependendo da intenção detectada, o fluxo de trabalho seleciona um de dois caminhos:

prepareInvestmentSearch: desenvolve parâmetros de busca orientados financeiramente, incluindo estágio de financiamento, valor do investimento, investidor e informações de renovação. Você pode encontrar o modelo completo de consulta no arquivo elasticsearchSetup.ts:

prepareMarketSearch: cria parâmetros orientados pelo mercado, focados em setores, geografias e modelos de negócios. Veja a consulta completa no arquivo elasticsearchSetup.ts :

nó executeSearch

Este nó pega os parâmetros de busca gerados do estado e os envia primeiro para o Elasticsearch, usando a API _render para visualizar a consulta para fins de depuração, e então envia uma solicitação para buscar os resultados.

nó visualizeResults

Por fim, este nó exibe os resultados do Elasticsearch.

Programaticamente, o gráfico completo tem a seguinte aparência:

Como você pode ver, temos uma aresta condicional onde o app decide qual "caminho" ou nó será executado em seguida. Esse recurso é útil quando fluxos de trabalho precisam de lógica de ramificação, como escolher entre várias ferramentas ou incluir uma etapa com uma pessoa no ciclo.

Com os recursos do núcleo do LangGraph entendidos, podemos configurar o aplicativo onde o código será executado:

Junte tudo em um método main; aqui declaramos o gráfico com todos os elementos sob a variável fluxo de trabalho:

A variável de consulta simula a entrada do usuário inserida em uma barra de busca hipotética:

A partir da frase em linguagem natural "Encontre startups com financiamento Série A ou Série B entre US$ 8M–US$ 25M e receita mensal acima de US$ 500K", todos os filtros serão extraídos.

Finalmente, invoque o método principal:

Resultados

Para a entrada enviada, a aplicação escolhe o caminho focado no investimento e, como resultado, podemos ver a consulta Elasticsearch gerada pelo fluxo de trabalho LangGraph, que extrai os valores e intervalos a partir da entrada do usuário. Também podemos ver a consulta enviada para o Elasticsearch com os valores extraídos aplicados e, finalmente, os resultados formatados pelo node visualizeResults com os resultados.

Agora vamos testar o nó focado no mercado usando a consulta "Encontre startups de fintech e saúde em São Francisco, Nova York ou Boston":

Aprendizados

Durante o processo de escrita, aprendi:

• Devemos mostrar ao LLM os valores exatos dos filtros; caso contrário, dependemos de o usuário digitar os valores exatos das coisas. Para baixa cardinalidade, essa abordagem é válida; mas, quando a cardinalidade é alta, precisamos de algum mecanismo para filtrar os resultados.

• Usar templates para busca torna os resultados muito mais consistentes do que deixar o LLM escrever a consulta Elasticsearch, e também é mais rápido

• Arestas condicionais são um mecanismo poderoso para construir aplicações com múltiplas variantes e caminhos ramificados.

• A saída estruturada é extremamente útil ao gerar informações com LLMs porque impõe respostas previsíveis e seguras para tipos. Isso melhora a confiabilidade e reduz as interpretações errôneas imediatas.

Combinar busca semântica e estruturada por meio da recuperação híbrida produz resultados melhores e mais relevantes, equilibrando precisão e compreensão do contexto.

Conclusão

Neste exemplo, combinamos LangGraph.js com o Elasticsearch para criar um fluxo de trabalho dinâmico capaz de interpretar consultas em linguagem natural e decidir entre estratégias de busca voltadas para finanças ou para o mercado. Essa abordagem reduz a complexidade de elaborar consultas manuais, ao mesmo tempo em que melhora a flexibilidade e a precisão para analistas de capital de risco.

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:

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

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.

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:

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:

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:

3. Habilitar o acesso ao notebook para cada segredo

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:

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.

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

3. Clique em Criar.

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.

5. Pressione Criar para salvar o MCP personalizado.

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.

Prompt 1: Buscar por problemas

Pergunte: "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:

Resposta da ferramenta:

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

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 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:

Resposta da ferramenta:

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

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.

Introdução ao RAG agentivo

A Geração Aumentada por Recuperação (RAG, na sigla em inglês) tornou-se um pilar fundamental em aplicações baseadas em Modelos de Aprendizagem Baseados em Aprendizagem (LLM, na sigla em inglês), permitindo que os modelos forneçam respostas otimizadas ao recuperar o contexto relevante com base nas consultas do usuário. Os sistemas RAG aprimoram a precisão e o contexto das respostas do LLM (Modelo de Aprendizagem Baseado em Aprendizagem) ao utilizar informações externas provenientes de APIs ou bancos de dados, em vez de se limitarem ao conhecimento pré-treinado do LLM. Por outro lado, os agentes de IA operam de forma autônoma, tomando decisões e executando ações para atingir seus objetivos designados.

O RAG Agentic é uma estrutura que unifica os pontos fortes da geração aumentada por recuperação e do raciocínio agentivo. Ele integra o RAG ao processo de tomada de decisão do agente, permitindo que o sistema escolha dinamicamente fontes de dados, refine consultas para melhor recuperação de contexto, gere respostas mais precisas e aplique um ciclo de feedback para melhorar continuamente a qualidade da saída.

Principais características do RAG agentivo

A estrutura RAG agentiva representa um grande avanço em relação aos sistemas RAG tradicionais. Em vez de seguir um processo de recuperação fixo, utiliza agentes dinâmicos capazes de planejar, executar e otimizar resultados em tempo real.

Vamos analisar algumas das principais características que distinguem os pipelines RAG agentivos:

• Tomada de decisão dinâmica: o Agentic RAG utiliza um mecanismo de raciocínio para compreender a intenção do usuário e direcionar cada consulta para a fonte de dados mais relevante, produzindo respostas precisas e contextualizadas.

• Análise abrangente de consultas: o Agentic RAG analisa profundamente as consultas dos usuários, incluindo subperguntas e sua intenção geral. Ele avalia a complexidade da consulta e seleciona dinamicamente as fontes de dados mais relevantes para recuperar informações, garantindo respostas precisas e completas.

• Colaboração em múltiplas etapas: Esta estrutura permite a colaboração em múltiplas etapas através de uma rede de agentes especializados. Cada agente lida com uma parte específica de um objetivo maior, trabalhando sequencialmente ou simultaneamente para alcançar um resultado coeso.

• Mecanismos de autoavaliação: O pipeline RAG agentivo utiliza a autorreflexão para avaliar os documentos recuperados e as respostas geradas. Ele pode verificar se as informações recuperadas respondem completamente à consulta e, em seguida, revisar a saída quanto à precisão, integridade e consistência factual.

• Integração com ferramentas externas: Este fluxo de trabalho pode interagir com APIs externas, bancos de dados e fontes de informação em tempo real, incorporando informações atualizadas e adaptando-se dinamicamente à evolução dos dados.

Padrões de fluxo de trabalho do RAG agente

Os padrões de fluxo de trabalho definem como a IA agente estrutura, gerencia e orquestra aplicações baseadas em LLM de maneira confiável e eficiente. Diversas estruturas e plataformas, como LangChain, LangGraph, CrewAI e LlamaIndex, podem ser usadas para implementar esses fluxos de trabalho com agentes.

1. Cadeia de recuperação sequencial: Os fluxos de trabalho sequenciais dividem tarefas complexas em etapas simples e ordenadas. Cada etapa melhora a entrada para a próxima, levando a melhores resultados. Por exemplo, ao criar um perfil de cliente, um agente pode extrair detalhes básicos de um CRM, outro recupera o histórico de compras de um banco de dados de transações e um agente final combina essas informações para gerar um perfil completo para recomendações ou relatórios.

2. Cadeia de roteamento e recuperação: Neste padrão de fluxo de trabalho, um agente de roteamento analisa a entrada e a direciona para o processo ou fonte de dados mais apropriada. Essa abordagem é particularmente eficaz quando existem múltiplas fontes de dados distintas com sobreposição mínima. Por exemplo, em um sistema de atendimento ao cliente, o agente de roteamento categoriza as solicitações recebidas, como problemas técnicos, reembolsos ou reclamações, e as encaminha para o departamento apropriado para um tratamento eficiente.

3. Cadeia de recuperação paralela: Neste padrão de fluxo de trabalho, várias subtarefas independentes são executadas simultaneamente e suas saídas são posteriormente agregadas para gerar uma resposta final. Essa abordagem reduz significativamente o tempo de processamento e aumenta a eficiência do fluxo de trabalho. Por exemplo, em um fluxo de trabalho paralelo de atendimento ao cliente, um agente recupera solicitações anteriores semelhantes, enquanto outro consulta artigos relevantes da base de conhecimento. Um agregador combina então esses resultados para gerar uma resolução abrangente.

4. Cadeia de trabalho do Orchestrator: Este fluxo de trabalho compartilha semelhanças com a paralelização devido à sua utilização de subtarefas independentes. No entanto, uma distinção fundamental reside na integração de um agente orquestrador. Este agente é responsável por analisar as consultas do usuário, segmentá-las dinamicamente em subtarefas durante a execução e identificar os processos ou ferramentas apropriados necessários para formular uma resposta precisa.

Construindo um pipeline RAG agético do zero.

Para ilustrar os princípios do RAG agentivo, vamos projetar um fluxo de trabalho usando LangChain e Elasticsearch. Este fluxo de trabalho adota uma arquitetura baseada em roteamento, onde múltiplos agentes colaboram para analisar consultas, recuperar informações relevantes, avaliar resultados e gerar respostas coerentes. Você pode consultar este notebook Jupyter para acompanhar este exemplo.

O fluxo de trabalho começa com o agente de roteamento, que analisa a consulta do usuário para selecionar o método de recuperação ideal, ou seja, uma abordagem vectorstore, websearch ou composite . O vectorstore lida com a recuperação tradicional de documentos baseada em RAG, a pesquisa na web busca as informações mais recentes que não estão armazenadas no vectorstore, e a abordagem composta combina ambas quando são necessárias informações de múltiplas fontes.

Se os documentos forem considerados adequados, o agente de sumarização gera uma resposta clara e contextualizada. No entanto, se os documentos forem insuficientes ou irrelevantes, o agente de reescrita de consultas reformula a consulta para melhorar a pesquisa. Essa consulta revisada reinicia o processo de roteamento, permitindo que o sistema refine sua busca e aprimore o resultado final.

Pré-requisitos

Este fluxo de trabalho depende dos seguintes componentes principais para executar o exemplo de forma eficaz:

• Python 3.10

• Notebook Jupyter

• Azure OpenAI

• Elasticsearch

• LangChain

Antes de prosseguir, você será solicitado a configurar o seguinte conjunto de variáveis de ambiente obrigatórias para este exemplo.

Fontes de dados

Este fluxo de trabalho é ilustrado usando um subconjunto do conjunto de dados da AG News. O conjunto de dados inclui artigos de notícias de diversas categorias, como Internacional, Esportes, Negócios e Ciência/Tecnologia.

O módulo ElasticsearchStore é utilizado a partir do langchain_elasticsearch como nosso armazenamento de vetores. Para a recuperação de dados, implementamos a SparseVectorStrategy, utilizando o ELSER, o modelo de incorporação proprietário da Elastic. É essencial confirmar se o modelo ELSER está instalado e implantado corretamente em seu ambiente Elasticsearch antes de iniciar o armazenamento de vetores.

A funcionalidade de busca na web é implementada usando o DuckDuckGoSearchRun das ferramentas da comunidade LangChain, o que permite que o sistema recupere informações em tempo real da web de forma eficiente. Você também pode considerar o uso de outras APIs de busca que podem fornecer resultados mais relevantes. Essa ferramenta foi escolhida por permitir buscas sem a necessidade de uma chave de API.

O recuperador composto foi projetado para consultas que exigem uma combinação de fontes. É utilizado para fornecer uma resposta abrangente e contextualizada, recuperando simultaneamente dados em tempo real da web e consultando notícias históricas do banco de dados vetorial.

Configurar os agentes

Na etapa seguinte, os agentes LLM são definidos para fornecer capacidades de raciocínio e tomada de decisão dentro desse fluxo de trabalho. As cadeias LLM que criaremos incluem: router_chain, grade_docs_chain, rewrite_query_chain e summary_chain.

O agente de roteamento utiliza um assistente LLM para determinar a fonte de dados mais apropriada para uma determinada consulta em tempo de execução. O agente de classificação avalia os documentos recuperados quanto à sua relevância. Se os documentos forem considerados relevantes, eles são encaminhados ao agente de resumo para gerar um resumo. Caso contrário, o agente de reescrita de consultas reformula a consulta e a envia de volta ao processo de roteamento para uma nova tentativa de recuperação. Você pode encontrar as instruções para todos os agentes na seção Cadeias LLM do caderno.

O llm.with_structured_output restringe a saída do modelo a seguir um esquema predefinido definido pelo BaseModel sob a classe RouteQuery , garantindo a consistência dos resultados. A segunda linha compõe um RunnableSequence conectando router_prompt com router_structured, formando um pipeline no qual o prompt de entrada é processado pelo modelo de linguagem para produzir resultados estruturados e compatíveis com o esquema.

Defina os nós do grafo.

Esta parte envolve a definição dos estados do grafo, que representam os dados que fluem entre os diferentes componentes do sistema. Uma especificação clara desses estados garante que cada nó no fluxo de trabalho saiba quais informações ele pode acessar e atualizar.

Uma vez definidos os estados, o próximo passo é definir os nós do grafo. Os nós são como as unidades funcionais do grafo que executam operações específicas sobre os dados. Nosso pipeline possui 7 nós diferentes.

O nó query_rewriter serve a dois propósitos no fluxo de trabalho. Primeiro, ele reescreve a consulta do usuário usando o rewrite_query_chain para melhorar a recuperação quando os documentos avaliados pelo agente de autorreflexão são considerados insuficientes ou irrelevantes. Em segundo lugar, funciona como um contador que registra quantas vezes a consulta foi reescrita.

Cada vez que o nó é invocado, ele incrementa o retry_count armazenado no estado do fluxo de trabalho. Esse mecanismo impede que o fluxo de trabalho entre em um loop infinito. Se o retry_count exceder um limite predefinido, o sistema pode recorrer a um estado de erro, uma resposta padrão ou qualquer outra condição predefinida que você escolher.

Compilando o gráfico

O último passo é definir as arestas do grafo e adicionar quaisquer condições necessárias antes de compilá-lo. Cada grafo deve começar a partir de um nó inicial designado, que serve como ponto de entrada para o fluxo de trabalho. As arestas no grafo representam o fluxo de dados entre os nós e podem ser de dois tipos:

• Arestas retas: Estas definem um fluxo direto e incondicional de um nó para outro. Sempre que o primeiro nó conclui sua tarefa, o fluxo de trabalho avança automaticamente para o próximo nó ao longo da aresta reta.

• Arestas condicionais: Permitem que o fluxo de trabalho se ramifique com base no estado atual ou nos resultados da computação de um nó. O próximo nó é selecionado dinamicamente, dependendo de condições como resultados de avaliação, decisões de roteamento ou número de tentativas.

Com isso, seu primeiro pipeline RAG agentivo está pronto e pode ser testado usando o agente compilado.

Testando o pipeline RAG agentivo

Agora vamos testar esse pipeline usando três tipos distintos de consultas, conforme descrito abaixo. Note que os resultados podem variar, e os exemplos mostrados abaixo ilustram apenas um resultado possível.

Para a primeira consulta, o roteador seleciona websearch como fonte de dados. A consulta falha na avaliação de autorreflexão e, consequentemente, é redirecionada para a etapa de reescrita da consulta, conforme mostrado na saída.

Em seguida, examinamos um exemplo onde a recuperação vectorstore é usada, demonstrado com a segunda consulta.

A consulta final é direcionada à recuperação composta, que utiliza tanto o armazenamento vetorial quanto a pesquisa na web.

No fluxo de trabalho acima, o RAG agente determina de forma inteligente qual fonte de dados usar ao recuperar informações para uma consulta do usuário, melhorando assim a precisão e a relevância da resposta. Você pode criar exemplos adicionais para testar o agente e analisar os resultados para verificar se eles produzem algum resultado interessante.

Melhores práticas para a construção de fluxos de trabalho RAG com agentes

Agora que entendemos como o RAG agético funciona, vamos analisar algumas práticas recomendadas para a construção desses fluxos de trabalho. Seguir estas diretrizes ajudará a manter o sistema eficiente e de fácil manutenção.

• Prepare-se para planos de contingência: Planeje estratégias alternativas com antecedência para cenários em que qualquer etapa do fluxo de trabalho falhe. Isso pode incluir retornar respostas padrão, acionar estados de erro ou usar ferramentas alternativas. Isso garante que o sistema lide com as falhas de forma adequada, sem interromper o fluxo de trabalho geral.

• Implemente um registro abrangente: tente implementar o registro em cada etapa do fluxo de trabalho, como novas tentativas, saídas geradas, opções de roteamento e reescritas de consultas. Esses registros ajudam a melhorar a transparência, facilitam a depuração e auxiliam no aprimoramento de prompts, comportamento do agente e estratégias de recuperação ao longo do tempo.

• Selecione o padrão de fluxo de trabalho apropriado: Analise seu caso de uso e selecione o padrão de fluxo de trabalho que melhor atenda às suas necessidades. Utilize fluxos de trabalho sequenciais para raciocínio passo a passo, fluxos de trabalho paralelos para fontes de dados independentes e padrões de orquestrador-trabalhador para consultas complexas ou que envolvam múltiplas ferramentas.

• Incorporar estratégias de avaliação: Integrar mecanismos de avaliação em diferentes etapas do fluxo de trabalho. Isso pode incluir agentes de autorreflexão, classificação de documentos recuperados ou verificações de qualidade automatizadas. A avaliação ajuda a verificar se os documentos recuperados são relevantes, se as respostas são precisas e se todas as partes de uma consulta complexa foram abordadas.

Desafios

Embora os sistemas RAG agentivos ofereçam vantagens significativas em termos de adaptabilidade, precisão e raciocínio dinâmico, eles também apresentam certos desafios que devem ser abordados durante as fases de projeto e implementação. Alguns dos principais desafios incluem:

• Fluxos de trabalho complexos: À medida que mais agentes e pontos de decisão são adicionados, o fluxo de trabalho geral torna-se cada vez mais complexo. Isso pode levar a uma maior probabilidade de erros ou falhas em tempo de execução. Sempre que possível, priorize fluxos de trabalho simplificados, eliminando agentes redundantes e pontos de decisão desnecessários.

• Escalabilidade: Pode ser desafiador dimensionar sistemas RAG com agentes para lidar com grandes conjuntos de dados e altos volumes de consultas. Incorpore estratégias eficientes de indexação, armazenamento em cache e processamento distribuído para manter o desempenho em grande escala.

• Orquestração e sobrecarga computacional: A execução de fluxos de trabalho com múltiplos agentes requer orquestração avançada. Isso inclui um planejamento cuidadoso, gerenciamento de dependências e coordenação de agentes para evitar gargalos e conflitos, fatores que contribuem para a complexidade geral do sistema.

• Complexidade da avaliação: A avaliação desses fluxos de trabalho apresenta desafios inerentes, uma vez que cada etapa requer uma estratégia de avaliação distinta. Por exemplo, a etapa RAG deve ser avaliada quanto à relevância e completude dos documentos recuperados, enquanto os resumos gerados precisam ser verificados quanto à qualidade e precisão. Da mesma forma, a eficácia da reformulação de consultas requer uma lógica de avaliação separada para determinar se a consulta reescrita melhora os resultados da recuperação.

Conclusão

Neste post do blog, apresentamos o conceito de RAG agente e destacamos como ele aprimora a estrutura tradicional de RAG, incorporando capacidades autônomas da IA agente. Exploramos as principais funcionalidades do RAG agentivo e demonstramos essas funcionalidades por meio de um exemplo prático, construindo um assistente de notícias usando o Elasticsearch como repositório de vetores e o LangChain para criar a estrutura agentiva.

Além disso, discutimos as melhores práticas e os principais desafios a serem considerados ao projetar e implementar um pipeline RAG com agentes. Essas informações têm como objetivo orientar os desenvolvedores na criação de sistemas de agentes robustos, escaláveis e eficientes que combinem efetivamente recuperação de dados, raciocínio e tomada de decisões.

O que vem a seguir

O fluxo de trabalho que desenvolvemos é simples, deixando bastante espaço para melhorias e experimentação. Podemos melhorar isso experimentando com vários modelos de incorporação e refinando as estratégias de recuperação. Além disso, a integração de um agente de reclassificação para priorizar os documentos recuperados pode ser benéfica. Outra área a ser explorada envolve o desenvolvimento de estratégias de avaliação para estruturas de agentes, especificamente a identificação de abordagens comuns e reutilizáveis aplicáveis a diferentes tipos de estruturas. Por fim, experimentar essas estruturas em conjuntos de dados grandes e mais complexos.

Entretanto, se você tiver experiências semelhantes para compartilhar, adoraríamos saber mais sobre elas! Fique à vontade para enviar seus comentários ou entrar em contato conosco por meio do nosso canal da comunidade no Slack ou dos fóruns de discussão.

Recursos

• Auto-RAG: Aprendendo a Recuperar, Gerar e Criticar por meio da Autorreflexão

• Geração Aumentada por Recuperação Agencial: Uma Análise sobre RAG Agencial

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:

• Elastic Cloud hospedado na versão 9.2, implantação local ou sem servidor.

• Recomenda-se máquina com 32 GB de RAM (mínimo de 16 GB para GPT-OSS 20B).

• LM Studio instalado

• Docker Desktop instalado

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.

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:

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:

Acesse o Kibana

Abra seu navegador e acesse:

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.

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

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.

Indexar com API em lote

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

Verifique os dados

Execute uma consulta para verificar:

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:

Rótulos: Human Resources e GPT-OSS

Nome de exibição: HR Analytics Assistant

Descrição da tela:

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:

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.

Além dos projetos impressionantes, a experiência no Cal Hacks 12.0 também nos proporcionou algo igualmente valioso: feedback rápido e direto de desenvolvedores que estavam tendo contato com nossa Stack pela primeira vez. Hackathons são testes de pressão únicos, com prazos apertados, zero familiaridade prévia e obstáculos imprevisíveis (como as infames quedas de Wi-Fi). Eles revelam exatamente onde a experiência do desenvolvedor se destaca e onde ainda precisa ser aprimorada. Isso é ainda mais importante agora, à medida que os desenvolvedores interagem com o Elastic Stack de novas maneiras, cada vez mais por meio de fluxos de trabalho orientados por LLM. Neste post do blog, vamos explorar mais a fundo o que os participantes criaram com o Agent Builder e o que aprendemos durante o processo.

Os projetos vencedores

Primeiro lugar: AgentOverflow

Stack Overflow reconstruído para a era do LLM e dos agentes.

Leia mais sobre AgentOverflow aqui.

O AgentOverflow resolve um problema que a maioria dos desenvolvedores de IA enfrenta: os LLMs (Learning Learning Machines) têm alucinações, o histórico de bate-papo desaparece e os desenvolvedores perdem tempo resolvendo os mesmos problemas repetidamente.

O AgentOverflow captura, valida e reapresenta pares reais de problema-solução, para que os desenvolvedores possam quebrar o ciclo de ilusão e lançar produtos mais rapidamente.

Como funciona:

1. Compartilhar JSON - o "Esquema da Solução".

Um clique em um compartilhamento do Claude irá coletar, extrair e montar um JSON de Solução de Compartilhamento, que é um formato estruturado contendo:

• Problema

• Contexto

• Código

• Tags

• Etapas da solução verificadas.

Um validador (LAVA) verifica e impõe a estrutura; o usuário adiciona uma linha de contexto extra, que então é armazenada e indexada no Elasticsearch.

2. Encontre a solução

Quando você ficar preso, clique em Find Solution e o AgentOverflow irá extrair informações da sua conversa atual, usá-las para construir uma consulta e executar uma pesquisa híbrida no Elasticsearch para exibir os resultados:

• Correções classificadas e validadas pela comunidade

• As mesmas instruções que originalmente resolveram o problema.

Isso permite que os desenvolvedores copiem, colem e desbloqueiem sua sessão atual rapidamente.

3. MCP - Injeção de contexto para LLMs

Ao conectar-se às soluções estruturadas armazenadas no Elasticsearch por meio do MCP (Model Context Protocol), os LLMs recebem um contexto de alta qualidade (código, logs, configurações, correções anteriores) em tempo de execução, sem ruído adicional.

O AgentOverflow utiliza o Agent Builder com o Elasticsearch como uma camada de memória estruturada que injeta contexto relevante nos LLMs. Isso os transforma de chatbots passivos em solucionadores de problemas sensíveis ao contexto.

Segundo lugar: MarketMind

Uma visão interpretável e em tempo real da energia de mercado, alimentada por seis Agentes Elásticos.

Leia mais sobre a MarketMind aqui.

A MarketMind conquistou seu espaço ao oferecer aos traders iniciantes uma plataforma que converte dados de mercado fragmentados em sinais claros e em tempo real. Em vez de lidar com a ação do preço, os fundamentos, o sentimento e a volatilidade em diferentes ferramentas, o MarketMind consolida todas essas informações em uma única plataforma, ajudando os traders a obter insights acionáveis. Este projeto também utilizou algumas consultas ES|QL complexas na construção de seus agentes.

Como funciona:

1. Coletar dados de mercado em tempo real

O MarketMind extrai métricas de ação de preço, fundamentos, sentimento, volatilidade e risco do Yahoo Finance. Esses dados são ingeridos e organizados em múltiplos índices do Elasticsearch.

2. Seis agentes especializados analisam o mercado.

Cada agente, criado com o Agent Builder, concentra-se em uma camada diferente do mercado. Eles leem dados de um índice do Elasticsearch, calculam suas próprias métricas específicas do domínio e geram uma saída JSON padronizada com pontuações e justificativas.

3. Agregar sinais em um modelo unificado de “energia de mercado”

Os resultados combinados aparecem como pulsos brilhantes ao redor de cada ação, ilustrando se o ímpeto está aumentando, o risco está crescendo ou o sentimento está mudando.

4. Visualize insights

A interface foi desenvolvida com React e Next.js, utilizando TypeScript, recursos visuais baseados em física SVG e Chart.js para gráficos de velas em tempo real. Isso transforma análises brutas em feedback acionável em tempo real.

Outros projetos interessantes:

Aqui estão alguns outros fortes concorrentes que usaram o Elastic em diferentes partes de sua infraestrutura:

Encontre aqui a lista completa dos projetos submetidos à nossa trilha.

O que aprendemos com os desenvolvedores

• O Construtor de Agentes é fácil de usar:

A maioria das equipes nunca havia usado o Elastic antes e, mesmo assim, conseguiu criar agentes rapidamente com pouco suporte. Realizamos um workshop para aqueles que precisavam de mais orientação, mas a maioria conseguiu importar seus dados e construir um agente para executar ações com base nesses dados.

• Os LLMs se destacam em consultaskNN, mas ainda precisam de orientação na geração de ES|QL:

Ao solicitar que o ChatGPT-5 gerasse consultas ES|QL, foram retornadas informações incorretas, frequentemente misturando ES|QL e SQL. Fornecer os documentos ao LLM em um arquivo Markdown pareceu ser uma solução viável.

• Funções ES|QL exclusivas de snapshots vazaram para a documentação:

As próximas funções de agregação FIRST e LAST foram acidentalmente incluídas em nossa documentação ES|QL. Como fornecemos esses documentos ao ChatGPT, o modelo usou essas funções corretamente, mesmo que elas ainda não estejam disponíveis no Serverless. Graças ao feedback do grupo, a equipe de engenharia rapidamente abriu e incorporou uma correção para remover as funções da documentação publicada (PR #137341).

• Ausência de orientações específicas para Serverless:

Uma equipe tentou habilitar LOOKUP JOIN em um índice que não foi criado no modo de pesquisa. A mensagem de erro os levou a seguir comandos que não existem no Serverless. Repassamos isso para a equipe de produto, que imediatamente abriu uma solicitação de correção para uma mensagem acionável específica para Serverless. A longo prazo, a visão é ocultar completamente a complexidade da reindexação (Problema nº 4838).

• Valor dos eventos presenciais:

Hackathons online são ótimos, mas nada se compara ao feedback rápido que você obtém ao depurar código lado a lado com os desenvolvedores. Acompanhamos as equipes integrando o Agent Builder em diferentes casos de uso, identificamos pontos em que a experiência do desenvolvedor com ES|QL poderia ser aprimorada e corrigimos problemas muito mais rapidamente do que se tivéssemos tentado fazê-lo por meio de canais assíncronos.

Conclusão

O Cal Hacks 12.0 nos proporcionou mais do que um fim de semana repleto de demonstrações incríveis; também nos deu uma visão de como os novos desenvolvedores estão interagindo com o Elastic Stack. Em apenas 36 horas, vimos equipes começarem a usar o Agent Builder, ingerir dados no Elasticsearch, projetar sistemas multiagentes e testar nossos recursos de diversas maneiras. O evento também nos lembrou por que os eventos presenciais são importantes. Os ciclos de feedback rápidos, as conversas reais e a depuração prática nos ajudaram a entender as necessidades atuais dos desenvolvedores. Estamos entusiasmados em trazer de volta para a equipe de engenharia o que aprendemos. Nos vemos no próximo hackathon.

Este artigo é um complemento ao artigo "Criando uma sala de imprensa com o agente LLM usando os protocolos A2A e MCP no Elasticsearch!", que explicou os benefícios de implementar as arquiteturas A2A e MCP no mesmo agente para aproveitar ao máximo as vantagens exclusivas de ambas as estruturas. Um repositório está disponível caso você queira executar a demonstração por conta própria.

Vamos analisar como nossos agentes de redação colaboram usando tanto o A2A quanto o MCP para produzir um artigo jornalístico. O repositório que acompanha o projeto, onde é possível ver os agentes em ação, pode ser encontrado aqui.

Etapa 1: Atribuição da história

O chefe de jornalismo (atuando como cliente) designa uma pauta:

Etapa 2: O repórter solicita pesquisa.

O Agente Repórter reconhece que precisa de informações básicas e delega essa tarefa ao Agente Pesquisador por meio do método A2A:

Etapa 3: O repórter solicita contexto histórico ao Agente de Arquivo.

O agente repórter reconhece que o contexto histórico fortaleceria a matéria. Ele delega ao Agente de Arquivo (com tecnologia A2A do Elastic) via A2A a busca no arquivo de artigos da sala de notícias, que utiliza o Elasticsearch:

Etapa 4: O Agente de Arquivamento usa o Agente A2A Elástico com MCP

O Agente de Arquivamento utiliza o Agente A2A da Elastic, que por sua vez usa o MCP para acessar as ferramentas do Elasticsearch. Isso demonstra a arquitetura híbrida onde o A2A permite a colaboração entre agentes enquanto o MCP fornece acesso às ferramentas:

O Agente de Arquivamento recebe dados históricos abrangentes do Agente A2A da Elastic e os retorna ao Reporter:

Esta etapa demonstra como o agente A2A da Elastic se integra ao fluxo de trabalho da redação. O Agente de Arquivo (um agente específico para redações) trabalha em conjunto com o Agente A2A da Elastic (um especialista terceirizado) para aproveitar os poderosos recursos de busca e análise do Elasticsearch. O agente da Elastic usa o MCP internamente para acessar as ferramentas do Elasticsearch, demonstrando a clara separação entre a coordenação do agente (A2A) e o acesso às ferramentas (MCP).

Etapa 5: O pesquisador utiliza servidores MCP

O Agente Pesquisador acessa vários servidores MCP para coletar informações:

Etapa 6: O pesquisador devolve os dados ao repórter.

O Agente de Pesquisa envia uma pesquisa completa de volta via A2A:

Etapa 7: O repórter escreve o artigo

O Repórter Agente utiliza os dados da pesquisa e suas próprias capacidades de mestrado em Direito (LLM) para redigir o artigo. Durante a escrita, o Repórter utiliza os servidores MCP para estilo e modelos:

Etapa 8: baixa confiança desencadeia nova pesquisa

O agente repórter avalia sua versão preliminar e constata que uma das afirmações apresenta baixo nível de confiança. Envia outra solicitação ao Agente Pesquisador:

O pesquisador verifica a alegação usando servidores de checagem de fatos do MCP e retorna informações atualizadas:

Etapa 9: O repórter revisa e envia ao editor.

O repórter incorpora os fatos verificados e envia a versão finalizada ao editor por meio do sistema A2A:

Etapa 10: Revisão do editor usando as ferramentas MCP

O Agente de Edição utiliza vários servidores MCP para revisar o artigo:

O editor aprova o artigo e o encaminha:

Etapa 11: A editora publica via CI/CD

Por fim, o Agente de Impressão publica o artigo aprovado usando os servidores MCP para o pipeline CMS e CI/CD:

A editora confirma a publicação via A2A:

Segue abaixo a sequência completa do fluxo de trabalho A2A no repositório anexo, utilizando os mesmos agentes descritos acima.

#

De

Para

Ação

Protocolo

Descrição

1

Usuário

Chefe de Notícias

Atribuir história

HTTP POST

O usuário envia o tema e o enfoque da matéria.

2

Chefe de Notícias

Interno

Criar história

-

Cria um registro de história com um ID exclusivo.

3

Chefe de Notícias

Repórter

Atribuição de Delegado

A2A

Envia a atribuição da matéria através do protocolo A2A

4

Repórter

Interno

Aceitar tarefa

-

Atribuição de estoques internamente

5

Repórter

Servidor MCP

Gerar esboço

MCP/HTTP

Cria o esboço do artigo e as perguntas de pesquisa.

6a

Repórter

Pesquisador

Solicitar pesquisa

A2A

Envia perguntas (paralelo com 6b)

6b

Repórter

Arquivista

Pesquisar no arquivo

A2A JSONRPC

Pesquisa artigos históricos (paralelo com 6a)

7

Pesquisador

Servidor MCP

Questões de pesquisa

MCP/HTTP

Utiliza a abordagem antropogênica via MCP para responder a perguntas.

8

Pesquisador

Repórter

Retornar à pesquisa

A2A

Devolve respostas de pesquisa

9

Arquivista

Elasticsearch

Índice de pesquisa

API REST do ES

Consultas ao índice news_archive

10

Arquivista

Repórter

Retornar ao arquivo

A2A JSONRPC

Retorna resultados de pesquisa históricos

11

Repórter

Servidor MCP

Gerar artigo

MCP/HTTP

Cria artigo com contexto de pesquisa/arquivo

12

Repórter

Interno

Rascunho da loja

-

Salva o rascunho internamente

13

Repórter

Chefe de Notícias

Enviar rascunho

A2A

Entrega a versão finalizada

14

Chefe de Notícias

Interno

Atualização da história

-

Armazena o rascunho e atualiza o status para "rascunho_enviado".

15

Chefe de Notícias

Editor

Revisão do rascunho

A2A

Encaminha automaticamente para o Editor para revisão.

16

Editor

Servidor MCP

Artigo de revisão

MCP/HTTP

Analisa conteúdo usando Anthropic via MCP.

17

Editor

Chefe de Notícias

Revisão de retorno

A2A

Envia comentários e sugestões editoriais.

18

Chefe de Notícias

Interno

Avaliação da loja

-

Feedback do editor de lojas

19

Chefe de Notícias

Repórter

Aplicar edições

A2A

Feedback da revisão de rotas para o repórter

20

Repórter

Servidor MCP

Aplicar edições

MCP/HTTP

Revisa o artigo com base no feedback.

21

Repórter

Interno

Rascunho atualizado

-

Atualiza a versão preliminar com revisões.

22

Repórter

Chefe de Notícias

Devolução revisada

A2A

Devolve artigo revisado

23

Chefe de Notícias

Interno

Atualização da história

-

Lojas revisaram a versão preliminar, status para "revisado"

24

Chefe de Notícias

Editor

Publicar artigo

A2A

Rotas automáticas para o editor

25

Editor

Servidor MCP

Gerar etiquetas

MCP/HTTP

Cria etiquetas e categorias

26

Editor

Elasticsearch

Artigo de índice

API REST do ES

Indexa o artigo ao índice news_archive

27

Editor

Sistema de arquivos

Salvar Markdown

Entrada/Saída de Arquivos

Salva o artigo como .md arquivo em /artigos

28

Editor

Chefe de Notícias

Confirmar publicação

A2A

Retorna o status de sucesso

29

Chefe de Notícias

Interno

Atualização da história

-

Atualiza o status da matéria para "publicada".

Conclusão

Tanto o A2A quanto o MCP desempenham papéis importantes no paradigma moderno de infraestrutura de LLM aumentada. A tecnologia A2A oferece flexibilidade para sistemas multiagentes complexos, mas potencialmente menor portabilidade e maior complexidade operacional. O MCP oferece uma abordagem padronizada para integração de ferramentas que é mais simples de implementar e manter, embora não seja projetado para lidar com orquestração multiagente.

A escolha não é binária. Conforme demonstrado em nosso exemplo de redação, os sistemas mais sofisticados e eficazes baseados em LLM geralmente combinam ambas as abordagens: os agentes se coordenam e se especializam por meio de protocolos A2A, enquanto acessam suas ferramentas e recursos por meio de servidores MCP. Essa arquitetura híbrida proporciona os benefícios organizacionais dos sistemas multiagentes, juntamente com a padronização e as vantagens do ecossistema do MCP. Isso sugere que talvez não seja necessário escolher: basta usar ambos como abordagem padrão.

Cabe a você, como desenvolvedor ou arquiteto, testar e determinar a melhor combinação de ambas as soluções para obter o resultado adequado ao seu caso de uso específico. Compreender os pontos fortes, as limitações e as aplicações adequadas de cada abordagem permitirá que você construa sistemas de IA mais eficazes, fáceis de manter e escaláveis.

Seja para criar uma redação digital, uma plataforma de atendimento ao cliente, um assistente de pesquisa ou qualquer outro aplicativo baseado em LLM, considerar cuidadosamente suas necessidades de coordenação (A2A) e requisitos de acesso às ferramentas (MCP) o colocará no caminho do sucesso.

Recursos adicionais

• Construtor de Agentes do Elasticsearch: https://www.elastic.co/docs/solutions/search/elastic-agent-builder

• Especificação A2A: https://a2a-protocol.org/latest/specification/

• Integração A2A e MCP: https://a2a-protocol.org/latest/topics/a2a-and-mcp/

• Protocolo de Contexto do Modelo: https://modelcontextprotocol.io

A busca não morreu, apenas mudou de lugar.

Assim, tivemos essa mudança de uma abordagem que consistia principalmente em buscar contexto por meio de uma caixa de texto e usar as informações (o contexto) retornadas para construir as respostas nós mesmos, para agora usar a linguagem natural para dizer a um agente o que queremos e deixar que ele pesquise e compile automaticamente a resposta para nós. Muitos no mundo da tecnologia estão apontando para essa mudança e proclamando que "a busca está morta" (bem, o mundo do SEO e do AdWords está definitivamente mudando: alguém aí se lembra do GEO ?), mas a busca ainda é absolutamente crucial para as operações de agentes — ela só é realizada, em grande parte, fora do campo de visão, por meio de ferramentas.

Anteriormente, os humanos eram os principais árbitros da relevância subjetiva: cada usuário tem seus próprios motivos para realizar a busca, e sua experiência pessoal influencia a precisão relativa dos resultados. Para confiarmos que os agentes podem chegar à mesma conclusão (ou melhor) que nós, precisamos garantir que as informações contextuais a que eles têm acesso sejam as mais próximas possíveis da nossa intenção subjetiva. Temos que estruturar o contexto que oferecemos aos mestrados em Direito (LLM) de forma a atingir esse objetivo!

Geração de contexto com recuperação de pesquisa híbrida

Só para relembrar, lá da Parte I, que a busca híbrida da Elastic combina os pontos fortes da busca tradicional baseada em palavras-chave (flexibilidade de sintaxe, precisão de palavras-chave e pontuação de relevância) com a compreensão semântica da busca por similaridade vetorial e oferece múltiplas técnicas de reclassificação. Essa sinergia (nunca se encontrou um uso mais preciso dessa palavra!) Permite resultados altamente relevantes, com consultas que podem ser muito mais específicas na forma como direcionam o conteúdo. Não se trata apenas de poder aplicar a relevância subjetiva como uma das etapas de recuperação; trata-se, na verdade, de que a recuperação na primeira etapa pode incluir a pontuação de relevância juntamente com todos os outros métodos simultaneamente.

Precisão e eficiência superiores

Utilizar uma plataforma de dados que possa fornecer busca, recuperação e reclassificação distribuídas como seu principal mecanismo de recuperação de contexto faz muito sentido. Você pode usar uma sintaxe de consulta avançada para adicionar o componente ausente da intenção subjetiva e filtrar o conteúdo que possa distrair ou obscurecer o valor das informações contextuais retornadas. Você pode selecionar qualquer uma das opções de sintaxe individuais disponíveis ou combinar modalidades em uma única pesquisa que visa cada tipo de dado da maneira que melhor o compreende e, em seguida, combiná-los/reordená-los com a reclassificação. Você pode filtrar a resposta para incluir apenas os campos/valores desejados, mantendo os dados irrelevantes afastados. Em termos de suporte aos agentes, essa flexibilidade de segmentação permite criar ferramentas extremamente precisas na forma como recuperam o contexto.

Refinamento de contexto (agregações e sinais não relacionados ao conteúdo)

As agregações podem ser especialmente úteis para moldar o conteúdo que uma ferramenta fornece à janela de contexto. As agregações fornecem naturalmente informações numéricas sobre o formato dos dados contextuais retornados, o que facilita e torna mais preciso o raciocínio dos Modelos de Aprendizagem Baseados em Leis (LLMs). Como as agregações podem ser hierarquicamente aninhadas, é uma maneira fácil de adicionar detalhes em vários níveis para o LLM, a fim de gerar uma compreensão mais matizada. As agregações também podem ajudar no gerenciamento do tamanho da janela de contexto — você pode facilmente reduzir o resultado de uma consulta de 100 mil documentos para algumas centenas de tokens de insights agregados.

Os sinais não relacionados ao conteúdo são os indicadores inerentes aos seus dados que fornecem uma visão mais ampla do que você está analisando; são as características adicionais dos resultados, como popularidade, atualidade, localização geográfica, categorias, diversidade de hospedagem ou faixas de preço. Essas informações podem ser úteis para orientar o agente na avaliação da importância do contexto recebido. Alguns exemplos simples podem ajudar a ilustrar isso melhor:

• Impulsionando conteúdo popular e publicado recentemente - Imagine que você tenha uma base de conhecimento com artigos. Você deseja encontrar artigos relevantes para a consulta de um usuário, mas também quer priorizar artigos que sejam recentes e que tenham sido considerados úteis por outros usuários (por exemplo, que tenham um grande número de "curtidas"). Nesse cenário, podemos usar uma busca híbrida para encontrar artigos relevantes e, em seguida, reclassificá-los com base em uma combinação de sua data de publicação e popularidade.

• Busca em e-commerce com ajuste de vendas e estoque - Em um ambiente de e-commerce, você deseja mostrar aos clientes produtos que correspondam ao termo de busca, mas também promover produtos que estejam vendendo bem e disponíveis em estoque. Você também pode querer diminuir a classificação de produtos com baixo estoque para evitar a frustração do cliente.

• Priorizando problemas de alta gravidade em um sistema de rastreamento de bugs - Para uma equipe de desenvolvimento de software, ao procurar problemas, é crucial que os problemas de alta gravidade, alta prioridade e atualizados recentemente sejam exibidos primeiro. Você pode usar indicadores não-sinais, como "criticidade" e "mais discutido", para ponderar diferentes fatores de forma independente, garantindo que as questões mais críticas e ativamente discutidas cheguem ao topo.

Essas consultas de exemplo e outras podem ser encontradas na página de conteúdo do Elasticsearch Labs que acompanha este artigo.

aplicação das leis de segurança

Uma vantagem crucial de utilizar uma camada de velocidade baseada em pesquisa, como o Elastic, para engenharia de contexto é sua estrutura de segurança integrada. A plataforma da Elastic garante que o contexto fornecido às operações de IA generativa e agente respeite e proteja informações confidenciais mantidas em sigilo por meio de controle de acesso baseado em funções (RBAC) e controle de acesso baseado em atributos (ABAC) granulares. Isso significa que não apenas as consultas são processadas com eficiência, mas também que os resultados são filtrados de acordo com as permissões específicas do agente ou do usuário que iniciou a solicitação.

Os agentes são executados como o usuário autenticado, portanto a segurança é aplicada implicitamente por meio dos recursos de segurança integrados à plataforma:

• Permissões refinadas: Defina o acesso no nível do documento, do campo ou até mesmo do termo, garantindo que os agentes de IA recebam apenas os dados que estão autorizados a visualizar.

• Controle de acesso baseado em funções (RBAC): Atribua funções a agentes ou usuários, concedendo acesso a conjuntos de dados ou funcionalidades específicas com base em suas responsabilidades definidas.

• Controle de acesso baseado em atributos (ABAC): Implemente políticas de acesso dinâmicas com base em atributos dos dados, do usuário ou do ambiente, permitindo uma segurança altamente adaptável e contextualizada.

• Segurança em nível de documento (DLS) e segurança em nível de campo (FLS): Esses recursos garantem que, mesmo dentro de um documento recuperado, apenas as partes autorizadas sejam visíveis, impedindo que informações confidenciais sejam expostas.

• Integração com segurança corporativa: Integre-se perfeitamente com sistemas de gerenciamento de identidade existentes (como LDAP, SAML, OIDC) para aplicar políticas de segurança consistentes em toda a organização.

Ao integrar essas medidas de segurança diretamente no mecanismo de recuperação de contexto, a Elastic atua como um guardião seguro, garantindo que os agentes de IA operem dentro de limites de dados definidos, evitando a exposição não autorizada de dados e mantendo a conformidade com as regulamentações de privacidade de dados. Isso é fundamental para construir confiança em sistemas de IA que lidam com informações confidenciais ou proprietárias.

Como benefício adicional, ao usar uma camada unificada de velocidade de dados sobre suas fontes de dados corporativas, você alivia as cargas inesperadas de consultas ad hoc nesses repositórios que as ferramentas de agentes criariam. Você obtém um local centralizado para pesquisar tudo em tempo quase real e um único lugar para aplicar controles de segurança e governança.

Ferramentas híbridas baseadas em pesquisa

Existem algumas funcionalidades essenciais (e outras estão sendo adicionadas constantemente) da plataforma Elastic que impulsionam a busca pela engenharia de contexto. O principal aqui é que a plataforma oferece uma infinidade de maneiras de atingir objetivos, com a flexibilidade para adaptar, alterar e expandir os métodos à medida que o ecossistema de IA avança.

Apresentando o Construtor de Agentes

O Elastic Agent Builder é nossa primeira incursão no mundo das ferramentas de IA com agentes, criadas para interagir com os dados que você já armazena no Elastic. O Agent Builder oferece uma interface de chat que permite aos usuários criar e gerenciar seus próprios agentes e ferramentas dentro do Kibana. Ele vem com servidores MCP e A2A integrados, APIs programáticas e um conjunto de ferramentas de sistema pré-construídas para consultar e explorar índices do Elasticsearch, além de gerar consultas ES|QL a partir de linguagem natural. O Agent Builder permite criar ferramentas personalizadas que visam e moldam os dados contextuais retornados ao agente por meio de uma sintaxe de consulta ES|QL expressiva.

Como o ES|QL realiza buscas híbridas, você pergunta? A funcionalidade principal é alcançada através da combinação do tipo de campo semantic_text e dos comandos FORK/FUSE (o FUSE usa RRF por padrão para mesclar os resultados de cada fork). Aqui está um exemplo simples de uma busca fictícia de produto:

A cláusula EVAL incluída em cada um dos ramos FORK no exemplo acima não é estritamente necessária; ela está incluída apenas para demonstrar como você pode rastrear de qual modalidade de pesquisa um determinado resultado foi retornado.

Modelos de pesquisa

Digamos que você queira direcionar suas próprias ferramentas externas de gerenciamento de agentes para sua implantação do Elasticsearch. E em vez de ES|QL, você deseja usar recuperadores de vários estágios ou reutilizar a sintaxe DSL existente que você desenvolveu, e também deseja poder controlar as entradas que a consulta aceita, a sintaxe usada para executar a pesquisa e os campos retornados na saída. Os modelos de pesquisa permitem que os usuários definam estruturas predefinidas para padrões de pesquisa comuns, melhorando a eficiência e a consistência na recuperação de dados. Isso é particularmente benéfico para ferramentas de agentes que interagem com APIs de busca, pois ajuda a padronizar o código repetitivo e permite uma iteração mais rápida na lógica de busca. E se alguma vez precisar ajustar algum desses fatores, basta atualizar o modelo de pesquisa e pronto, as alterações são implementadas. Se você procura um exemplo de modelos de pesquisa em ação com ferramentas agentivas, confira o blog do Elasticsearch Labs " MCP para pesquisa inteligente", que utiliza um modelo de pesquisa por trás de uma chamada de ferramenta de um servidor MCP externo.

Fluxos de trabalho integrados (SIM!)

Um dos aspectos mais difíceis de lidar em nosso novo mundo de IA com agentes é a natureza não determinística de agentes "racionais" semiautônomos e autodirigidos. A engenharia de contexto é uma disciplina crítica para a IA ativa: são as técnicas que ajudam a restringir as possíveis conclusões que nosso agente pode gerar ao que sabemos ser verdade fundamental. Mesmo com uma janela de contexto altamente precisa e relevante (quando saímos do âmbito dos fatos numéricos), ainda nos falta aquela garantia de que a resposta do agente seja totalmente repetível e confiável.

Ao executar a mesma solicitação para um agente várias vezes, as respostas podem ser essencialmente as mesmas, com apenas uma pequena diferença na forma como são enviadas. Isso geralmente funciona bem para consultas simples, talvez seja quase imperceptível, e podemos tentar moldar a saída com técnicas de engenharia de contexto. Mas, à medida que as tarefas que solicitamos aos nossos agentes se tornam mais complexas, aumenta a probabilidade de que uma ou mais subtarefas introduzam uma variação que altere ligeiramente o resultado final. É provável que a situação piore à medida que começarmos a depender mais da comunicação entre agentes, e essas variações se tornarão cumulativas. Isso reforça a ideia de que as ferramentas com as quais nossos agentes interagem precisam ser muito flexíveis e ajustáveis para direcionar com precisão os dados contextuais, e que devem responder em um formato de saída esperado. Isso também indica que, para muitos casos de uso, precisamos direcionar as interações entre agentes e ferramentas — é aí que os fluxos de trabalho entram em cena!

Em breve, a Elastic terá fluxos de trabalho totalmente personalizáveis integrados ao núcleo da plataforma. Esses fluxos de trabalho poderão operar com agentes e ferramentas de forma bidirecional, ou seja, os fluxos de trabalho poderão chamar agentes e ferramentas, e os agentes e ferramentas poderão chamar fluxos de trabalho. Ter essas funcionalidades totalmente integradas na mesma plataforma de IA de busca onde todos os seus dados residem será transformador; o potencial dos fluxos de trabalho é extremamente empolgante! Em breve, muito em breve!

Elástico como banco de memória unificado

Por ser uma plataforma de dados distribuída, criada para buscas quase em tempo real, a Elastic executa naturalmente as funções de memória de longo prazo para sistemas de IA com agentes. Com a experiência de chat integrada do Agent Builder, também temos rastreamento e gerenciamento da memória de curto prazo e do histórico de conversas. E como toda a plataforma é orientada a APIs, é extremamente fácil utilizar o Elastic como plataforma para persistir a saída contextual de uma ferramenta (e poder consultá-la posteriormente), o que poderia sobrecarregar a janela de contexto do agente; essa técnica às vezes é chamada de "anotações " em círculos de engenharia de contexto.

Ter memória de curto e longo prazo na mesma plataforma de busca traz muitos benefícios intrínsecos: imagine poder usar históricos de bate-papo e respostas contextuais persistentes como parte dos influenciadores semânticos em interações futuras, ou para realizar análises de ameaças, ou para criar produtos de dados persistentes que são gerados automaticamente a partir de chamadas de ferramentas repetidas com frequência… As possibilidades são infinitas!

Conclusão

O surgimento de grandes modelos de linguagem mudou a forma como conseguimos relacionar conteúdo e os métodos que usamos para analisar nossos dados. Estamos nos afastando rapidamente do mundo atual, onde os humanos realizam a pesquisa, a análise contextual e o raciocínio lógico para responder às suas próprias perguntas, para um mundo onde essas etapas são amplamente automatizadas por meio de inteligência artificial ativa. Para que possamos confiar nas respostas geradas que recebemos, precisamos ter a garantia de que o agente considerou todas as informações mais relevantes (incluindo o fator de relevância subjetiva) ao gerar sua resposta. Nosso principal método para tornar a IA agente confiável é fundamentar as ferramentas que recuperam contexto adicional por meio de técnicas de RAG (Aleatorização, Atribuição e Geração de Respostas) e engenharia de contexto, mas a forma como essas ferramentas realizam a recuperação inicial pode ser crucial para a precisão da resposta.

A plataforma Elastic Search AI oferece a flexibilidade e a vantagem da busca híbrida, juntamente com diversos recursos integrados que auxiliam a IA agente em termos de precisão, desempenho e escalabilidade; em outras palavras, o Elastic é uma plataforma fantástica para vários aspectos da engenharia de contexto! Ao padronizar a recuperação de contexto por meio de uma plataforma de busca, simplificamos as operações das ferramentas de inteligência artificial em várias frentes — e, assim como diz o paradoxo "ir mais devagar para ir mais rápido", a simplicidade na camada de geração de contexto significa uma IA mais rápida e confiável.

Uma nova forma de interagir com dados

A IA generativa (genAI) e a IA agentiva funcionam de maneira diferente da busca tradicional. Enquanto antes começávamos a pesquisar informações por meio de uma busca ("deixe-me pesquisar isso no Google..."), a ação inicial tanto para a IA de geração de robôs quanto para os agentes geralmente se dá por meio da linguagem natural inserida em uma interface de bate-papo. A interface de bate-papo é uma discussão com um LLM (Literatura Liderada pelo Senhor da Moeda) que usa sua compreensão semântica para transformar nossa pergunta em uma resposta concisa, uma resposta resumida que parece vir de um oráculo com amplo conhecimento de todos os tipos de informação. O que realmente convence é a capacidade do LLM de gerar frases coerentes e ponderadas que conectam os fragmentos de conhecimento que ele apresenta — mesmo quando são imprecisos ou totalmente alucinatórios, há uma sensação de veracidade neles.

Aquela velha barra de pesquisa com a qual nos acostumamos tanto a interagir pode ser considerada o mecanismo RAG que usávamos quando nós mesmos éramos o agente de raciocínio. Hoje em dia, até mesmo os mecanismos de busca da internet estão transformando nossa tradicional experiência de busca lexical, baseada em "catar e digitar", em resumos gerados por inteligência artificial que respondem à consulta com um sumário dos resultados, ajudando os usuários a evitar a necessidade de clicar e avaliar cada resultado individualmente.

IA Generativa e RAG

A IA generativa tenta usar sua compreensão semântica do mundo para analisar a intenção subjetiva expressa em uma solicitação de bate-papo e, em seguida, usa suas habilidades de inferência para criar uma resposta especializada instantaneamente. Uma interação com IA generativa possui várias partes: começa com a entrada/consulta do usuário, conversas anteriores na sessão de bate-papo podem ser usadas como contexto adicional, e a instrução que informa ao LLM como raciocinar e quais procedimentos seguir na construção da resposta. As instruções evoluíram de orientações simples do tipo "explique isso para mim como se eu tivesse cinco anos de idade" para explicações detalhadas de como processar as solicitações. Essas análises geralmente incluem seções distintas que descrevem detalhes da personalidade/função da IA, raciocínio pré-geração/processo de pensamento interno, critérios objetivos, restrições, formato de saída, público-alvo, bem como exemplos para ajudar a demonstrar os resultados esperados.

Além da consulta do usuário e da mensagem do sistema, a geração aumentada de recuperação (RAG, na sigla em inglês) fornece informações contextuais adicionais no que é chamado de "janela de contexto". O RAG tem sido uma adição crucial à arquitetura; é o que usamos para informar o LLM sobre as peças que faltam em sua compreensão semântica do mundo.

As janelas de contexto podem ser um tanto exigentes em termos do que, onde e quanto você lhes fornece. O contexto selecionado é muito importante, obviamente, mas a relação sinal-ruído do contexto fornecido também importa, assim como o tamanho da janela.

Informação insuficiente

Fornecer pouca informação em uma consulta, prompt ou janela de contexto pode levar a alucinações, pois o LLM não consegue determinar com precisão o contexto semântico correto para gerar uma resposta. Existem também problemas com a similaridade vetorial dos tamanhos dos fragmentos de documentos — uma pergunta curta e simples pode não se alinhar semanticamente com os documentos ricos e detalhados encontrados em nossas bases de conhecimento vetorizadas. Foram desenvolvidas técnicas de expansão de consultas, como Hypothetical Document Embeddings (HyDE) , que utilizam LLMs para gerar uma resposta hipotética mais rica e expressiva do que a consulta curta. O perigo aqui, claro, é que o documento hipotético seja em si uma alucinação que afasta ainda mais o LLM do contexto correto.

Informação em excesso

Assim como acontece conosco, humanos, o excesso de informações em uma janela de contexto pode sobrecarregar e confundir um usuário de linguagem natural sobre quais são as partes importantes. O estouro de contexto (ou "deterioração de contexto ") afeta a qualidade e o desempenho das operações de IA generativa; ele impacta significativamente o "orçamento de atenção" do LLM (sua memória de trabalho) e dilui a relevância entre muitos tokens concorrentes. O conceito de "deterioração do contexto" também inclui a observação de que os autores de livros didáticos tendem a ter um viés posicional — eles preferem o conteúdo no início ou no final de uma janela de contexto em relação ao conteúdo na seção intermediária.

Informações que distraem ou são contraditórias

Quanto maior for a janela de contexto, maior será a probabilidade de incluir informações supérfluas ou conflitantes que podem distrair o usuário do LLM (Liderança em Aprendizagem) de selecionar e processar o contexto correto. De certa forma, isso se torna um problema de "lixo entra, lixo sai": simplesmente despejar um conjunto de resultados de documentos em uma janela de contexto fornece ao LLM muita informação para processar (potencialmente em excesso), mas dependendo de como o contexto foi selecionado, há uma possibilidade maior de informações conflitantes ou irrelevantes se infiltrarem.

IA Agêntica

Eu disse que havia muito o que abordar, mas conseguimos — finalmente estamos falando sobre tópicos de IA agente! A IA Agética é uma nova e empolgante aplicação das interfaces de chat do LLM que expande a capacidade da IA generativa (podemos já chamá-la de "legada"?) de sintetizar respostas com base em seu próprio conhecimento e nas informações contextuais fornecidas pelo usuário. À medida que a IA generativa amadureceu, percebemos que havia um certo nível de tarefas e automação que poderíamos delegar aos LLMs, inicialmente relegadas a atividades tediosas e de baixo risco que podem ser facilmente verificadas/validadas por um humano. Em um curto período de tempo, esse escopo inicial cresceu: uma janela de bate-papo do LLM agora pode ser a faísca que envia um agente de IA para planejar, executar e avaliar e adaptar seu plano de forma autônoma e iterativa para atingir o objetivo especificado. Os agentes têm acesso ao raciocínio dos seus LLMs, ao histórico de conversas e à memória cognitiva (na medida do possível), e também dispõem de ferramentas específicas que podem utilizar para atingir esse objetivo. Também estamos vendo agora arquiteturas que permitem que um agente de nível superior funcione como orquestrador de múltiplos subagentes, cada um com suas próprias cadeias lógicas, conjuntos de instruções, contexto e ferramentas.

Os agentes são o ponto de entrada para um fluxo de trabalho em grande parte automatizado: eles são autônomos, pois conseguem conversar com um usuário e, em seguida, usar a "lógica" para determinar quais ferramentas estão disponíveis para ajudar a responder à pergunta do usuário. As ferramentas são geralmente consideradas passivas em comparação com os agentes e são construídas para realizar um único tipo de tarefa. Os tipos de tarefas que uma ferramenta pode executar são praticamente ilimitados (o que é realmente empolgante!), mas uma das principais tarefas que as ferramentas realizam é coletar informações contextuais para que um agente as considere ao executar seu fluxo de trabalho.

Como tecnologia, a IA ativa ainda está em sua infância e propensa ao equivalente acadêmico do transtorno de déficit de atenção — ela facilmente esquece o que lhe foi pedido para fazer e, muitas vezes, sai fazendo outras coisas que não faziam parte do escopo da tarefa. Por trás da aparente magia, as habilidades de "raciocínio" dos LLMs ainda se baseiam em prever o próximo token mais provável em uma sequência. Para que o raciocínio (ou, um dia, a inteligência artificial geral (IAG)) se torne confiável e digno de confiança, precisamos ser capazes de verificar se, ao recebermos as informações corretas e mais atualizadas, elas raciocinarão da maneira que esperamos (e talvez nos forneçam aquela informação extra que não havíamos imaginado). Para que isso aconteça, as arquiteturas agentivas precisarão da capacidade de se comunicar claramente (protocolos), de aderir aos fluxos de trabalho e restrições que lhes impomos (diretrizes), de lembrar em que ponto da tarefa estão (estado), de gerenciar seu espaço de memória disponível e de validar se suas respostas são precisas e atendem aos critérios da tarefa.

Fale comigo em uma língua que eu possa entender.

Como é comum em novas áreas de desenvolvimento (especialmente no mundo dos LLMs), inicialmente existiram várias abordagens para a comunicação entre agentes e ferramentas, mas elas rapidamente convergiram para o Protocolo de Contexto do Modelo (MCP) como o padrão de facto. A definição de Protocolo de Contexto de Modelo está literalmente no nome: é o protocolo que um modelo usa para solicitar e receber informações contextuais . O MCP funciona como um adaptador universal para que os agentes LLM se conectem a ferramentas e fontes de dados externas; ele simplifica e padroniza as APIs para que diferentes estruturas e ferramentas LLM possam interoperar facilmente. Isso faz do MCP uma espécie de ponto de articulação entre a lógica de orquestração e os comandos do sistema dados a um agente para que ele execute tarefas de forma autônoma a serviço de seus objetivos, e as operações enviadas às ferramentas para que sejam executadas de maneira mais isolada (isolada, pelo menos, em relação ao agente iniciador).

Este ecossistema é tão novo que cada direção de expansão parece uma nova fronteira. Temos protocolos semelhantes para interações agente-a-agente (Agent2Agent (A2A) , claro!), bem como outros projetos para melhorar a memória de raciocínio do agente (ReasoningBank), para selecionar o melhor servidor MCP para a tarefa em questão (RAG-MCP) e usar análise semântica, como classificação zero-shot e detecção de padrões na entrada e saída, como Guardrails para controlar sobre o que um agente pode operar.

Você deve ter percebido que a intenção subjacente de cada um desses projetos é melhorar a qualidade e o controle das informações retornadas para uma janela de contexto do agente/genAI? Embora o ecossistema de IA agente continue a desenvolver a capacidade de lidar melhor com essas informações contextuais (para controlá-las, gerenciá-las e operá-las), sempre haverá a necessidade de recuperar as informações contextuais mais relevantes como matéria-prima para o agente processar.

Bem-vindo à engenharia de contexto!

Se você está familiarizado com os termos de IA generativa, provavelmente já ouviu falar de 'engenharia de prompts' - a essa altura, é quase uma pseudociência em si mesma. A engenharia de prompts é usada para encontrar as melhores e mais eficientes maneiras de descrever proativamente os comportamentos que você deseja que o LLM utilize ao gerar sua resposta. A " engenharia de contexto" estende as técnicas de "engenharia de prompts" além do lado do agente, abrangendo também as fontes e sistemas de contexto disponíveis no lado das ferramentas do protocolo MCP, e inclui os tópicos gerais de gerenciamento, processamento e geração de contexto:

• Gerenciamento de contexto - Relacionado à manutenção da eficiência de estado e contexto em fluxos de trabalho de agentes de longa duração e/ou mais complexos. Planejamento, acompanhamento e orquestração iterativos de tarefas e chamadas de ferramentas para atingir os objetivos do agente. Devido ao limitado "orçamento de atenção" com que os agentes têm que trabalhar, o gerenciamento de contexto se preocupa principalmente com técnicas que ajudam a refinar a janela de contexto para capturar tanto o escopo mais completo quanto os elementos mais importantes do contexto (sua precisão versus abrangência!). As técnicas incluem compressão, sumarização e persistência do contexto de etapas anteriores ou chamadas de ferramentas para liberar espaço na memória de trabalho para contexto adicional em etapas subsequentes.

• Processamento de contexto - Os passos lógicos e, idealmente, em sua maioria programáticos para integrar, normalizar ou refinar o contexto adquirido de fontes distintas, de modo que o agente possa raciocinar sobre todo o contexto de maneira relativamente uniforme. O objetivo principal é tornar o contexto de todas as fontes (sugestões, RAG, memória, etc.) o mais acessível possível ao agente.

• Geração de contexto - Se o processamento de contexto visa tornar o contexto recuperado utilizável para o agente, então a geração de contexto permite que o agente solicite e receba informações contextuais adicionais conforme desejar, mas também com restrições.

Os diversos elementos efêmeros dos aplicativos de bate-papo do LLM se relacionam diretamente (e às vezes de maneiras sobrepostas) com essas funções de alto nível da engenharia de contexto:

• Instruções / avisos do sistema - Os avisos servem de base para que a atividade de IA generativa (ou agentiva) direcione seu raciocínio para atingir o objetivo do usuário. Os prompts são um contexto por si só; não são apenas instruções de tom — frequentemente incluem lógica de execução da tarefa e regras para coisas como "pensar passo a passo" ou "respirar fundo" antes de responder, para validar se a resposta atende completamente à solicitação do usuário. Testes recentes demonstraram que as linguagens de marcação são muito eficazes para estruturar as diferentes partes de um enunciado, mas também é preciso ter cuidado para calibrar as instruções, encontrando um equilíbrio ideal entre serem vagas demais e específicas demais; queremos fornecer instruções suficientes para que o LLM encontre o contexto correto, mas não ser tão prescritivos a ponto de perder insights inesperados.

• Memória de curto prazo (estado/histórico) - A memória de curto prazo consiste essencialmente nas interações da sessão de bate-papo entre o usuário e o LLM. Essas informações são úteis para refinar o contexto em sessões ao vivo e podem ser salvas para consulta e continuação futuras.

• Memória de longo prazo - A memória de longo prazo deve consistir em informações que sejam úteis em múltiplas sessões. E não se trata apenas de bases de conhecimento específicas de domínio acessadas por meio do RAG; pesquisas recentes utilizam os resultados de solicitações anteriores de IA agentiva/generativa para aprender e referenciar em interações agentivas atuais. Algumas das inovações mais interessantes na área da memória de longo prazo estão relacionadas ao ajuste da forma como o estado é armazenado e vinculado, para que os agentes possam retomar de onde pararam.

• Saída estruturada - A cognição exige esforço, então provavelmente não é surpresa que, mesmo com capacidades de raciocínio, os LLMs (assim como os humanos) queiram despender menos esforço ao pensar e, na ausência de uma API ou protocolo definido, ter um mapa (um esquema) de como ler os dados retornados por uma chamada de ferramenta é extremamente útil. A inclusão de Saídas Estruturadas como parte da estrutura agentiva ajuda a tornar essas interações máquina a máquina mais rápidas e confiáveis, com menos necessidade de análise sintática guiada pelo pensamento.

• Ferramentas disponíveis - As ferramentas podem realizar todo tipo de tarefa, desde coletar informações adicionais (por exemplo, enviar consultas RAG para repositórios de dados corporativos ou por meio de APIs online) até executar ações automatizadas em nome do agente (como reservar um quarto de hotel com base nos critérios da solicitação do agente). As ferramentas também podem ser subagentes com suas próprias cadeias de processamento.

• Geração Aumentada por Recuperação (RAG) - Eu realmente gosto da descrição de RAG como "integração dinâmica de conhecimento". Conforme descrito anteriormente, RAG é a técnica para fornecer as informações adicionais às quais o LLM não teve acesso durante seu treinamento, ou seja, é uma reiteração das ideias que consideramos mais importantes para obter a resposta correta — aquela que é mais relevante para nossa pergunta subjetiva.

Poder cósmico fenomenal, espaço vital minúsculo!

A IA agente tem muitos novos domínios fascinantes e empolgantes para explorar! Ainda existem muitos dos antigos problemas tradicionais de recuperação e processamento de dados a serem resolvidos, mas também novas classes de desafios que só agora estão vindo à tona na nova era dos LLMs. Muitos dos problemas imediatos que estamos enfrentando hoje estão relacionados à engenharia de contexto, ou seja, a como fornecer aos LLMs (Learning Learning Machines - Máquinas de Memória de Longo Prazo) as informações contextuais adicionais de que precisam sem sobrecarregar seu espaço limitado de memória de trabalho.

A flexibilidade de agentes semiautônomos que têm acesso a uma variedade de ferramentas (e outros agentes) dá origem a tantas novas ideias para implementar IA que é difícil imaginar as diferentes maneiras pelas quais poderíamos juntar as peças. A maior parte da pesquisa atual se enquadra no campo da engenharia de contexto e está focada na construção de estruturas de gerenciamento de memória que possam lidar e rastrear quantidades maiores de contexto — isso porque os problemas de raciocínio profundo que realmente queremos que os LLMs resolvam apresentam maior complexidade e etapas de pensamento mais longas e multifásicas, onde a memorização é extremamente importante.

Grande parte da experimentação em curso na área visa encontrar a gestão de tarefas e as configurações de ferramentas ideais para alimentar a "boca" dos agentes. Cada chamada de ferramenta na cadeia de raciocínio de um agente acarreta um custo cumulativo, tanto em termos de computação necessária para executar a função dessa ferramenta quanto em termos do impacto na janela de contexto limitada. Algumas das técnicas mais recentes para gerenciar o contexto de agentes LLM causaram efeitos em cadeia indesejados, como o "colapso de contexto ", em que a compressão/resumo do contexto acumulado para tarefas de longa duração resulta em perda excessiva de dados. O objetivo é obter ferramentas que retornem um contexto conciso e preciso, sem que informações irrelevantes ocupem o valioso espaço de memória da janela de contexto.

Tantas possibilidades

Desejamos separação de funções com flexibilidade para reutilizar ferramentas/componentes, portanto, faz todo o sentido criar ferramentas dedicadas e automatizadas para conectar-se a fontes de dados específicas — cada ferramenta pode se especializar em consultar um tipo de repositório, um tipo de fluxo de dados ou até mesmo um caso de uso. Mas atenção: na ânsia de economizar tempo/dinheiro/provar que algo é possível, haverá uma forte tentação de usar os LLMs como ferramenta de federação… Tente não fazer isso, já passamos por essa situação antes! A consulta federada funciona como um "tradutor universal" que converte uma consulta recebida na sintaxe que o repositório remoto entende e, em seguida, precisa racionalizar os resultados de múltiplas fontes em uma resposta coerente. A federação como técnica funciona bem em pequenas escalas, mas em grandes escalas, e especialmente quando os dados são multimodais, a federação tenta preencher lacunas que são simplesmente muito grandes.

No mundo agentivo, o agente seria o federador e as ferramentas (através do MCP) seriam as conexões definidas manualmente com recursos distintos. Utilizar ferramentas específicas para acessar fontes de dados desconectadas pode parecer uma nova e poderosa maneira de unir dinamicamente diferentes fluxos de dados para cada consulta, mas usar essas ferramentas para fazer a mesma pergunta a várias fontes provavelmente acabará causando mais problemas do que soluções. Cada uma dessas fontes de dados provavelmente consiste em diferentes tipos de repositórios subjacentes, cada um com suas próprias capacidades de recuperar, classificar e proteger os dados neles contidos. Essas variações ou "incompatibilidades de impedância" entre os repositórios aumentam a carga de processamento, obviamente. Eles também podem introduzir informações ou sinais conflitantes, onde algo aparentemente inócuo como um desalinhamento na pontuação pode alterar drasticamente a importância atribuída a um trecho do contexto retornado e afetar a relevância da resposta gerada no final.

A troca de contexto também é difícil para os computadores.

Quando você envia um agente em uma missão, muitas vezes a primeira tarefa dele é encontrar todos os dados relevantes aos quais ele tem acesso. Assim como acontece com os humanos, se cada fonte de dados à qual o agente se conecta responde com informações diferentes e desagregadas, haverá uma carga cognitiva (embora não exatamente do mesmo tipo) associada à extração dos elementos contextuais relevantes do conteúdo recuperado. Isso requer tempo/computação, e cada pequeno detalhe se soma na cadeia lógica agentiva. Isso nos leva à conclusão de que, assim como está sendo discutido para o MCP, a maioria das ferramentas de agentes deveria se comportar mais como APIs — funções isoladas com entradas e saídas conhecidas, ajustadas para atender às necessidades de diferentes tipos de agentes. Aliás, estamos até percebendo que os LLMs precisam de contexto para contexto — eles se saem muito melhor em conectar os pontos semânticos, especialmente quando se trata de uma tarefa como traduzir linguagem natural para sintaxe estruturada, quando têm um esquema ao qual se referir (leia o manual, de fato!).

Intervalo da sétima entrada!

Já abordamos o impacto que os LLMs tiveram na recuperação e consulta de dados, bem como a forma como a janela de bate-papo está evoluindo para uma experiência de IA ativa. Vamos juntar os dois tópicos e ver como podemos usar nossos recursos modernos de busca e recuperação para melhorar nossos resultados em engenharia de contexto. Vamos para a Parte III: O poder da busca híbrida na engenharia de contexto!

Os sistemas atuais baseados em LLM estão evoluindo rapidamente, deixando de ser aplicações de modelo único e se tornando redes complexas onde agentes especializados trabalham juntos para realizar tarefas antes consideradas impossíveis pela computação moderna. À medida que esses sistemas se tornam mais complexos, a infraestrutura que permite a comunicação entre agentes e o acesso a ferramentas passa a ser o foco principal do desenvolvimento. Surgiram duas abordagens complementares para atender a essas necessidades: os protocolos Agent2Agent (A2A) para coordenação multiagente e o Model Context Protocol (MCP) para acesso padronizado a ferramentas e recursos.

Compreender quando usar cada um em harmonia com o outro e quando utilizá-los isoladamente pode impactar significativamente a escalabilidade, a facilidade de manutenção e a eficácia de suas aplicações. Este artigo explora os conceitos e implementações do modelo A2A (Application -to-Application) no exemplo prático de uma redação digital, onde agentes especializados em LLM (Legal Learning Management) colaboram para pesquisar, escrever, editar e publicar artigos de notícias.

Um repositório complementar pode ser encontrado aqui, e examinaremos exemplos concretos do A2A em ação perto do final do artigo, na Seção 5.

Pré-requisitos

O repositório consiste em implementações em Python dos agentes A2A. O Flask fornece um servidor de API, bem como um serviço de mensagens personalizado em Python chamado Event Hub, que encaminha mensagens para registro e atualizações da interface do usuário. Por fim, uma interface de usuário React é fornecida para uso independente dos recursos da sala de imprensa. Tudo está contido em uma imagem Docker para facilitar a implementação. Se você deseja executar os serviços diretamente em sua máquina, precisará garantir que tenha as seguintes tecnologias instaladas:

Linguagens e ambientes de execução

• Python 13.12 - Linguagem principal de backend

• Node.js 18+ - Interface de usuário React opcional

Frameworks principais e SDKs:

• SDK A2A 0.3.8 - Coordenação e comunicação de agentes

• SDK Antrópico - Integração com Claude para geração de IA

• Uvicorn - Servidor ASGI para executar agentes

• FastMCP 2.12.5+ - Implementação do servidor MCP

• React 18.2 - Framework de interface de usuário para front-end

Dados e pesquisa

• Elasticsearch 9.1.1+ - Indexação e pesquisa de artigos

Implantação do Docker (opcional, mas recomendada)

• Docker 28.5.1+

Seção 1: O que é Agent2Agent (A2A)?

Definição e conceitos fundamentais

Agent2Agent (A2A) é um protocolo padronizado para interação entre agentes LLM independentes. Em vez de um único sistema monolítico que lida com todas as tarefas, o A2A permite que vários agentes especializados se comuniquem, coordenem e colaborem para realizar fluxos de trabalho complexos que seriam difíceis, lentos ou simplesmente impossíveis de serem gerenciados com eficiência por um único agente.

Especificação oficial: https://a2a-protocol.org/latest/specification/

Origens e evolução

O conceito de comunicação Agente para Agente, ou sistemas multiagentes, tem raízes em sistemas distribuídos, microsserviços e pesquisas multiagentes que remontam a décadas. Os primeiros trabalhos em inteligência artificial distribuída lançaram as bases para agentes capazes de negociar, coordenar e colaborar. Esses primeiros sistemas eram dedicados a simulações sociais em larga escala, pesquisa acadêmica e gerenciamento de redes elétricas.

Com o surgimento da disponibilidade do LLM e a redução do custo de operação, os sistemas multiagentes tornaram-se acessíveis aos mercados "prosumidores", com o apoio do Google e da comunidade de pesquisa em IA em geral. Agora conhecidos como sistemas Agent2Agent, a adição do protocolo A2A evoluiu para um padrão moderno projetado especificamente para a era de múltiplos modelos de linguagem de grande porte coordenando esforços e tarefas.

O protocolo A2A garante comunicação e coordenação perfeitas entre os agentes, aplicando padrões e princípios consistentes aos pontos de interação onde os LLMs se conectam e se comunicam. Essa padronização permite que agentes de diferentes desenvolvedores — que utilizam diferentes modelos subjacentes — trabalhem juntos de forma eficaz.

Os protocolos de comunicação não são novidade e estão amplamente estabelecidos em praticamente todas as transações digitais realizadas na internet. Se você digitou https://www.elastic.co/search-labs Ao acessar este artigo por meio de um navegador, é muito provável que os protocolos TCP/IP, HTTP e de consulta DNS tenham sido executados, garantindo uma experiência de navegação consistente.

Características principais

Os sistemas A2A são construídos sobre diversos princípios fundamentais para garantir uma comunicação fluida. Com base nesses princípios, garante-se que diferentes agentes, utilizando diferentes LLMs, frameworks e linguagens de programação, interajam perfeitamente.

Eis os quatro princípios principais:

• Troca de mensagens: Os agentes comunicam-se por meio de mensagens estruturadas com propriedades e formatos bem definidos.

• Coordenação: Os agentes orquestram fluxos de trabalho complexos, delegando tarefas uns aos outros e gerenciando dependências sem bloquear outros agentes.

• Especialização: Cada agente se concentra em um domínio ou capacidade específica, tornando-se um especialista em sua área e oferecendo a conclusão de tarefas com base nessa habilidade.

• Estado distribuído: O estado e o conhecimento são distribuídos entre os agentes em vez de centralizados, sendo que os agentes têm a capacidade de atualizar uns aos outros sobre o progresso da tarefa, o estado e os retornos parciais (artefatos).

A redação: um exemplo prático

Imagine uma redação digital alimentada por agentes de IA, cada um especializado em um aspecto diferente do jornalismo:

• Chefe de Notícias (coordenador/cliente): Atribui pautas e supervisiona o fluxo de trabalho.

• Agente de reportagem: Redige artigos com base em pesquisas e entrevistas.

• Agente de Pesquisa: Reúne fatos, estatísticas e informações de contexto.

• Agente de Arquivo: Pesquisa artigos históricos e identifica tendências usando o Elasticsearch.

• Agente Editorial: Analisa artigos quanto à qualidade, estilo e otimização para SEO.

• Agente de Publicação: Publica artigos aprovados na plataforma do blog via CI/CD

Esses profissionais não trabalham isoladamente; quando o chefe de jornalismo atribui uma matéria sobre a adoção de energias renováveis, o repórter precisa do pesquisador para coletar as estatísticas, do editor para revisar o rascunho e do editor-chefe para publicar a versão final. Essa coordenação ocorre por meio de protocolos A2A.

Seção 2: Compreendendo a arquitetura A2A

Funções de Agente de Atendimento ao Cliente e Agente Remoto

Na arquitetura A2A, os agentes assumem dois papéis principais. O Agente Cliente é responsável por formular e comunicar tarefas a outros agentes no sistema. Identifica agentes remotos e suas capacidades, usando essas informações para tomar decisões fundamentadas sobre a delegação de tarefas. O agente do cliente coordena o fluxo de trabalho geral, garantindo que as tarefas sejam distribuídas adequadamente e que o sistema progrida em direção aos seus objetivos.

O Agente Remoto, por outro lado, executa tarefas delegadas pelos clientes. Ela fornece informações ou toma medidas específicas em resposta a solicitações, mas não inicia ações de forma independente. Os agentes remotos também podem se comunicar com outros agentes remotos conforme necessário para cumprir suas responsabilidades atribuídas, criando uma rede colaborativa de capacidades especializadas.

Em nossa redação, o Chefe de Notícias atua como agente do cliente, enquanto o Repórter, o Pesquisador, o Editor e o Diretor de Publicação são agentes remotos que respondem às solicitações e se coordenam entre si.

Principais funcionalidades A2A

Os protocolos A2A definem diversas capacidades que permitem a colaboração multiagente:

1. Descoberta

Os servidores A2A devem anunciar suas funcionalidades para que os clientes saibam quando e como utilizá-las para tarefas específicas. Isso é feito por meio de Cartões de Agente — documentos JSON que descrevem as habilidades, entradas e saídas de um agente. Os cartões de agente são disponibilizados em endpoints consistentes e conhecidos (como o endpoint recomendado /.well-known/agent-card.json ), permitindo que os clientes descubram e consultem as capacidades de um agente antes de iniciar a colaboração.

Abaixo, segue um exemplo de cartão de agente para o agente de arquivamento personalizado da Elastic, "Archie Archivist". Note que fornecedores de software como a Elastic hospedam seus agentes A2A e fornecem um URL para acesso:

Este cartão de agente revela vários aspectos importantes do agente de arquivamento da Elastic. O agente se identifica como "Archie Archivist" e declara claramente seu propósito: ajudar a encontrar documentos de notícias históricas em um índice do Elasticsearch. O cartão especifica o provedor (Elastic) e a versão do protocolo (0.3.0), garantindo a compatibilidade com outros agentes compatíveis com A2A. Mais importante ainda, a matriz skills enumera as capacidades específicas que este agente oferece, incluindo funcionalidades de pesquisa poderosas e exploração inteligente de índices. Cada habilidade define quais modos de entrada e saída ela suporta, permitindo que os clientes entendam exatamente como se comunicar com esse agente. Este agente deriva do serviço Agent Builder da Elastic, que fornece um conjunto de ferramentas nativas com suporte a LLM e endpoints de API para interagir com seu armazenamento de dados, e não apenas para recuperar dados dele. O acesso aos agentes A2A no Elasticsearch pode ser encontrado aqui.

2. Negociação

Clientes e agentes precisam concordar com os métodos de comunicação — sejam as interações realizadas por meio de texto, formulários, iframes ou até mesmo áudio/vídeo — para garantir a interação adequada do usuário e a troca de dados. Essa negociação ocorre no início da colaboração entre os agentes e estabelece os protocolos que irão reger sua interação ao longo do fluxo de trabalho. Por exemplo, um agente de atendimento ao cliente baseado em voz pode negociar para se comunicar por meio de fluxos de áudio, enquanto um agente de análise de dados pode preferir JSON estruturado. O processo de negociação garante que ambas as partes possam trocar informações de forma eficaz, num formato que se adeque às suas capacidades e às exigências da tarefa em questão.

As funcionalidades listadas no trecho JSON acima possuem esquemas de entrada e saída; estes definem uma expectativa de como outros agentes devem interagir com este agente.

3. Gestão de tarefas e estados

Clientes e agentes precisam de mecanismos para comunicar o status das tarefas, alterações e dependências ao longo da execução das mesmas. Isso inclui gerenciar todo o ciclo de vida de uma tarefa, desde a criação e atribuição até as atualizações de progresso e alterações de status. Os status típicos incluem pendente, em andamento, concluído ou reprovado. O sistema também deve rastrear as dependências entre as tarefas para garantir que o trabalho prévio seja concluído antes do início das tarefas dependentes. O tratamento de erros e a lógica de repetição também são componentes essenciais, permitindo que o sistema se recupere de forma adequada de falhas e continue progredindo em direção ao objetivo principal.

Exemplo de mensagem de tarefa:

Esta mensagem de tarefa de exemplo demonstra vários aspectos importantes da comunicação A2A.

• A estrutura da mensagem inclui metadados como um identificador único da mensagem, o tipo de mensagem que está sendo enviada, a identificação do remetente e do destinatário e um registro de data e hora para rastreamento e depuração.

• A carga útil contém as informações reais da tarefa, especificando qual funcionalidade está sendo invocada no agente remoto e fornecendo os parâmetros necessários para executar essa funcionalidade.

• A seção de contexto fornece informações adicionais que ajudam o agente receptor a entender o fluxo de trabalho mais amplo, incluindo prazos e níveis de prioridade que orientam a forma como o agente deve alocar seus recursos e programar seu trabalho.

4. Colaboração

Clientes e agentes devem dar suporte a uma interação dinâmica, porém estruturada, permitindo que os agentes solicitem esclarecimentos, informações ou subações do cliente, de outros agentes ou de usuários. Isso cria um ambiente colaborativo onde os agentes podem fazer perguntas de acompanhamento quando as instruções iniciais forem ambíguas, solicitar contexto adicional para tomar melhores decisões, delegar subtarefas a outros agentes com conhecimento mais adequado e fornecer resultados intermediários para feedback antes de prosseguir com a tarefa completa. Essa comunicação multidirecional garante que os agentes não trabalhem isoladamente, mas sim que estejam engajados em um diálogo contínuo que leva a melhores resultados.

Comunicação distribuída, ponto a ponto

A tecnologia A2A permite a comunicação distribuída, na qual os agentes podem ser hospedados por diferentes organizações, com alguns agentes mantidos internamente, enquanto outros são fornecidos por serviços de terceiros. Esses agentes podem ser executados em diferentes infraestruturas, abrangendo potencialmente vários provedores de nuvem ou centros de dados locais. Eles podem usar diferentes modelos de aprendizado de máquina subjacentes, com alguns agentes baseados em modelos GPT, outros em Claude e outros ainda em alternativas de código aberto. Os agentes podem até operar em diferentes regiões geográficas para cumprir os requisitos de soberania de dados ou reduzir a latência. Apesar dessa diversidade, todos os agentes concordam com um protocolo de comunicação comum para a troca de informações, garantindo a interoperabilidade independentemente dos detalhes de implementação. Essa arquitetura distribuída proporciona flexibilidade na forma como os sistemas são construídos e implantados, permitindo que as organizações combinem os melhores agentes e infraestrutura para suas necessidades específicas.

Esta é a arquitetura final do aplicativo da redação:

Seção 3: Protocolo de Contexto do Modelo (MCP)

Definição e propósito

O Protocolo de Contexto do Modelo (MCP) é um protocolo padronizado desenvolvido pela Anthropic para aprimorar e capacitar um LLM individual com ferramentas, recursos e instruções definidos pelo usuário, entre outras adições suplementares ao código-fonte. O MCP fornece uma interface universal entre modelos de linguagem e os recursos externos necessários para que eles concluam tarefas com eficácia. Este artigo descreve o estado atual do MCP com exemplos de casos de uso, tendências emergentes e a implementação da própria Elastic.

Conceitos básicos do MCP

O MCP opera em uma arquitetura cliente-servidor com três componentes principais:

• Clientes: aplicativos (como o Claude Desktop ou aplicativos de IA personalizados) que se conectam aos servidores MCP para acessar suas funcionalidades.

• Servidores: aplicações que expõem recursos, ferramentas e instruções para modelos de linguagem. Cada servidor é especializado em fornecer acesso a funcionalidades ou fontes de dados específicas.

  • Ferramentas: funções definidas pelo usuário que os modelos podem invocar para executar ações, como pesquisar bancos de dados, chamar APIs externas ou realizar transformações nos dados.

  • Recursos: fontes de dados que os modelos podem ler, fornecidas com dados dinâmicos ou estáticos e acessadas por meio de padrões de URI (semelhantes a rotas REST).

  • Instruções: modelos de instruções reutilizáveis com variáveis que orientam o modelo na realização de tarefas específicas.

Padrão de solicitação-resposta

O MCP segue um padrão de interação de solicitação-resposta familiar, semelhante às APIs REST. O cliente (LLM) solicita um recurso ou invoca uma ferramenta; em seguida, o servidor MCP processa a solicitação e retorna o resultado, que o LLM utiliza para continuar sua tarefa. Este modelo centralizado com servidores periféricos oferece um padrão de integração mais simples em comparação com a comunicação entre agentes ponto a ponto.

MCP na redação

Em nosso exemplo de redação, os agentes individuais usam servidores MCP para acessar as ferramentas e os dados de que precisam:

• O Agente de Pesquisa utiliza:

  • Servidor MCP da API de notícias (acesso a bancos de dados de notícias)

  • Servidor MCP de verificação de fatos (verifica alegações em fontes confiáveis)

  • Servidor MCP de base de dados académica (artigos académicos e investigação)

• O agente repórter utiliza:

  • Guia de Estilo do Servidor MCP (padrões de redação para redações)

  • Servidor MCP de modelos (modelos e formatos de artigos)

  • Servidor MCP da Biblioteca de Imagens (fotos e gráficos de banco de imagens)

• O Editor Agent utiliza:

  • Servidor MCP do Verificador Gramatical (ferramentas de qualidade linguística)

  • Servidor MCP de Detecção de Plágio (verificação de originalidade)

  • Servidor MCP de Análise de SEO (otimização de títulos e palavras-chave)

• O Publisher Agent utiliza:

  • Servidor CMS MCP (API do sistema de gerenciamento de conteúdo)

  • Servidor CI/CD MCP (pipeline de implantação)

  • Servidor MCP de análise (rastreamento e monitoramento)

Seção 4: comparação de arquiteturas

Quando usar o A2A

A arquitetura A2A se destaca em cenários que exigem colaboração multiagente genuína. Fluxos de trabalho com várias etapas que exigem coordenação se beneficiam muito do A2A, principalmente quando as tarefas envolvem várias etapas sequenciais ou paralelas, fluxos de trabalho que exigem iteração e refinamento, e processos com pontos de verificação e necessidades de validação. Em nosso exemplo de redação, o fluxo de trabalho da matéria exige que o Repórter escreva, mas pode precisar consultar o Pesquisador se a confiança em certos fatos for baixa, depois passar para o Editor e, finalmente, para o Editor-Chefe.

A especialização em domínios específicos em diversas áreas é outro caso de uso importante para o A2A. Quando vários especialistas em diversas áreas são necessários para realizar uma tarefa maior, com cada agente trazendo conhecimento profundo do domínio e capacidades de raciocínio especializadas para diferentes aspectos, o A2A fornece a estrutura de coordenação necessária para fazer essas conexões. A redação exemplifica isso perfeitamente: o pesquisador se especializa na coleta de informações, o repórter na redação e o editor no controle de qualidade — cada um com uma especialização distinta.

A necessidade de comportamento autônomo dos agentes torna o A2A particularmente valioso. Agentes capazes de tomar decisões independentes, demonstrar comportamento proativo com base em condições variáveis e se adaptar dinamicamente aos requisitos do fluxo de trabalho prosperam em uma arquitetura A2A. A escalabilidade horizontal de funções especializadas é outra vantagem fundamental: em vez de ter um único agente que domina todas as tarefas, vários agentes especializados trabalham em coordenação, e várias instâncias do mesmo agente podem lidar com subtarefas de forma assíncrona. Durante a cobertura de notícias de última hora em nossa redação, por exemplo, vários repórteres podem trabalhar simultaneamente em diferentes ângulos da mesma história.

Por fim, tarefas que exigem colaboração genuína entre múltiplos agentes são ideais para o A2A. Isso inclui mecanismos de avaliação do LLM como júri , sistemas de consenso e votação, e resolução colaborativa de problemas onde múltiplas perspectivas são necessárias para alcançar o melhor resultado.

Quando usar o MCP

O Protocolo de Contexto de Modelo é ideal para ampliar as capacidades de um único modelo de IA. Quando um único modelo de IA precisa acessar várias ferramentas e fontes de dados, o MCP oferece a solução perfeita, combinando raciocínio centralizado com ferramentas distribuídas e integração de ferramentas simplificada. Em nosso exemplo de redação, o Agente Pesquisador (um modelo) precisa de acesso a múltiplas fontes de dados, incluindo a API de Notícias, serviços de verificação de fatos e bases de dados acadêmicas — todas acessadas por meio de servidores MCP padronizados.

A integração de ferramentas padronizadas torna-se uma prioridade quando o amplo compartilhamento e a reutilização dessas integrações são importantes. O MCP se destaca aqui com seu ecossistema de servidores MCP pré-configurados, que reduzem significativamente o tempo de desenvolvimento para integrações comuns. Quando simplicidade e facilidade de manutenção são necessárias, os padrões de solicitação-resposta do MCP são familiares aos desenvolvedores, mais fáceis de entender e depurar do que sistemas distribuídos e apresentam menor complexidade operacional.

Por fim, o MCP costuma ser oferecido por fornecedores de software para facilitar a comunicação remota com seus sistemas. Esses servidores MCP oferecidos pelo provedor reduzem significativamente o tempo de integração e desenvolvimento, ao mesmo tempo que oferecem uma interface padronizada para sistemas proprietários, tornando a integração muito mais simples do que o desenvolvimento de APIs personalizadas.

Quando usar ambos (MCP da A2A ❤️)

Muitos sistemas sofisticados se beneficiam da combinação de A2A e MCP, conforme observado na documentação da A2A sobre integração com MCP. Sistemas que exigem tanto coordenação quanto padronização são candidatos ideais para uma abordagem híbrida. O A2A lida com a coordenação de agentes e a orquestração de fluxos de trabalho, enquanto o MCP fornece acesso a ferramentas para agentes individuais. Em nosso exemplo de redação, os agentes se coordenam por meio do sistema A2A (atendimento ao usuário), com o fluxo de trabalho indo do repórter para o pesquisador, para o editor e, finalmente, para o editor-chefe. No entanto, cada agente utiliza servidores MCP para suas ferramentas especializadas, criando uma clara separação arquitetural.

A presença de múltiplos agentes especializados, cada um utilizando o MCP para acesso a ferramentas, representa um padrão comum onde existe uma camada de coordenação de agentes gerenciada pelo A2A e uma camada de acesso a ferramentas gerenciada pelo MCP. Essa clara separação de responsabilidades torna os sistemas mais fáceis de entender e manter.

Os benefícios de combinar ambas as abordagens são substanciais. Você obtém os benefícios organizacionais dos sistemas multiagentes, incluindo especialização, autonomia e processamento paralelo, ao mesmo tempo que desfruta dos benefícios de padronização e ecossistema do MCP, como integração de ferramentas e acesso a recursos. Existe uma clara separação entre a coordenação de agentes (A2A) e o acesso a recursos (MCP) e, o que é importante, a A2A não é necessária para tarefas menores, como o acesso à API isoladamente — a MCP lida com essas tarefas de forma eficiente, sem a sobrecarga da orquestração multiagente.

FAQ: A2A vs. MCP - Casos de uso

Recurso

Agente para Agente (A2A)

Protocolo de Contexto do Modelo (MCP)

Híbrido (A2A + MCP)

Objetivo principal

Coordenação multiagente: Permite que uma equipe de agentes especializados trabalhe em conjunto em fluxos de trabalho complexos e com várias etapas.

Aprimoramento para agente único: Amplia a capacidade de um único LLM/Agente com ferramentas, recursos e dados externos.

Força combinada: A2A gerencia o fluxo de trabalho da equipe, enquanto a MCP fornece ferramentas para cada membro da equipe.

Exemplo de equipe de redação

A cadeia de fluxo de trabalho: Chefe de Notícias → Repórter → Pesquisador → Editor → Publicador. Esta é a camada de coordenação.

Ferramentas do agente individual: O Agente Repórter acessa o servidor de guia de estilo e o servidor de modelos (via MCP). Esta é a camada de acesso à ferramenta.

O sistema completo: o repórter coordena com o editor (A2A) e utiliza o servidor MCP da biblioteca de imagens para encontrar uma imagem para a matéria.

Quando usar qual

Quando você precisa de colaboração genuína, iteração e aprimoramento, ou de conhecimento especializado dividido entre vários agentes.

Quando um único agente precisa acessar várias ferramentas e fontes de dados ou requer integração padronizada com sistemas proprietários.

Quando você precisa dos benefícios organizacionais dos sistemas multiagentes e dos benefícios de padronização e ecossistema do MCP.

Benefício principal

Autonomia e escalabilidade: Os agentes podem tomar decisões independentes e o sistema permite a escalabilidade horizontal de funções especializadas.

Simplicidade e padronização: Mais fácil de depurar e manter devido ao raciocínio centralizado, além de fornecer uma interface universal para recursos.

Separação clara de responsabilidades: torna o sistema mais fácil de entender: A2A = trabalho em equipe, MCP = acesso à ferramenta.

Conclusão

Esta é a primeira parte de um artigo em duas seções que aborda a implementação de agentes baseados em A2A, reforçados com servidores MCP para fornecer suporte e acesso externo a dados e ferramentas. A próxima parte explorará o código real para demonstrar como eles funcionam em conjunto, simulando as atividades de uma redação online. Embora ambas as estruturas sejam extremamente capazes e flexíveis por si só, você verá o quanto elas se complementam quando trabalham em conjunto.

Neste blog, usaremos o Mastra para construir um agente de conhecimento que memoriza o que os usuários dizem e consegue recuperar informações relevantes posteriormente, utilizando o Elasticsearch como backend de memória e recuperação. Você pode facilmente estender esse mesmo conceito a casos de uso do mundo real, como agentes de suporte que conseguem se lembrar de conversas e soluções anteriores, permitindo que eles personalizem as respostas para usuários específicos ou apresentem soluções mais rapidamente com base no contexto prévio.

Acompanhe aqui como construir isso passo a passo. Se você se perder ou simplesmente quiser executar um exemplo finalizado, confira o repositório aqui.

O que é Mastra?

Mastra é um framework TypeScript de código aberto para a construção de agentes de IA com componentes intercambiáveis para raciocínio, memória e ferramentas. Seu recurso de recuperação semântica permite que os agentes se lembrem e recuperem interações passadas, armazenando mensagens como representações vetoriais em um banco de dados vetorial. Isso permite que os agentes mantenham o contexto e a continuidade da conversa a longo prazo. O Elasticsearch é um excelente armazenamento de vetores para habilitar esse recurso, pois oferece suporte a buscas vetoriais densas e eficientes. Quando a recuperação semântica é acionada, o agente extrai mensagens relevantes do passado para a janela de contexto do modelo, permitindo que o modelo use esse contexto recuperado como base para seu raciocínio e respostas.

O que você precisa para começar

• Node v18+

• Elasticsearch (versão 8.15 ou mais recente)

• Chave da API do Elasticsearch

• Chave da API OpenAI

Observação: você precisará disso porque a demonstração usa o provedor OpenAI, mas o Mastra é compatível com outros SDKs de IA e provedores de modelos da comunidade, então você pode facilmente trocá-lo dependendo da sua configuração.

Construindo um projeto Mastra

Usaremos a CLI integrada do Mastra para fornecer a estrutura básica do nosso projeto. Execute o comando:

Você receberá uma série de instruções, começando com:

1. Dê um nome ao seu projeto.

2. Podemos manter esta opção padrão; fique à vontade para deixar este campo em branco.

3. Para este projeto, usaremos um modelo fornecido pela OpenAI.

4. Selecione a opção “Ignorar por enquanto”, pois armazenaremos todas as nossas variáveis de ambiente em um arquivo `.env` que configuraremos em uma etapa posterior.

5. Também podemos ignorar esta opção.

Assim que a inicialização estiver concluída, podemos passar para a próxima etapa.

Instalando dependências

Em seguida, precisamos instalar algumas dependências:

• ai - Pacote Core AI SDK que fornece ferramentas para gerenciar modelos de IA, prompts e fluxos de trabalho em JavaScript/TypeScript. O Mastra é construído sobre o SDK de IA da Vercel, portanto, precisamos dessa dependência para permitir as interações do modelo com o seu agente.

• @ai-sdk/openai - Plugin que conecta o SDK de IA aos modelos da OpenAI (como GPT-4, GPT-4o, etc.), permitindo chamadas à API usando sua chave de API da OpenAI.

• @elastic/elasticsearch - Cliente oficial do Elasticsearch para Node.js, Utilizado para conectar-se ao seu Elastic Cloud ou cluster local para indexação, pesquisa e operações vetoriais.

• dotenv - Carrega variáveis de ambiente de um arquivo .env arquivo em process.env, permitindo que você insira credenciais com segurança, como chaves de API e endpoints do Elasticsearch.

Configurando variáveis de ambiente

Crie um arquivo .env no diretório raiz do seu projeto, caso ainda não exista um. Alternativamente, você pode copiar e renomear o exemplo .env que eu forneci no repositório. Neste arquivo, podemos adicionar as seguintes variáveis:

Isso conclui a configuração básica. A partir daqui, você já pode começar a construir e orquestrar agentes. Vamos dar um passo além e adicionar o Elasticsearch como camada de armazenamento e busca vetorial.

Adicionando o Elasticsearch como armazenamento vetorial.

Crie uma nova pasta chamada stores e, dentro dela, adicione este arquivo. Antes que a Mastra e a Elastic lancem uma integração oficial de armazenamento vetorial do Elasticsearch, Abhi Aiyer(CTO da Mastra) compartilhou esta classe protótipo inicial chamada ElasticVector. Em termos simples, ele conecta a abstração de memória do Mastra aos recursos de vetores densos do Elasticsearch, permitindo que os desenvolvedores utilizem o Elasticsearch como banco de dados de vetores para seus agentes.

Vamos analisar mais detalhadamente as partes importantes da integração:

Ingestão do cliente Elasticsearch

Esta seção define a classe ElasticVector e configura a conexão do cliente Elasticsearch com suporte para implantações padrão e sem servidor.

• ElasticVectorConfig extends ClientOptionsIsso cria uma nova interface de configuração que herda todas as opções do cliente Elasticsearch (como node, auth, requestTimeout) e adiciona nossas propriedades personalizadas. Isso significa que os usuários podem passar qualquer configuração válida do Elasticsearch juntamente com nossas opções específicas para ambientes sem servidor.

• extends MastraVectorIsso permite que ElasticVector herde da classe base MastraVector do Mastra, que é uma interface comum à qual todas as integrações de armazenamento vetorial estão em conformidade. Isso garante que o Elasticsearch se comporte como qualquer outro backend vetorial do Mastra da perspectiva do agente.

• private client: ClientEsta é uma propriedade privada que contém uma instância do cliente JavaScript do Elasticsearch. Isso permite que a classe se comunique diretamente com o seu cluster.

• isServerless e deploymentChecked: Essas propriedades funcionam em conjunto para detectar e armazenar em cache se estamos conectados a uma implantação do Elasticsearch sem servidor ou padrão. Essa detecção ocorre automaticamente no primeiro uso ou pode ser configurada explicitamente.

• constructor(config: ClientOptions): Este construtor recebe um objeto de configuração (contendo suas credenciais do Elasticsearch e configurações opcionais sem servidor) e o usa para inicializar o cliente na linha this.client = new Client(config).

• super()Isso chama o construtor base do Mastra, portanto, ele herda o registro de logs, os auxiliares de validação e outros recursos internos.

Neste ponto, Mastra sabe que existe uma nova loja de vetores chamada ElasticVector

Detecção do tipo de implantação

Antes de criar os índices, o adaptador detecta automaticamente se você está usando o Elasticsearch padrão ou o Elasticsearch Serverless. Isso é importante porque as implantações sem servidor não permitem a configuração manual de shards.

O que está acontecendo:

• Primeiro verifica se você definiu explicitamente isServerless na configuração (ignora a detecção automática).

• Chama a API info() do Elasticsearch para obter informações do cluster.

• Verifica o build_flavor field (implantações sem servidor retornam serverless)

• Se a opção de build não estiver disponível, a solução é verificar a descrição da versão.

• Armazena o resultado em cache para evitar chamadas repetidas à API.

• Se a detecção falhar, a implantação padrão será utilizada por padrão.

Exemplo de uso:

Criando o armazenamento de “memória” no Elasticsearch

A função abaixo configura um índice Elasticsearch para armazenar embeddings. Verifica se o índice já existe. Caso contrário, cria um com o mapeamento abaixo que contém um campo dense_vector para armazenar embeddings e métricas de similaridade personalizadas.

Algumas coisas a ter em conta:

• O parâmetro dimension representa o comprimento de cada vetor de incorporação, que depende do modelo de incorporação que você está usando. Em nosso caso, geraremos embeddings usando o modelo text-embedding-3-small da OpenAI, que produz vetores de tamanho 1536. Usaremos esse valor como padrão.

• A variável similarity usada no mapeamento abaixo é definida pela função auxiliar const similarity = this.mapMetricToSimilarity(metric), que recebe o valor do parâmetro metric e o converte em uma palavra-chave compatível com o Elasticsearch para a métrica de distância escolhida.

  • Por exemplo: Mastra usa termos gerais para similaridade de vetores como cosine, euclidean e dotproduct. Se passássemos a métrica euclidean diretamente para o mapeamento do Elasticsearch, ele geraria um erro porque o Elasticsearch espera que a palavra-chave l2_norm represente a distância euclidiana.

• Compatibilidade com ambientes sem servidor: o código omite automaticamente as configurações de shard e réplica para implantações sem servidor, pois estas são gerenciadas automaticamente pelo Elasticsearch Serverless.

Armazenar uma nova memória ou anotação após uma interação.

Esta função recebe novos embeddings gerados após cada interação, juntamente com os metadados, e os insere ou atualiza no índice usando a API bulk do Elastic. A API bulk agrupa várias operações de gravação em uma única solicitação; essa melhoria no desempenho de indexação garante que as atualizações permaneçam eficientes à medida que a memória do nosso agente continua a crescer.

Consultar vetores semelhantes para recuperação semântica

Essa função é o núcleo do recurso de recuperação semântica. O agente utiliza a busca vetorial para encontrar incorporações armazenadas semelhantes em nosso índice.

Por dentro do capô:

• Executa uma consulta kNN (k-vizinhos mais próximos) usando a API knn no Elasticsearch.

• Recupera os K vetores mais semelhantes ao vetor de consulta de entrada.

• Opcionalmente, aplica filtros de metadados para refinar os resultados (por exemplo, pesquisar apenas dentro de uma categoria ou intervalo de tempo específico).

• Retorna resultados estruturados, incluindo o ID do documento, a pontuação de similaridade e os metadados armazenados.

Criando o agente de conhecimento

Agora que vimos a conexão entre Mastra e Elasticsearch por meio da integração ElasticVector , vamos criar o próprio Agente de Conhecimento.

Dentro da pasta agents, crie um arquivo chamado knowledge-agent.ts. Podemos começar conectando nossas variáveis de ambiente e inicializando o cliente Elasticsearch.

Aqui, nós:

• Use dotenv para carregar nossas variáveis do nosso arquivo .env .

• Verifique se as credenciais do Elasticsearch estão sendo inseridas corretamente e, em seguida, poderemos estabelecer uma conexão bem-sucedida com o cliente.

• Passe o endpoint do Elasticsearch e a chave da API para o construtor ElasticVector para criar uma instância do nosso armazenamento de vetores que definimos anteriormente.

• Opcionalmente, especifique isServerless: true se estiver usando o Elasticsearch Serverless. Isso elimina a etapa de detecção automática e melhora o tempo de inicialização. Caso seja omitido, o adaptador detectará automaticamente o seu tipo de implantação na primeira utilização.

Em seguida, podemos definir o agente usando a classe Agent do Mastra.

Os campos que podemos definir são:

• name e instructions: Dê a ele uma identidade e uma função primária.

• modelEstamos usando o gpt-4o da OpenAI por meio do pacote @ai-sdk/openai .

• memory:

  • vector: Aponta para o nosso armazenamento Elasticsearch, de onde os embeddings são armazenados e recuperados.

  • embedderQual modelo usar para gerar embeddings?

  • semanticRecall As opções definem como funciona o recall:

    • topKQuantas mensagens semanticamente semelhantes devem ser recuperadas?

    • messageRange: Qual a extensão da conversa a ser incluída em cada interação?

    • scopeDefine o limite da memória.

Quase pronto. Basta adicionarmos esse agente recém-criado à nossa configuração do Mastra. No arquivo chamado index.ts, importe o agente de conhecimento e insira-o no campo agents .

Os outros campos incluem:

• storageEste é o repositório de dados interno do Mastra para histórico de execuções, métricas de observabilidade, pontuações e caches. Para obter mais informações sobre o sistema de armazenamento Mastra, visite aqui.

• loggerO Mastra utiliza o Pino, que é um registrador JSON estruturado e leve. Ele registra eventos como início e término de agentes, chamadas e resultados de ferramentas, erros e tempos de resposta do LLM.

• observabilityControla o rastreamento de IA e a visibilidade da execução de agentes. Ele rastreia:

  • Início/fim de cada etapa de raciocínio.

  • Qual modelo ou ferramenta foi utilizada?

  • Entradas e saídas.

  • Pontuações e avaliações

Testando o agente com o Mastra Studio

Parabéns! Se você chegou até aqui, está pronto para executar este agente e testar suas capacidades de recuperação semântica. Felizmente, o Mastra oferece uma interface de chat integrada, então não precisamos criar a nossa própria.

Para iniciar o servidor de desenvolvimento do Mastra, abra um terminal e execute o seguinte comando:

Após a inicialização e o empacotamento iniciais do servidor, você deverá receber um endereço para o Playground.

Cole este endereço no seu navegador e você será direcionado para o Mastra Studio.

Selecione a opção knowledgeAgent e comece a conversar.

Para um teste rápido para verificar se tudo está conectado corretamente, forneça algumas informações como: "A equipe anunciou que o desempenho de vendas em outubro aumentou 12%, impulsionado principalmente por renovações de contratos corporativos." O próximo passo é expandir o alcance aos clientes de médio porte.” Em seguida, inicie um novo bate-papo e faça uma pergunta como: "Em qual segmento de clientes dissemos que precisamos nos concentrar a seguir?" O agente de conhecimento deve ser capaz de recordar as informações que você lhe forneceu na primeira conversa. Você deverá ver uma resposta semelhante a esta:

Ao recebermos uma resposta como essa, significa que o agente armazenou com sucesso nossa mensagem anterior como embeddings no Elasticsearch e a recuperou posteriormente usando a busca vetorial.

Inspecionando o armazenamento de memória de longo prazo do agente.

Acesse a aba memory na configuração do seu agente no Mastra Studio. Isso permite que você veja o que seu agente aprendeu ao longo do tempo. Cada mensagem, resposta e interação que é incorporada e armazenada no Elasticsearch passa a fazer parte dessa memória de longo prazo. Você pode realizar buscas semânticas em interações passadas para encontrar rapidamente informações ou contextos que o agente aprendeu anteriormente. Este é essencialmente o mesmo mecanismo que o agente usa durante a recuperação semântica, mas aqui você pode inspecioná-lo diretamente. No exemplo abaixo, estamos pesquisando o termo "vendas" e obtendo como resultado todas as interações que incluíram algo relacionado a vendas.

Conclusão

Ao conectar o Mastra e o Elasticsearch, podemos fornecer memória aos nossos agentes, o que é uma camada fundamental na engenharia de contexto. Com a recuperação semântica, os agentes podem construir contexto ao longo do tempo, fundamentando suas respostas no que aprenderam. Isso significa interações mais precisas, confiáveis e naturais.

Essa integração inicial é apenas o ponto de partida. O mesmo padrão pode permitir que agentes de suporte se lembrem de chamados anteriores, bots internos recuperem documentação relevante ou assistentes de IA consigam recordar detalhes do cliente no meio da conversa. Também estamos trabalhando para uma integração oficial com o Mastra, tornando essa combinação ainda mais perfeita em um futuro próximo.

Estamos ansiosos para ver o que você vai construir em seguida. Experimente, explore o Mastra e seus recursos de memória e sinta-se à vontade para compartilhar suas descobertas com a comunidade.

Mas a verdadeira mágica acontece quando você consegue integrar essas ferramentas personalizadas e orientadas a dados aos ambientes onde você passa a maior parte do tempo. E se o agente do seu editor de código pudesse acessar com segurança a base de conhecimento privada da sua organização?

É aí que entra o Protocolo de Contexto do Modelo (MCP) . O Elastic Agent Builder é fornecido com um servidor MCP integrado que dá acesso às ferramentas da plataforma.

Por que usar o servidor Elastic Agent Builder MCP?

Os agentes de IA são incrivelmente poderosos, mas seu conhecimento geralmente se limita aos dados com os quais foram treinados e às informações que podem pesquisar ativamente na internet pública. Eles não conhecem os documentos de design internos da sua empresa, os manuais de implantação específicos da sua equipe ou a estrutura exclusiva dos logs de seus aplicativos.

O desafio é fornecer ao seu assistente de IA o contexto especializado de que ele precisa. Este é precisamente o problema que o MCP foi projetado para resolver. MCP é um padrão aberto que permite que um modelo ou agente de IA descubra e utilize ferramentas externas.

Para tornar isso possível, o Elastic Agent Builder expõe nativamente suas ferramentas personalizadas por meio de um servidor MCP integrado. Isso significa que você pode conectar facilmente qualquer cliente compatível com MCP, como Cursor, VS Code ou Claude Desktop, com as ferramentas especializadas e com reconhecimento de dados que você criou com o Elastic Agent Builder.

Quando usar MCP (e quando não usar)

O Elastic Agent Builder inclui diversos protocolos para suportar diferentes padrões de integração. Escolher a opção certa é fundamental para criar fluxos de trabalho de IA eficazes.

• Use o MCP para aprimorar seu agente de IA (como no Cursor ou no VS Code) com ferramentas especializadas. Trata-se da abordagem "traga suas próprias ferramentas", que aprimora o assistente que você já usa com acesso seguro aos seus dados privados. Somente as ferramentas são expostas através do servidor MCP — os agentes da Elastic são independentes disso.

• Utilize o protocolo A2A para permitir que seu Elastic Agent totalmente personalizado colabore com outros agentes autônomos (como no Gemini Enterprise do Google). Isso se aplica à delegação entre agentes, onde cada agente trabalha em conjunto para resolver um problema.

• Utilize as APIs do Agent Builder para obter controle programático completo ao criar um aplicativo personalizado do zero.

Para um desenvolvedor que busca respostas em sua documentação interna sem sair do seu IDE, o MCP é a solução ideal.

Exemplo: suas ferramentas personalizadas no Cursor com o servidor Agent Builder MCP

Vamos analisar um exemplo prático que eu uso diariamente. Primeiro, rastreei e indexei nossa documentação interna de engenharia em um índice Elasticsearch chamado elastic-dev-docs. Embora pudéssemos usar as ferramentas genéricas e integradas disponíveis no Agent Builder, criaremos nossa própria ferramenta personalizada para consultar essa base de conhecimento específica.

O motivo para construir uma ferramenta personalizada é simples: controle e precisão. Essa abordagem nos dá o poder de executar uma consulta semântica rápida diretamente em nosso índice elastic-dev-docs . Temos controle total sobre qual índice é o alvo e como os dados são obtidos.

Agora, veja como podemos usar essa base de conhecimento personalizada em um editor de código com inteligência artificial, como o Cursor.

Etapa 1: Crie uma ferramenta de base de conhecimento personalizada no Agent Builder.

Primeiro, crie uma nova ferramenta no Construtor de Agentes. Uma descrição clara e específica da ferramenta é importante porque é assim que qualquer agente de IA, seja o Elastic Agent interno ou uma ferramenta externa como o Cursor, conectado via MCP, descobre e seleciona a ferramenta adequada para a tarefa correta.

Uma descrição precisa deve ser explícita. Por exemplo: “Realiza uma busca semântica no índice elastic-dev-docs para encontrar documentação interna de engenharia, manuais de operação e procedimentos de lançamento.”

Com isso configurado, a ferramenta está preparada para realizar uma busca semântica em nosso índice específico. Uma vez salvo, fica imediatamente disponível para ser servido.

Antes de conectar o dispositivo ao mundo exterior, você pode testá-lo diretamente na interface do usuário. Basta clicar no botão Testar para preencher manualmente os parâmetros, simulando o que o LLM fará, e inspecionar os resultados para confirmar se tudo está funcionando corretamente.

Etapa 2: Conecte o Cursor ao servidor Elastic MCP

O Elastic Agent Builder expõe automaticamente todas as ferramentas disponíveis por meio de um endpoint MCP seguro. Você pode encontrar o URL exclusivo do seu servidor na interface de Ferramentas do Kibana.

Para conectar ao Cursor, basta adicionar este URL ao seu arquivo de configuração, juntamente com uma chave de API Elastic para autenticação (saiba como criar uma chave de API ES). Utilizamos uma chave de API para autorização, pois isso garante que as ferramentas sejam executadas somente com as permissões que você concedeu, respeitando todas as suas regras de controle de acesso.

A configuração MCP em ~/.cursor/mcp.json do Cursor se parece com isto:

Após salvar a configuração, você deverá ver a ferramenta de servidor Elastic Agent Builder MCP disponível no Cursor.

Passo 3: pergunte à vontade!

Com a conexão estabelecida, os agentes do Cursor agora podem invocar suas ferramentas personalizadas para responder às suas perguntas ou orientar o processo de geração de código.

Vamos fazer uma pergunta específica:

“Consulte os passos para liberar o serviço de rastreamento na documentação interna de engenharia da organização do Elasticsearch”

Nos bastidores, a magia acontece:

1. O agente Cursor decide a melhor forma de responder à sua pergunta e, em seguida, decide ligar para o engineering_documentation_internal_search

2. Ela invoca a ferramenta com uma consulta em linguagem natural.

3. A ferramenta executa uma busca semântica no índice elastic-dev-docs e retorna os procedimentos mais relevantes e atualizados.

Obtemos uma resposta precisa e confiável com base em nossa documentação interna, tudo isso sem precisar sair do editor de código. A experiência é perfeita e impactante.

Sua vez de construir

Agora você viu como usar o servidor MCP integrado no Elastic Agent Builder para estender seus assistentes de IA com acesso seguro aos seus dados privados. Fundamentar os modelos em suas próprias informações é fundamental para torná-los verdadeiramente úteis.

Recapitulando, abordamos as etapas principais:

• Escolher o protocolo certo para as suas necessidades (MCP).

• Criação de uma ferramenta de base de conhecimento personalizada.

• Conectar essa ferramenta a um assistente de IDE como o Cursor.

Seus agentes e ferramentas não precisam mais estar desconectados de seu contexto mais valioso. Esperamos que este guia ajude você a criar fluxos de trabalho mais eficazes e orientados a dados. Boa construção!

No Elastic Stack, existem muitos aplicativos agentivos baseados em LLM, como o futuro Elastic AI Agent no Agent Builder (atualmente em versão de pré-visualização técnica) e o Attack Discovery (disponível para o público geral nas versões 8.18 e 9.0+), com mais em desenvolvimento. Durante o desenvolvimento, e mesmo após a implementação, é importante responder a estas perguntas:

• Como podemos estimar a qualidade das respostas dessas aplicações de IA?

• Se fizermos uma alteração, como podemos garantir que ela seja realmente uma melhoria e não cause deterioração na experiência do usuário?

• Como podemos testar esses resultados de forma fácil e repetível?

Diferentemente dos testes de software tradicionais, a avaliação de aplicações de IA generativa envolve métodos estatísticos, análises qualitativas minuciosas e uma compreensão profunda dos objetivos do usuário.

Este artigo detalha o processo que a equipe de desenvolvimento da Elastic utiliza para realizar avaliações, garantir a qualidade das alterações antes da implantação e monitorar o desempenho do sistema. Nosso objetivo é garantir que cada mudança seja respaldada por evidências, resultando em resultados confiáveis e verificáveis. Parte desse processo está integrada diretamente ao Kibana, refletindo nosso compromisso com a transparência como parte de nossa filosofia de código aberto. Ao compartilhar abertamente partes de nossos dados e métricas de avaliação, buscamos fomentar a confiança da comunidade e fornecer uma estrutura clara para qualquer pessoa que desenvolva agentes de IA ou utilize nossos produtos.

Exemplos de produtos

Os métodos utilizados neste documento serviram de base para a forma como iteramos e aprimoramos soluções como o Attack Discovery e o Elastic AI Agent. Uma breve introdução aos dois, respectivamente:

Descoberta de ataques da Elastic Security

A descoberta de ataques utiliza LLMs para identificar e resumir sequências de ataques no Elastic. Com base nos alertas do Elastic Security em um determinado período (padrão de 24 horas), o fluxo de trabalho automatizado do Attack Discovery identificará automaticamente se ocorreram ataques, além de informações importantes, como quais hosts ou usuários foram comprometidos e quais alertas contribuíram para essa conclusão.

O objetivo é que a solução baseada em LLM produza um resultado pelo menos tão bom quanto o de um ser humano.

Agente de IA Elástico

O Elastic Agent Builder é a nossa nova plataforma para criar agentes de IA sensíveis ao contexto que aproveitam todos os nossos recursos de busca. Ele vem com o Elastic AI Agent, um agente pré-construído de uso geral, projetado para ajudar os usuários a entender e obter respostas a partir de seus dados por meio de interação conversacional.

O agente consegue isso identificando automaticamente informações relevantes no Elasticsearch ou em bases de conhecimento conectadas e utilizando um conjunto de ferramentas pré-construídas para interagir com elas. Isso permite que o Elastic AI Agent responda a uma ampla gama de consultas de usuários, desde perguntas e respostas simples sobre um único documento até solicitações complexas que exigem agregação e buscas de uma ou várias etapas em diversos índices.

Medindo melhorias por meio de experimentos

No contexto de agentes de IA, um experimento é uma mudança estruturada e testável no sistema, projetada para melhorar o desempenho em dimensões bem definidas (por exemplo, utilidade, correção, latência). O objetivo é responder de forma definitiva: "Se incorporarmos essa alteração, podemos garantir que ela representa uma melhoria real e não prejudicará a experiência do usuário?"

A maioria dos experimentos que realizamos geralmente inclui:

• Uma hipótese: uma afirmação específica e falseável. Exemplo: “Adicionar acesso a uma ferramenta de descoberta de ataques melhora a precisão das consultas relacionadas à segurança.”

• Critérios de sucesso: Limiares claros que definem o que significa "sucesso". Exemplo: “Melhoria de 5% na pontuação de correção no conjunto de dados de segurança, sem degradação em outros locais.”

• Plano de avaliação: Como medimos o sucesso (métricas, conjuntos de dados, método de comparação)

Um experimento bem-sucedido é um processo sistemático de investigação. Toda alteração, desde um pequeno ajuste de um prompt até uma grande mudança arquitetônica, segue estes sete passos para garantir que os resultados sejam significativos e acionáveis:

• Etapa 1: Identificar o problema

• Etapa 2: Definir métricas

• Etapa 3: Formule uma hipótese clara

• Etapa 4: Preparar o conjunto de dados de avaliação

• Etapa 5: Execute o experimento

• Etapa 6: Analisar resultados + iterar

• Etapa 7: Tome uma decisão e documente-a.

Um exemplo dessas etapas é ilustrado na Figura 1. As subseções a seguir explicarão cada etapa, e detalharemos os aspectos técnicos de cada etapa em documentos futuros.

Passo a passo com exemplos reais do Elastic

Etapa 1: Identificar o problema

Qual é exatamente o problema que essa mudança visa resolver?

Exemplo de detecção de ataques: os resumos são ocasionalmente incompletos ou atividades benignas são erroneamente sinalizadas como ataques (falsos positivos).

Exemplo de agente de IA elástica: a seleção de ferramentas do agente, especialmente para consultas analíticas, é subótima e inconsistente, muitas vezes levando à escolha da ferramenta errada. Isso, por sua vez, aumenta os custos dos tokens e a latência.

Etapa 2: Definir métricas

Torne o problema mensurável, para que possamos comparar uma mudança com o estado atual.

As métricas comuns incluem precisão e revocação, similaridade semântica, factualidade, e assim por diante. Dependendo do caso de uso, utilizamos verificações de código para calcular as métricas, como a correspondência de IDs de alerta ou URLs recuperados corretamente, ou técnicas como LLM-as-judge para respostas mais livres.

Abaixo estão alguns exemplos (lista não exaustiva) de métricas usadas nos experimentos:

Descoberta de ataques

Métrica

Descrição

Precisão e memorização

Compare os IDs de alerta entre as saídas reais e esperadas para medir a precisão da detecção.

Semelhança

Utilize o BERTScore para comparar a similaridade semântica do texto de resposta.

Factualidade

Os principais indicadores de comprometimento (IOCs) estão presentes? As táticas MITRE (taxonomia de ataques do setor) estão corretamente representadas?

Consistência da cadeia de ataque

Compare o número de descobertas para verificar se houve superestimação ou subestimação da notificação do ataque.

Agente de IA Elástico

Métrica

Descrição

Precisão e memorização

Comparar os documentos/informações recuperados pelo agente para responder a uma consulta do usuário com as informações ou documentos realmente necessários para responder à consulta, a fim de medir a precisão da recuperação de informações.

Factualidade

Os principais fatos necessários para responder à consulta do usuário estão presentes? Os fatos estão na ordem correta para questões processuais?

Relevância da resposta

A resposta contém informações periféricas ou não relacionadas à consulta do usuário?

Completude da resposta

A resposta atende a todas as partes da consulta do usuário? A resposta contém todas as informações presentes na verdade fundamental?

Validação ES|QL

O código ES|QL gerado está sintaticamente correto? É funcionalmente idêntico ao ES|QL original?

Etapa 3: Formule uma hipótese clara

Estabeleça critérios de sucesso claros usando o problema e as métricas definidas acima.

Exemplo de agente de IA elástico:

1. Implementar alterações nas descrições das ferramentas relevance_search e nl_search para definir claramente suas funções e casos de uso específicos.

2. Prevemos que melhoraremos a precisão da invocação de nossa ferramenta em 25%.

3. Verificaremos se isso representa um saldo positivo, garantindo que não haja impacto negativo em outras métricas, por exemplo... factualidade e completude.

4. Acreditamos que isso funcionará porque descrições precisas das ferramentas ajudarão o agente a selecionar e aplicar com mais exatidão a ferramenta de busca mais adequada para diferentes tipos de consulta, reduzindo o uso incorreto e melhorando a eficácia geral da busca.

Etapa 4: Preparar o conjunto de dados de avaliação

Para medir o desempenho do sistema, utilizamos conjuntos de dados que capturam cenários do mundo real.

Dependendo do tipo de avaliação que estivermos realizando, podemos precisar de diferentes formatos de dados, como dados brutos inseridos em um LLM (por exemplo, cenários de ataque para descoberta de ataques) e resultados esperados. Se o aplicativo for um chatbot, as entradas podem ser consultas do usuário e as saídas podem ser respostas corretas do chatbot, links corretos que ele deveria ter recuperado e assim por diante.

Exemplo de descoberta de ataques:

10 novos cenários de ataque

8 episódios de Oh My Malware (ohmymalware.com)

4 cenários de múltiplos ataques (criados pela combinação de ataques nas duas primeiras categorias)

3 cenários benignos

Exemplo de conjunto de dados para avaliação de agentes de IA elástica (Link para o conjunto de dados do Kibana):

14 Índices que utilizam conjuntos de dados de código aberto para simular múltiplas fontes em KB.

5 tipos de consulta (analítica, recuperação de texto, híbrida…)

7 tipos de intenção de consulta (procedimental, factual - classificação, investigativa; …)

Etapa 5: Execute o experimento

Execute o experimento gerando respostas tanto do agente existente quanto da versão modificada em relação ao conjunto de dados de avaliação. Calcule métricas como a veracidade factual (ver passo 2).

Combinamos diversas avaliações com base nas métricas exigidas na Etapa 2:

• Avaliação baseada em regras (por exemplo, (Use Python/TypeScript para verificar se o arquivo .json é válido)

• LLM como juiz (consultar um LLM separado para verificar se uma resposta é factualmente consistente com um documento original)

• Revisão com intervenção humana para verificações de qualidade e nuances.

Etapa 6: Analisar resultados + iterar

Agora que temos as métricas, vamos analisar os resultados. Mesmo que os resultados atendam aos critérios de sucesso definidos na etapa 3, ainda faremos uma revisão humana antes de incorporar a alteração à produção; se os resultados não atenderem aos critérios, iteraremos e corrigiremos os problemas e, em seguida, executaremos as avaliações na nova alteração.

Prevemos que serão necessárias algumas iterações para encontrarmos a melhor alteração antes de a consolidarmos. Assim como é feito executar testes de software locais antes de enviar uma alteração, as avaliações offline podem ser executadas com alterações locais ou com várias alterações propostas. Automatizar o salvamento de resultados experimentais, pontuações compostas e visualizações é útil para agilizar a análise.

Etapa 7: Tome uma decisão e documente-a.

Com base em uma estrutura de decisão e critérios de aceitação, decida sobre a incorporação da alteração e documente o experimento. A tomada de decisões é multifacetada e pode considerar fatores que vão além do conjunto de dados de avaliação, como verificar cenários de regressão em outros conjuntos de dados ou ponderar o custo-benefício de uma mudança proposta.

Exemplo: Após testar e comparar algumas iterações, escolha a alteração com a melhor pontuação para enviar aos gerentes de produto e outras partes interessadas relevantes para aprovação. Anexe os resultados das etapas anteriores para auxiliar na tomada de decisão. Para mais exemplos sobre a descoberta de ataques, consulte Nos bastidores dos recursos de IA generativa do Elastic Security.

Conclusão

Neste blog, descrevemos o processo completo de um fluxo de trabalho de experimento, ilustrando como avaliamos e testamos as alterações em um sistema de agentes antes de disponibilizá-las aos usuários da Elastic. Também fornecemos alguns exemplos de como aprimorar fluxos de trabalho baseados em agentes no Elastic. Em publicações subsequentes no blog, detalharemos diferentes etapas, como criar um bom conjunto de dados, projetar métricas confiáveis e tomar decisões quando várias métricas estão envolvidas.

Mas e se você quiser usar seus agentes personalizados com os aplicativos e ferramentas de produtividade que você já utiliza?

É aí que entra o protocolo Agente-para-Agente (A2A) . A2A é um padrão aberto de interoperabilidade, permitindo que agentes de diferentes plataformas se comuniquem e colaborem. E nós o integramos diretamente ao Elastic Agent Builder.

Hoje, vamos mostrar como pegar um agente personalizado que você criou e expô-lo a outros serviços, especificamente, ao Gemini Enterprise (antigo Agentspace).

O poder dos padrões abertos: por que a abordagem A2A é importante

Na postagem do blog "Seu primeiro Elastic Agent", mostramos como criar agentes personalizados, como um agente de Assistente Financeiro com acesso seguro aos seus dados de mercado. Mas seu valor é limitado se você não puder disponibilizar suas informações em outros ambientes, como o Gemini Enterprise, sem refazer todo o seu trabalho.

Esse desafio de interoperabilidade é o que impede o avanço da IA ativa. Os agentes precisam de uma linguagem comum para se comunicarem entre plataformas, e essa é precisamente a função do protocolo A2A. Ela fornece uma camada de comunicação padrão que não só permite a interação direta com o agente, como também abre caminho para um futuro em que agentes especializados em toda a organização possam colaborar e compartilhar informações.

Para tornar isso possível, o Elastic Agent Builder oferece suporte nativo ao protocolo A2A por meio de dois endpoints padrão para todos os seus agentes:

1. O endpoint do cartão do agente (GET {your-kibana-url}/api/agent_builder/a2a/{agentId}.json) - Este funciona como o cartão de visita personalizado do seu agente. Ele fornece metadados sobre seu agente (nome, descrição, capacidades, etc.) para qualquer serviço compatível com A2A.

2. O ponto final do protocolo A2A (POST {your-kibana-url}/api/agent_builder/a2a/{agentId}) - Este é o canal de comunicação. Outros agentes enviam suas solicitações para cá, e seu agente as processa e retorna uma resposta, tudo seguindo a especificação do protocolo A2A.

Teste seu agente com o inspetor A2A.

Antes de conectar nosso agente a um sistema de produção, é bom verificar se a comunicação está funcionando corretamente. A maneira mais fácil de fazer isso é com o A2A Inspector, uma ferramenta projetada especificamente para testar e depurar integrações A2A.

Colocar o inspetor em funcionamento é simples. Você pode clonar o repositório a2a-inspector e seguir as instruções do arquivo README para executar o aplicativo. Uma vez iniciado, o UI está disponível por padrão em http://localhost:5001/.

Para conectar o A2A Inspector ao seu agente, você precisará fornecer duas informações essenciais:

• URL do Cartão do Agente: Este é o endpoint que descreve o seu agente. Para o agente Assistente Financeiro da nossa postagem anterior, este URL seria {your-kibana-url}/api/agent_builder/a2a/financial_assistant.json.

• Cabeçalho de autenticação: Usaremos uma chave de API padrão para autenticação.

Após inserir esses detalhes na interface do inspetor, você poderá se conectar e começar a conversar com seu agente imediatamente.

Essa validação simples nos dá a certeza de que nosso agente está configurado corretamente e pronto para a próxima etapa.

Entre ao vivo! Seu agente personalizado na Gemini Enterprise

Agora vem a parte emocionante: dar vida ao nosso agente de consultoria financeira personalizado dentro do Gemini Enterprise (antigo Agentspace). Essa integração é viabilizada pelo Elastic AI Agent, que está disponível no Google Cloud Marketplace.

Uma vez conectado, o Gemini Enterprise usa o protocolo A2A para se comunicar diretamente com seu agente. É aqui que o verdadeiro poder da interoperabilidade se destaca: os usuários agora podem acessar insights profundos e baseados em dados do seu agente Elasticsearch personalizado sem precisar sair do ambiente familiar. Você pode ver seu agente elástico personalizado na lista de agentes:

Imagine um usuário do Gemini Enterprise perguntando:

"Estou preocupado com o sentimento do mercado. Você pode me mostrar quais dos nossos clientes estão mais vulneráveis a notícias negativas?"

Nos bastidores, o Gemini Enterprise encaminha essa consulta por meio do protocolo A2A para o seu Elastic Agent personalizado. Seu agente então utiliza suas ferramentas especializadas para consultar seus dados, formular uma resposta e enviá-la de volta. Para o usuário final, a experiência é perfeita.

E não para por aqui! A resposta obtida com o agente elástico agora pode ser usada como contexto para suas próximas perguntas, que podem acionar um agente especializado diferente (por exemplo, seu agente de plataforma de investimentos para ajustar a exposição a empresas listadas). Tudo isso sem sair da sua barra de pesquisa.

Com seus agentes Elastic implantados no Gemini Enterprise com A2A, você pode unificar acesso, orquestração e fluxos de trabalho, eliminando atritos entre IA, pesquisa e sistemas corporativos, oferecendo uma interface de usuário única onde os usuários interagem com seus dados e ferramentas — tudo em contexto. Para os usuários, isso significa menos troca de ferramentas e assistentes de IA mais intuitivos e capazes. Para as organizações, isso significa governança coerente, escalabilidade e interoperabilidade integradas.

Sua vez de construir

Agora você tem as ferramentas para disponibilizar seus Agentes Elásticos em qualquer lugar. Ao aproveitar o protocolo aberto A2A, você pode ampliar o alcance de seus agentes personalizados e orientados a dados.

Neste post, apresentamos os principais passos:

• Exponha seu agente por meio do cartão de agente A2A e dos endpoints do protocolo.

• Testando a conexão com o A2A Inspector.

• Integrar seu agente em tempo real a um serviço externo como o Gemini Enterprise do Google.

Seus agentes não precisam mais ficar isolados. Estamos ansiosos para ver os sistemas poderosos e interconectados que vocês criarão. Boa construção!

A maneira mais fácil de começar é com sua avaliação gratuita do Elastic Cloud no Google Cloud Marketplace.

Leia o artigo "Building AI Agentic Workflows with Elasticsearch" para obter mais informações sobre o panorama geral desse projeto, ou "Your First Elastic Agent: From a Single Query to a AI-Powered Chat" para uma introdução mais prática.

Neste blog, porém, vamos nos aprofundar um pouco em uma das primeiras coisas que acontecem quando você começa a conversar e apresentar algumas das melhorias recentes que implementamos.

O que está acontecendo aqui?

Ao interagir com seus dados do Elasticsearch, nosso agente de IA padrão segue este fluxo padrão:

1. Examine o prompt.

2. Identifique qual índice provavelmente contém as respostas para essa pergunta.

3. Gere uma consulta para esse índice, com base no prompt.

4. Pesquise esse índice com essa consulta.

5. Sintetize os resultados.

6. Os resultados respondem à pergunta? Em caso afirmativo, responda. Caso contrário, repita, mas tente algo diferente.

Isso não deve parecer muito inovador - é apenas Geração Aumentada por Recuperação (RAG). E, como seria de esperar, a qualidade das suas respostas depende muito da relevância dos resultados da sua pesquisa inicial. Enquanto trabalhávamos para melhorar a qualidade de nossas respostas, prestamos muita atenção às consultas que gerávamos na etapa 3 e executávamos na etapa 4. E percebemos um padrão interessante.

Muitas vezes, quando nossas primeiras respostas eram "ruins", não era porque tínhamos executado uma consulta ruim. Isso aconteceu porque tínhamos escolhido o índice errado para consultar. Os passos 3 e 4 geralmente não eram o nosso problema - era o passo 2.

O que estávamos fazendo?

Nossa implementação inicial foi simples. Tínhamos criado uma ferramenta (chamada index_explorer) que efetivamente faria um _cat/indices para listar todos os índices disponíveis para nós e, em seguida, pediria ao LLM para identificar qual desses índices era a melhor correspondência para a mensagem/pergunta/solicitação do usuário. Você pode ver a implementação original aqui.

Quão bem isso estava funcionando? Não tínhamos certeza! Tínhamos exemplos claros de situações em que não estava funcionando bem, mas nosso primeiro desafio real foi quantificar nossa situação atual.

Estabelecer uma linha de base

Tudo começa com dados.

O que precisávamos era de um Conjunto de Dados Ideal para medir a eficácia de uma ferramenta na seleção do índice correto, dada uma solicitação do usuário e um conjunto preexistente de índices. E nós não tínhamos um conjunto de dados desse tipo disponível. Então, nós geramos um.

Reconhecimento: Sabemos que isso não é a "melhor prática". Mas, às vezes, é melhor seguir em frente do que ficar discutindo detalhes irrelevantes. Progresso, SIMPLES Perfeição.

Geramos índices iniciais para vários domínios diferentes usando este prompt. Em seguida, para cada domínio gerado, geramos mais alguns índices usando esse prompt (o objetivo aqui é semear confusão para o LLM com negativos difíceis e exemplos difíceis de classificar). Em seguida, editamos manualmente cada índice gerado e suas respectivas descrições. Por fim, geramos consultas de teste usando esse prompt. Isso nos deixou com dados de exemplo como:

e casos de teste como:

Construindo um arnês de teste

A partir daqui, o processo foi muito simples. Crie uma ferramenta que possa:

1. Crie um ambiente totalmente novo com um cluster Elasticsearch de destino.

2. Crie todos os índices definidos no conjunto de dados de destino.

3. Para cada cenário de teste, execute a ferramenta index_explorer (felizmente, temos uma API Execute Tool).

4. Compare o índice resultante com o índice esperado e registre o resultado.

5. Após concluir todos os cenários de teste, tabule os resultados.

A pesquisa indica…

Os resultados iniciais foram, previsivelmente, medíocres.

No geral, a precisão na identificação do índice correto foi de 77,14%. E isso no cenário "ideal", onde todos os índices têm nomes bons e semanticamente significativos. Qualquer pessoa que já tenha executado um `PUT test2/_doc/foo {...}` sabe que seus índices nem sempre têm nomes significativos.

Portanto, temos uma base de referência, e ela mostra que há muito espaço para melhorias. Chegou a hora de fazer ciência! 🧪

Experimentação

Hipótese 1: Os mapeamentos ajudarão

O objetivo aqui é identificar um índice que contenha dados relevantes para a pergunta original. E a parte de um índice que melhor descreve os dados que ele contém são os mapeamentos do índice. Mesmo sem obter nenhuma amostra do conteúdo do índice, saber que o índice possui um campo de preço do tipo double implica que os dados representam algo que está à venda. Um campo de autor do tipo texto implica alguns dados linguísticos não estruturados. A combinação dos dois pode sugerir que os dados são livros/histórias/poemas. Podemos obter muitas pistas semânticas apenas conhecendo as propriedades de um índice. Então, em uma branch local, eu ajustei nosso arquivo `.index_explorer`. Ferramenta para enviar os mapeamentos completos de um índice (juntamente com seu nome) ao LLM para que este tome uma decisão.

O resultado (dos registros do Kibana):

Os autores originais da ferramenta já haviam previsto isso. Embora o mapeamento de um índice seja uma mina de ouro de informações, ele também é um bloco JSON bastante extenso. E em um cenário realista onde você está comparando inúmeros índices (nosso conjunto de dados de avaliação define 20), esses blocos JSON se acumulam. Assim, queremos fornecer ao LLM mais contexto para sua decisão, não apenas os nomes dos índices de todas as opções, mas também os mapeamentos completos de cada uma.

Hipótese 2: Mapeamentos “achatados” (listas de campos) como solução de compromisso.

Partimos do pressuposto de que os criadores de índices usarão nomes de índice semanticamente significativos. E se estendermos essa suposição também aos nomes dos campos? Nosso experimento anterior falhou porque o mapeamento de JSON inclui MUITOS metadados e código repetitivo desnecessários.

O bloco acima, por exemplo, tem 236 caracteres e define apenas um único campo em um mapeamento do Elasticsearch. Enquanto a string “description_text” possui apenas 16 caracteres. Isso representa um aumento de quase 15 vezes na contagem de caracteres, sem uma melhoria semântica significativa na descrição do que esse campo implica sobre os dados disponíveis. E se buscássemos os mapeamentos para todos os índices, mas antes de enviá-los para o LLM, os "aplanássemos" em uma lista contendo apenas os nomes de seus campos?

Nós experimentamos.

Isso é ótimo! Melhorias em todos os aspectos. Mas será que poderíamos fazer melhor?

Hipótese 3: Descrições no mapeamento _meta

Se apenas os nomes dos campos, sem nenhum contexto adicional, causaram um salto tão grande, presumivelmente adicionar um contexto substancial seria ainda melhor! Não é necessariamente convencional que cada índice tenha uma descrição associada, mas é possível adicionar metadados de qualquer tipo ao objeto _meta do mapeamento. Retornamos aos índices gerados e adicionamos descrições para cada índice em nosso conjunto de dados. Contanto que as descrições não sejam excessivamente longas, elas devem usar menos tokens do que o mapeamento completo e fornecer informações significativamente melhores sobre quais dados estão incluídos no índice. Nosso experimento validou essa hipótese.

Uma pequena melhoria, e agora temos mais de 90% de precisão em todos os aspectos.

Hipótese 4: O todo é maior que a soma das partes.

Os nomes dos campos aumentaram nossos resultados. As descrições aumentaram nossos resultados. Portanto, utilizar tanto as descrições quanto os nomes dos campos deve apresentar resultados ainda melhores, certo?

Os dados indicaram "não" (nenhuma mudança em relação ao experimento anterior). A principal teoria era que, como as descrições foram geradas a partir dos campos/mapeamentos do índice, não havia informações suficientes entre esses dois contextos para adicionar algo "novo" ao combiná-los. Além disso, a carga útil que estamos enviando para nossos 20 índices de teste está ficando bastante grande. A linha de raciocínio que seguimos até agora não é escalável. Na verdade, há bons motivos para acreditar que nenhum dos nossos experimentos até agora funcionaria em clusters Elasticsearch, onde existem centenas ou milhares de índices para escolher. Qualquer abordagem que aumente linearmente o tamanho da mensagem enviada ao LLM à medida que o número total de índices aumenta provavelmente não será uma estratégia generalizável.

O que realmente precisamos é de uma abordagem que nos ajude a reduzir um grande número de candidatos apenas às opções mais relevantes…

O que temos aqui é um problema de busca.

Hipótese 5: Seleção via busca semântica

Se o nome de um índice tiver significado semântico, ele poderá ser armazenado como um vetor e pesquisado semanticamente.

Se os nomes dos campos de um índice tiverem significado semântico, eles podem ser armazenados como vetores e pesquisados semanticamente.

Se um índice possui uma descrição com significado semântico, ele também pode ser armazenado como um vetor e pesquisado semanticamente.

Atualmente, os índices do Elasticsearch não tornam nenhuma dessas informações pesquisável (talvez devêssemos!), mas foi bastante trivial improvisar algo que pudesse contornar essa lacuna. Utilizando a estrutura de conectores da Elastic, criei um conector que gera um documento para cada índice em um cluster. Os documentos resultantes seriam algo como:

Enviei esses documentos para um novo índice onde defini manualmente o mapeamento da seguinte forma:

Isso cria um único campo semantic_content, onde todos os outros campos com significado semântico são divididos em blocos e indexados. A busca neste índice torna-se trivial, bastando:

A ferramenta index_explorer modificada agora é muito mais rápida, pois não precisa fazer uma solicitação a um LLM, mas pode solicitar um único embedding para a consulta fornecida e executar uma operação de busca vetorial eficiente. Considerando o resultado mais relevante como nosso índice selecionado, obtivemos os seguintes resultados:

Essa abordagem é escalável. Essa abordagem é eficiente. Mas essa abordagem é pouco melhor do que a nossa abordagem inicial. Isso não é surpreendente; a abordagem de busca aqui é incrivelmente ingênua. Não há nuances. Não há reconhecimento de que o nome e a descrição de um índice devam ter mais peso do que um nome de campo arbitrário que o índice contenha. Não há como priorizar correspondências lexicais exatas em detrimento de correspondências sinônimas. No entanto, construir uma consulta altamente detalhada exigiria muitas suposições sobre os dados disponíveis. Até agora, já fizemos algumas suposições importantes sobre o significado semântico dos nomes de índices e campos, mas precisaríamos ir um passo além e começar a supor o quanto de significado eles têm e como se relacionam entre si. Sem fazer isso, provavelmente não conseguiremos identificar com segurança a melhor correspondência como nosso resultado principal, mas podemos afirmar com mais certeza que a melhor correspondência está em algum lugar entre os N melhores resultados. Precisamos de algo que possa consumir informações semânticas no contexto em que existem, comparando-as com outra entidade que pode se representar de uma maneira semanticamente distinta, e fazendo um julgamento entre elas. Como um mestrado em Direito.

Hipótese 6: Redução do conjunto de candidatos

Houve vários outros experimentos que vou abordar superficialmente, mas o principal avanço foi abandonar a ideia de escolher a melhor correspondência puramente com base em uma busca semântica e, em vez disso, usar a busca semântica como um filtro para eliminar índices irrelevantes da análise do LLM. Combinamos os algoritmos Linear Retrievers, Hybrid Search com RRF e semantic_text em nossa busca, limitando os resultados aos 5 índices de correspondência principais.

Em seguida, para cada correspondência, adicionamos o nome do índice, a descrição e os nomes dos campos a uma mensagem para o LLM. Os resultados foram fantásticos:

A maior precisão obtida em qualquer experimento até hoje! E como essa abordagem não aumenta o tamanho da mensagem proporcionalmente ao número total de índices, ela é muito mais escalável.

Resultados

O primeiro resultado claro foi que nossa linha de base pode ser melhorada. Isso parece óbvio em retrospectiva, mas antes do início da experimentação, houve uma discussão séria sobre se deveríamos abandonar completamente nossa ferramenta index_explorer e confiar na configuração explícita do usuário para limitar o espaço de busca. Embora essa ainda seja uma opção viável e válida, esta pesquisa mostra que existem caminhos promissores para automatizar a seleção de índices quando essas informações fornecidas pelo usuário não estão disponíveis.

A próxima conclusão clara foi que simplesmente adicionar mais caracteres descritivos ao problema tem resultados cada vez menores. Antes desta pesquisa, estávamos debatendo se deveríamos investir na expansão da capacidade do Elasticsearch para armazenar metadados em nível de campo. Atualmente, esses valores meta são limitados a 50 caracteres, e havia uma suposição de que precisaríamos aumentar esse valor para podermos obter uma compreensão semântica de nossos campos. Claramente, esse não é o caso, e o LLM parece funcionar muito bem apenas com os nomes das áreas de estudo. Poderemos investigar isso mais a fundo posteriormente, mas já não parece urgente.

Por outro lado, isso forneceu evidências claras da importância de se ter metadados de índice "pesquisáveis". Para esses experimentos, nós hackeamos um índice de índices. Mas isso é algo que poderíamos investigar, integrando diretamente ao Elasticsearch, criando APIs para gerenciar ou, pelo menos, estabelecendo uma convenção a respeito. Estaremos avaliando nossas opções e discutindo internamente, então fiquem atentos.

Finalmente, esse esforço confirmou o valor de dedicarmos tempo para experimentar e tomar decisões baseadas em dados. Na verdade, isso nos ajudou a reafirmar que nosso produto Agent Builder precisará de recursos robustos de avaliação integrados. Se precisarmos construir toda uma estrutura de testes apenas para uma ferramenta que seleciona índices, nossos clientes certamente precisarão de maneiras de avaliar qualitativamente suas ferramentas personalizadas à medida que fazem ajustes iterativos.

Estou ansioso para ver o que vamos construir, e espero que você também esteja!

Imagine um gerente financeiro que precisa se atualizar antes de uma reunião com um cliente. Em vez de vasculhar manualmente os feeds de notícias e comparar painéis de portfólio, agora eles podem simplesmente fazer uma pergunta direta ao seu agente personalizado. Essa é a vantagem de uma abordagem que prioriza o bate-papo. O gestor tem acesso direto e conversacional aos seus dados, podendo fazer perguntas como: "Quais são as últimas notícias sobre a ACME Corp e como isso afeta os investimentos do meu cliente?" e obtendo uma resposta sintetizada e especializada em segundos.

Embora estejamos criando um especialista financeiro hoje, as aplicações são tão variadas quanto seus dados. O mesmo poder pode criar um analista de cibersegurança para procurar ameaças, um engenheiro de confiabilidade de sites para diagnosticar uma interrupção ou um gerente de marketing para otimizar uma campanha. Independentemente da área, a missão principal é a mesma: transformar seus dados em um especialista com quem você possa conversar.

Etapa 0: Nosso conjunto de dados

Nosso conjunto de dados hoje é um conjunto de dados sintético baseado em finanças, composto por contas financeiras, posições de ativos, notícias e relatórios financeiros. Embora sintética, ela replica uma versão simplificada de um conjunto de dados financeiro real.

financial_accountsPortfólios de clientes com perfis de risco

financial_holdingsPosições em ações/ETFs/títulos com histórico de compras

financial_asset_detailsDetalhes sobre a ação/ETF/título

financial_newsArtigos de mercado gerados por IA com análise de sentimento

financial_reportsResultados da empresa e notas dos analistas

Você pode carregar este conjunto de dados por conta própria seguindo as instruções do notebook que acompanha este documento, localizado aqui.

Etapa 1: A Base — Sua Lógica de Negócios em ES|QL

Toda habilidade de IA começa com uma base lógica sólida. Para o nosso agente de Gestão Financeira, precisamos ensiná-lo a responder a uma pergunta comum: "Estou preocupado com o sentimento do mercado." Você pode me mostrar quais dos nossos clientes correm maior risco em caso de más notícias? Essa questão vai além de uma simples pesquisa. Isso exige que correlacionemos o sentimento do mercado com as carteiras dos clientes.

Precisamos encontrar os ativos mencionados em artigos negativos, identificar todos os clientes que possuem esses ativos, calcular o valor de mercado atual da sua exposição e, em seguida, classificar os resultados para priorizar o maior risco. Essa análise complexa de múltiplas junções é a tarefa perfeita para nossa ferramenta avançada ES|QL.

Aqui está a consulta completa que usaremos. Parece impressionante, mas os conceitos são simples.

Analisando em detalhes: Junções e guarda-corpos

Nesta consulta, dois conceitos importantes entram em jogo e são essenciais para a criação do Agent Builder.

1. A junção de pesquisa

Durante anos, uma das funcionalidades mais solicitadas no Elasticsearch tem sido a capacidade de unir dados de diferentes índices com base em uma chave comum. Com ES|QL, isso agora é possível com LOOKUP JOIN.

Em nossa nova consulta, realizamos uma cadeia de três LOOKUP JOIN: primeiro conectando notícias negativas aos detalhes dos ativos, depois vinculando esses ativos às participações do cliente e, finalmente, unindo às informações da conta do cliente. Isso gera um resultado incrivelmente rico a partir de quatro índices diferentes em uma única consulta eficiente. Isso significa que podemos combinar conjuntos de dados distintos para criar uma resposta única e esclarecedora sem precisar desnormalizar todos os nossos dados em um único índice gigante antecipadamente.

2. Parâmetros como guarda-corpos LLM

Você notará que a consulta usa ?time_duration. Isso não é apenas uma variável; é uma proteção para a IA. Embora os Modelos de Linguagem de Grande Porte (LLMs, na sigla em inglês) sejam ótimos para gerar consultas, permitir que eles tenham livre acesso aos seus dados pode levar a consultas ineficientes ou até mesmo incorretas.

Ao criar uma consulta parametrizada, forçamos o LLM a funcionar dentro da lógica de negócios testada, eficiente e correta que um especialista humano já definiu. É semelhante à forma como os desenvolvedores usam modelos de pesquisa há anos para expor com segurança os recursos de consulta aos aplicativos. O agente pode interpretar a solicitação de um usuário como "esta semana" para preencher o parâmetro time_duration , mas deve usar nossa estrutura de consulta para obter a resposta. Isso nos proporciona o equilíbrio perfeito entre flexibilidade e controle.

Em última análise, essa consulta permite que um especialista que entende os dados incorpore seu conhecimento em uma ferramenta. Outras pessoas — e agentes de IA — podem então usar essa ferramenta para obter resultados correlacionados, fornecendo simplesmente um único parâmetro, sem precisar saber nada sobre a complexidade subjacente.

Etapa 2: A Habilidade — Transformar uma Consulta em uma Ferramenta Reutilizável

Uma consulta ES|QL é apenas texto até que a registremos como uma ferramenta. No Construtor de Agentes, uma ferramenta é mais do que apenas uma consulta salva; é uma "habilidade" que um agente de IA pode entender e optar por usar. A mágica está na descrição em linguagem natural que fornecemos. Essa descrição serve de ponte entre a pergunta do usuário e a lógica de consulta subjacente. Vamos registrar a consulta que acabamos de criar.

O Caminho da Interface do Usuário

Criar uma ferramenta no Kibana é um processo simples.

1. Navegue até Agentes

• Clique em Ferramentas ou Gerenciar Ferramentas e clique no botão Nova ferramenta .

2. Preencha o formulário com os seguintes dados:

• ID da ferramenta: find_client_exposure_to_negative_news

eu. Este é o ID exclusivo da ferramenta.

• Descrição: "Identifica a exposição da carteira de clientes a notícias negativas." Esta ferramenta analisa notícias e relatórios recentes em busca de sentimentos negativos, identifica o ativo associado e encontra todos os clientes que possuem esse ativo. Retorna uma lista ordenada pelo valor de mercado atual da posição para destacar o maior risco potencial."

eu. É isso que o LLM lê para decidir se essa ferramenta é a adequada para o trabalho.

• Rótulos: retrieval e risk-analysis

Etiquetas são usadas para ajudar a agrupar várias ferramentas.

• Configuração: Cole a consulta ES|QL completa da Etapa 1.

eu. Esta é a pesquisa que o agente usará.

3. Clique em Inferir parâmetros da consulta. A interface do usuário encontrará automaticamente ?time_duration e listará abaixo. Adicione uma descrição simples para cada um, para ajudar o agente (e outros usuários) a entender sua finalidade.

• time_durationO período de tempo para pesquisar notícias negativas. O formato é "X horas", com o valor padrão de 8760 horas.

4. Teste!

• Clique em Salvar e testar.

• Você verá um novo menu suspenso onde poderá testar a consulta para garantir que ela esteja funcionando conforme o esperado.

eu. Em time_duration insira o intervalo desejado; aqui, estamos usando “8760 horas”.

• Clique em “Enviar” e, se tudo correr bem, você verá uma resposta em formato JSON. Para garantir que funcione como esperado, role para baixo e observe o objeto values . É aí que os documentos correspondentes são devolvidos.

5. Clique no “X” no canto superior direito para fechar a janela de teste. Sua nova ferramenta agora aparecerá na lista, pronta para ser atribuída a um agente.

O caminho da API

Para desenvolvedores que preferem automação ou precisam gerenciar ferramentas programaticamente, é possível obter o mesmo resultado com uma única chamada de API. Basta enviar uma solicitação POST para o endpoint /api/agent_builder/tools com a definição da ferramenta.

Etapa 3: O Cérebro — Criando seu Agente Personalizado

Criamos uma habilidade reutilizável (a Ferramenta). Agora, precisamos criar o Agente, a persona que de fato irá utilizá-lo. Um Agente é a combinação de um LLM (Licença de Aprendizagem Baseada em Leis), um conjunto específico de ferramentas às quais você lhe concede acesso e, mais importante, um conjunto de Instruções Personalizadas que atuam como sua constituição, definindo sua personalidade, regras e propósito.

A Arte do Prompt

O aspecto mais importante na criação de um agente confiável e especializado é o prompt. Um conjunto de instruções bem elaborado é o que diferencia um chatbot genérico de um assistente profissional e focado. É aqui que você define as diretrizes, define a saída e atribui ao agente sua missão.

Para o nosso agente Financial Manager , usaremos o seguinte prompt.

Vamos analisar por que essa estratégia é tão eficaz:

• Define uma persona sofisticada: a primeira frase estabelece imediatamente o agente como um "Assistente de Inteligência de Dados especializado", definindo um tom profissional e competente.

• Isso fornece uma estrutura de raciocínio: ao dizer ao agente para "Compreender, Planejar, Executar e Sintetizar", estamos lhe dando um procedimento operacional padrão. Isso melhora sua capacidade de lidar com questões complexas e de várias etapas.

• Isso promove o diálogo interativo: a instrução para "fazer perguntas esclarecedoras" torna o agente mais robusto. Isso minimizará suposições incorretas sobre solicitações ambíguas, levando a respostas mais precisas.

O Caminho da Interface do Usuário

1. Navegue até Agentes.

• Clique em Ferramentas ou Gerenciar Ferramentas e clique no botão Nova ferramenta .

2. Preencha os dados básicos:

• ID do agente: financial_assistant.

• Instruções: Copie o enunciado acima.

• Rótulos: Finance.

• Nome de exibição: Financial Assistant.

• Descrição da exibição: An assistant for analyzing and understanding your financial data.

3. De volta ao topo, clique em Ferramentas.

• Marque a caixa ao lado da nossa ferramenta find_client_exposure_to_negative_news .

4. Clique em Salvar.

O caminho da API

Você pode criar o mesmo agente com uma solicitação POST para o endpoint /api/agent_builder/agents . O corpo da solicitação contém todas as mesmas informações: o ID, o nome, a descrição, o conjunto completo de instruções e uma lista das ferramentas que o agente tem permissão para usar.

Passo 4: A Recompensa — Ter uma Conversa

Temos nossa lógica de negócios encapsulada em uma ferramenta e um "cérebro" pronto para usá-la em nosso Agente. Chegou a hora de ver tudo se concretizar. Agora podemos começar a interagir com nossos dados usando um agente especializado.

O Caminho da Interface do Usuário

1. Navegue até Agentes no Kibana.

2. Utilizando o menu suspenso no canto inferior direito da janela de chat, alterne do agente padrão Elastic AI para o nosso novo agente Assistente Financeiro .

3. Faça uma pergunta que permita ao agente usar nossa ferramenta especializada:

   1. Estou preocupado com o sentimento do mercado. Você pode me mostrar quais dos nossos clientes correm maior risco em caso de más notícias?

Após alguns instantes, o agente retornará uma resposta completa e perfeitamente formatada. Devido à natureza dos LLMs, sua resposta pode ser formatada de maneira ligeiramente diferente, mas nesta execução, o agente retornou:

O que acabou de acontecer? O Raciocínio do Agente

O agente não apenas "sabia" a resposta. Executou um plano de várias etapas centrado na seleção da melhor ferramenta para o trabalho. Eis uma análise do seu processo de pensamento:

• Intenção identificada: Correspondeu a palavras-chave da sua pergunta, como "risco" e "notícias negativas", à descrição da ferramenta find_client_exposure_to_negative_news .

• Plano executado: o sistema extraiu o período de tempo da sua solicitação e fez uma única chamada para essa ferramenta especializada.

• Delegou o trabalho: a ferramenta então realizou todo o trabalho pesado: as junções encadeadas, os cálculos de valor e a classificação.

• Resultado Sintetizado: Por fim, o agente formatou os dados brutos da ferramenta em um resumo claro e legível para humanos, seguindo as regras do prompt.

E não precisamos apenas supor, se ampliarmos nosso pensamento e observarmos mais detalhes.

O caminho da API

Você pode iniciar essa mesma conversa programaticamente. Basta enviar a pergunta de entrada para o endpoint da API converse , certificando-se de especificar o agent_id do nosso financial_manager.

Para desenvolvedores: Integração com a API

Embora a interface do Kibana ofereça uma experiência fantástica e intuitiva para criar e gerenciar seus agentes, tudo o que você viu hoje também pode ser feito programaticamente. O Agent Builder é baseado em um conjunto de APIs, permitindo que você integre essa funcionalidade diretamente em seus próprios aplicativos, pipelines de CI/CD ou scripts de automação.

Os três principais endpoints com os quais você trabalhará são:

• /api/agent_builder/toolsO ponto de extremidade para criar, listar e gerenciar as habilidades reutilizáveis que seus agentes podem usar.

• /api/agent_builder/agentsO ponto final para definir as personas dos seus agentes, incluindo as importantíssimas instruções e atribuições de ferramentas.

• /api/agent_builder/converse: O ponto de acesso para interagir com seus agentes, iniciar conversas e obter respostas.

Para um passo a passo completo e prático de como usar essas APIs para executar cada etapa deste tutorial, confira o Jupyter Notebook que acompanha o tutorial, disponível aqui em nosso repositório do GitHub.

Conclusão: Sua vez de construir

Começamos por pegar numa consulta ES|QL e transformá-la numa habilidade reutilizável. Em seguida, criamos um agente de IA especializado, atribuindo-lhe uma missão e regras claras, e capacitando-o com essa habilidade. O resultado é um assistente sofisticado que consegue entender uma pergunta complexa e executar uma análise em várias etapas para fornecer uma resposta precisa e baseada em dados.

Esse fluxo de trabalho é fundamental para o novo Construtor de Agentes da Elastic. Ele foi projetado para ser simples o suficiente para que usuários sem conhecimento técnico possam criar agentes por meio da interface do usuário, mas também sofisticado o bastante para que desenvolvedores criem aplicativos personalizados com inteligência artificial utilizando nossas APIs. Mais importante ainda, permite que você conecte LLMs aos seus próprios dados de forma segura e protegida, regida pela lógica especializada que você define, e converse com seus dados.

Pronto para usar agentes para conversar com seus dados?

A melhor maneira de consolidar o que você aprendeu é colocar a mão na massa. Experimente tudo o que discutimos hoje em nossa oficina prática, gratuita e interativa. Você passará por todo esse processo e muito mais em um ambiente sandbox dedicado.

Em um post futuro do blog, mostraremos como usar um aplicativo independente que interage com nosso agente Financial Assistant e exploraremos o Protocolo de Contexto de Modelo (MCP) que torna tudo isso possível. E em um post separado, discutiremos o suporte do Agent Builder ao protocolo Agent2Agent, ou A2A, ainda em desenvolvimento.

Fiquem ligados e boas construções!

Construtor de Agentes: Uma Base para a Criação de Agentes de IA Orientados por Dados

A promessa de um agente de IA é simples: dê a ele um objetivo e ele realizará a tarefa. Mas para os desenvolvedores, a realidade é uma série de desafios complexos. Em primeiro lugar, um agente é tão bom quanto a sua percepção do ambiente e das ferramentas que lhe são fornecidas para atingir os objetivos do usuário. Além disso, fornecer o contexto correto em meio a um mar de dados empresariais diversos é um desafio enorme. Finalmente, tudo isso precisa ser orquestrado por um circuito de raciocínio confiável que possa planejar, executar e aprender.

Para resolver isso, os desenvolvedores precisam construir uma estrutura complexa e frágil do zero. A arquitetura de agentes atual exige a integração de várias peças distintas: um LLM (Modelo de Aprendizado de Liderança), um banco de dados vetorial, um repositório de metadados, sistemas separados para registro e rastreamento, e alguma forma de avaliar se tudo está funcionando corretamente. Isso não é apenas complexo; é caro, propenso a erros e dificulta a criação de sistemas de IA confiáveis e de alta qualidade que seus usuários exigem.

Por isso, queremos simplificar. Para isso, nossa abordagem consiste em pegar os elementos essenciais de um agente orientado ao contexto eficaz e integrá-los diretamente ao núcleo do Elasticsearch com um novo conjunto de recursos chamado Elastic AI Agent Builder. Essa nova camada fornece uma estrutura com todos os componentes essenciais para a criação de agentes de IA baseados no Elasticsearch: um conjunto aberto de primitivas, protocolos baseados em padrões e acesso seguro aos dados — para que você possa criar sistemas de agentes adaptados a dados e requisitos do mundo real:

Proporcionar experiências com IA: esse é o objetivo final. Com nossa Plataforma de IA de Busca e seus dados como base, você pode criar qualquer tipo de aplicativo de IA generativa: desde interfaces de bate-papo personalizadas até integrações com frameworks de agentes como o LangChain ou aplicativos de negócios como o Salesforce.

Com tecnologia Agents & Tools: sobre a plataforma, expomos uma camada de abstrações limpa e simples. Você interage diretamente com agentes e ferramentas, que podem ser personalizadas para atender às suas necessidades específicas. Você também pode acessar os recursos da plataforma por meio de APIs robustas e padrões abertos como MCP e A2A.

Habilitado pela Plataforma de IA de Busca: este é o mecanismo principal onde integramos os componentes. O banco de dados vetorial avançado, a lógica do agente, a construção de consultas, os recursos de segurança e o rastreamento para avaliação, tudo reside aqui, gerenciado e otimizado pela Elastic.

Desvendando o poder dos seus dados: a base de qualquer agente de sucesso são dados de alta qualidade. Nossa plataforma começa com a capacidade de ingerir ou federar o acesso a todos os dados da sua empresa.

Construção de Agentes na Plataforma

O Agent Builder, integrado à Plataforma de IA de Busca, fornece uma estrutura completa para o desenvolvimento de agentes. É construído sobre cinco pilares fundamentais, cada um projetado para abordar um aspecto crítico da construção e implantação de sistemas de IA de nível de produção. Vamos analisar como os agentes definem o objetivo, as ferramentas fornecem as capacidades, os padrões abertos garantem a interoperabilidade, a avaliação proporciona transparência e a segurança garante a confiança.

Agentes

Os agentes são o bloco de construção de nível mais alto nesta nova camada do Elasticsearch. Um agente define o objetivo a ser alcançado, o conjunto de ferramentas disponíveis para execução e as fontes de dados sobre as quais pode operar. Os agentes não se limitam a interações conversacionais; eles podem viabilizar fluxos de trabalho completos, automação de tarefas ou experiências voltadas para o usuário.

Quando uma consulta é direcionada a um agente, ela segue um ciclo estruturado:

1. Interprete sua contribuição e objetivo.

2. Selecione a ferramenta e os argumentos corretos para a execução.

3. Analise a resposta da ferramenta.

4. Decida se deseja retornar um resultado ou continuar com outras invocações da ferramenta.

A Elastic cuida da orquestração, do contexto e da execução desse ciclo. Os desenvolvedores se concentram em definir o que o agente deve fazer: objetivos, ferramentas e dados, enquanto o sistema gerencia como o raciocínio e os fluxos de trabalho são executados.

O Agente Padrão

Nosso primeiro agente desenvolvido nesta plataforma é um agente conversacional nativo do Kibana, que permite interagir imediatamente com seus dados. Proporciona uma experiência pronta a usar, mantendo-se totalmente extensível e permitindo que você comece a interagir com seus dados imediatamente, sem necessidade de configuração adicional.

Você pode interagir com essa experiência diretamente no Kibana por meio de uma nova experiência de chat ou via API.

Consultar o agente padrão por meio da API requer apenas uma única chamada:

Como as conversas mantêm estado, você pode continuar interagindo com um agente usando um `conversation_id` ou recuperar o histórico completo da conversa:

Agentes alfandegários

Os desenvolvedores também podem criar seus próprios agentes personalizados por meio de APIs simples. Os agentes encapsulam instruções, ferramentas e acesso a dados, criando mecanismos de raciocínio personalizados.

Criar um agente personalizado é tão simples quanto fazer uma única chamada à API. O exemplo abaixo ilustra isso. O campo "configuração" contém todos os detalhes importantes, como instruções ou ferramentas disponíveis:

Uma vez criado, o agente pode ser consultado diretamente:

Essa abordagem transforma o agente, de um sistema complexo a ser construído do zero, em uma unidade simples e declarativa de lógica de negócios, permitindo que você implemente automação inteligente mais rapidamente.

Para uma análise aprofundada sobre como construir um agente especializado do zero, consulte nosso guia detalhado, passo a passo: Seu primeiro agente elástico: de uma única consulta a um bate-papo com inteligência artificial.

Ferramentas

Se os agentes definem o que realizar, as ferramentas definem como.

As ferramentas expõem funcionalidades específicas do Elastic Core para que os agentes executem e recuperem informações ou realizem uma ação. As ferramentas podem incluir funcionalidades básicas como obter índices ou obter mapeamentos, ou funcionalidades mais avançadas como conversão de linguagem natural para ES|QL.

O Elasticsearch é fornecido com um conjunto de ferramentas padrão otimizadas para necessidades comuns. Mas a verdadeira flexibilidade vem de criar a sua própria. Ao definir as ferramentas, você decide exatamente quais consultas, índices e campos são expostos a um agente com ES|QL, proporcionando controle preciso sobre velocidade, exatidão e segurança.

O registro de uma nova ferramenta também é tão simples quanto uma única chamada de API. Você poderia criar uma ferramenta que utilizasse nossa linguagem ES|QL (Elasticsearch Query Language) para encontrar notícias sobre um ativo financeiro específico:

Após o registro, você pode atribuir a nova ferramenta aos seus agentes personalizados, oferecendo a eles um conjunto selecionado de habilidades para analisar e utilizar sempre que for adequado.

Oferecemos uma plataforma para criar ferramentas personalizadas para suas necessidades específicas, por exemplo, com ES|QL, que transforma o agente de um agente de propósito geral em um especialista em um domínio específico, fundamentado em seus dados e domínio de negócios exclusivos.

Padrões Abertos e Interoperabilidade

Os agentes e ferramentas do Elasticsearch são expostos por meio de APIs de padrão aberto, o que facilita sua integração como blocos fundamentais dentro do ecossistema mais amplo de frameworks de agentes. Nossa abordagem é simples: sem caixas pretas. Queremos que você possa aproveitar o principal ponto forte da Elastic em buscas e combiná-lo com recursos complementares e outros sistemas de agentes.

Para tornar isso possível, estamos disponibilizando nossas capacidades por meio de APIs, protocolos emergentes e padrões abertos.

Protocolo de Contexto do Modelo (MCP)

O Protocolo de Contexto de Modelo (MCP) está rapidamente se tornando o padrão aberto para conectar ferramentas em diferentes sistemas. Ao oferecer suporte ao MCP, o Elasticsearch pode conectar a IA conversacional aos seus bancos de dados, índices e APIs externas. Com um servidor MCP remoto integrado ao Elastic Stack, qualquer cliente compatível com MCP pode acessar as ferramentas da Elastic e usá-las como blocos de construção em seus fluxos de trabalho de agentes mais amplos.

Esta não é uma via de mão única. Você também poderá importar ferramentas de servidores MCP externos e disponibilizá-las dentro do Elasticsearch. Em breve, os servidores MCP provavelmente estarão disponíveis para quase tudo e serão muito mais abrangentes do que qualquer coisa que pudéssemos criar por conta própria. A Elastic oferece busca e recuperação em grande escala, e você pode combinar isso com recursos especializados de outras plataformas para criar agentes eficazes.

Agente para Agente (A2A)

Também estamos trabalhando no suporte de agente para agente (A2A). Enquanto o MCP se concentra em conectar ferramentas, o A2A se concentra em conectar agentes. Com um servidor A2A, os agentes Elastic que você criar poderão se comunicar diretamente com agentes de outros sistemas: compartilhando contexto, delegando tarefas e coordenando fluxos de trabalho.

Pense nisso como interoperabilidade na camada de raciocínio. Seu agente Elastic pode lidar com a busca e recuperação de dados, depois repassar a tarefa para um agente de suporte ou de TI especializado e obter o resultado de volta sem problemas. O resultado é um ecossistema de agentes cooperativos, cada um fazendo o que faz de melhor.

Em última análise, a adoção do MCP e do A2A reforça nosso compromisso com o papel do Elasticsearch como um elemento de primeira classe, garantindo a integração aberta em todo o ecossistema de agentes.

Rastreamento e Avaliação

À medida que a busca se integra aos agentes, o desafio da avaliação eficaz torna-se crucial. Para implantar agentes com segurança em ambientes empresariais reais, você precisa ter a garantia de que eles não sejam apenas precisos, mas também eficientes e confiáveis. Como você mede o desempenho, diagnostica uma resposta inadequada ou melhora o nível inicial? Tudo começa com a visibilidade.

É por isso que projetamos nossas APIs de agentes com foco na transparência desde o início. Considere esta interação simples entre agentes:

A resposta inclui não apenas a resposta final, mas também o rastreamento completo da execução, detalhando quais ferramentas o agente selecionou, os parâmetros que utilizou e os resultados de cada etapa.

O rastreamento e o registro abrangentes são essenciais para um ciclo de melhoria contínua e, em breve, você poderá armazenar e visualizar esses rastreamentos de agentes diretamente no Elasticsearch. Melhor ainda, esses rastreamentos são baseados no protocolo OpenTelemetry, garantindo que sejam padronizados e portáteis para integração com a plataforma de observabilidade de sua escolha.

Esse nível de detalhamento é a base para um verdadeiro ciclo de melhoria contínua. Ele permite que você crie um conjunto abrangente de testes, depure falhas, identifique modos de falha para evitar regressões e capture padrões de sucesso para otimizar o desempenho. Em última análise, essa abordagem orientada por dados é a chave para transformar um protótipo promissor em um sistema de IA confiável e pronto para produção.

Segurança

À medida que os agentes e as ferramentas se tornam mais capazes, a segurança deixa de ser opcional e passa a ser fundamental. Expor APIs, automatizar tarefas e fluxos de trabalho exige que os sistemas empresariais sejam confiáveis. Principalmente à medida que os agentes começam a automatizar mais fluxos de trabalho, a capacidade de protegê-los e garantir que atendam aos requisitos da empresa torna-se essencial.

Todas as funcionalidades acima herdam os controles já disponíveis no Elastic atualmente, incluindo o controle de acesso baseado em funções (RBAC) para chamadas de API e o gerenciamento de chaves de API. Também estamos estendendo os mesmos controles a novos protocolos como o MCP. Isso significa suporte para padrões como o OAuth, bem como a capacidade de integrar mecanismos de autenticação personalizados.

Nosso objetivo é oferecer a flexibilidade necessária para que você experimente agentes e ferramentas, mantendo o nível de segurança, conformidade e governança que sua organização exige.

O que vem a seguir

Não estamos apenas adicionando funcionalidades; estamos expandindo o Elasticsearch para engenharia de contexto agente. Planejamos desenvolver nosso trabalho daqui para frente com base nesses princípios:

1. Compromisso com o código aberto e os padrões

Nosso compromisso com o código aberto e os padrões abertos garante que essas funcionalidades permaneçam interoperáveis com estruturas de agentes externas. Você sempre poderá conectar, estender e compor agentes em todo o seu ecossistema, mantendo seus dados e fluxos de trabalho sob seu controle.

2. Valor do Contexto

O contexto é o maior trunfo de um agente de IA. Gerenciar o contexto enquanto os agentes realizam buscas e operações de fluxo de trabalho pode ser uma tarefa desafiadora. Estamos aproveitando os principais pontos fortes da Elastic para resolver a engenharia de contexto, garantindo que as informações mais relevantes estejam sempre disponíveis para o seu agente.

3. Foque em fluxos de dados agéticos

No futuro, os agentes serão uma fonte de dados cada vez maior, incluindo a saída dos agentes (documentos gerados, relatórios, visualizações) e o rastro de execução dos agentes (seu raciocínio, chamadas de ferramentas, memória/contexto). A Elastic é ideal para lidar com esse tipo de dados, e estamos trabalhando em pesquisas sobre como realizar análises, avaliações e melhorias automatizadas usando esses dados.

4. Segurança e proteção por design

Os agentes de IA introduzem um conjunto totalmente novo de desafios em termos de segurança e proteção. A Elastic sempre foi líder em soluções seguras e continuamos a incorporar proteções de nível empresarial, controles de acesso e princípios de "confiança zero".

5. Integrado à plataforma

Os recursos para criar agentes de IA estão integrados na plataforma Elasticsearch. Isso significa que funcionalidades de nível de plataforma, como rastreamento, avaliação, visualização e análise, são todas aplicáveis aos agentes. Deseja desenvolver painéis de controle com base nas execuções dos agentes? Isso já está integrado. Deseja avaliar o desempenho do agente de IA usando análise de sentimentos? A plataforma permite isso. Isso possibilita a criação de um ciclo de vida completo em torno de suas experiências com IA.

O objetivo da Elastic é fornecer interfaces para que você possa criar IA conversacional e fluxos de trabalho automatizados que sejam totalmente integrados, extensíveis e baseados em seus dados. Mais detalhes técnicos e informações sobre o progresso serão compartilhados em breve.

O Construtor de Agentes já está disponível em versão prévia privada. Entre em contato conosco para solicitar acesso. Tem perguntas ou comentários? Conecte-se com nossa comunidade de desenvolvedores em nosso espaço de trabalho no Slack ou em nosso fórum de discussão.

Neste artigo, exploraremos como construir um assistente RAG agente usando o Mastra e um aplicativo web JavaScript leve para interagir com ele. Ao conectar este agente ao Elasticsearch, damos a ele acesso a dados estruturados dos jogadores e a capacidade de executar agregações estatísticas em tempo real, para fornecer recomendações baseadas em estatísticas dos jogadores. Acesse o repositório do GitHub para acompanhar; o arquivo README fornece instruções sobre como clonar e executar o aplicativo por conta própria.

Eis como deverá ficar quando tudo estiver montado:

Nota: Este post do blog complementa o artigo “Criando agentes de IA com o SDK de IA e o Elastic”. Se você é iniciante no estudo de agentes de IA em geral e em suas possíveis aplicações, comece por aí.

Visão geral da arquitetura

No núcleo do sistema está um modelo de linguagem abrangente (LLM, na sigla em inglês), que atua como o motor de raciocínio do agente (o cérebro). Ele interpreta a entrada do usuário, decide quais ferramentas utilizar e orquestra as etapas necessárias para gerar uma resposta relevante.

O próprio agente é estruturado pelo Mastra, um framework de agentes no ecossistema JavaScript. O Mastra integra o LLM com infraestrutura de backend, expõe-no como um endpoint de API e fornece uma interface para definir ferramentas, prompts do sistema e comportamento do agente.

Na interface, usamos o Vite para criar rapidamente um aplicativo web React que fornece uma interface de chat para enviar perguntas ao agente e receber suas respostas.

Por fim, temos o Elasticsearch, que armazena estatísticas de jogadores e dados de confrontos que o agente pode consultar e agregar.

Histórico

Vamos revisar alguns conceitos fundamentais:

O que é RAG agentivo?

Os agentes de IA podem interagir com outros sistemas, operar de forma independente e executar ações com base em parâmetros definidos por eles. O Agentic RAG combina a autonomia de um agente de IA com os princípios da geração aumentada por recuperação, permitindo que um LLM escolha quais ferramentas utilizar e quais dados usar como contexto para gerar uma resposta. Leia mais sobre a RAG aqui.

Ao escolher uma estrutura, por que ir além do AI-SDK?

Existem muitas estruturas de agentes de IA disponíveis e você provavelmente já ouviu falar das mais populares, como CrewAI, AutoGen e LangGraph. A maioria dessas estruturas compartilha um conjunto comum de funcionalidades, incluindo suporte para diferentes modelos, uso de ferramentas e gerenciamento de memória.

Segue abaixo uma tabela comparativa de frameworks elaborada por Harrison Chase (CEO da LangChain).

O que despertou meu interesse no Mastra foi o fato de ser um framework que prioriza o JavaScript, criado para que desenvolvedores full-stack possam integrar agentes facilmente em seu ecossistema. O SDK de IA da Vercel também faz a maior parte disso, mas o grande diferencial do Mastra é quando seus projetos incluem fluxos de trabalho de agentes mais complexos. O Mastra aprimora os padrões básicos definidos pelo AI-SDK e, neste projeto, usaremos os dois em conjunto.

Considerações sobre estruturas e escolha de modelos

Embora essas estruturas possam ajudá-lo a criar agentes de IA rapidamente, existem algumas desvantagens a serem consideradas. Por exemplo, ao usar qualquer outra estrutura fora dos agentes de IA ou de qualquer camada de abstração em geral, você perde um pouco do controle. Se o LLM não usar as ferramentas corretamente ou fizer algo que você não deseja, a abstração dificulta a depuração. Ainda assim, na minha opinião, essa troca vale a pena pela facilidade e rapidez que se obtém ao construir, especialmente porque essas estruturas estão ganhando força e sendo constantemente aprimoradas.

Novamente, essas estruturas são agnósticas em relação ao modelo, o que significa que você pode usar diferentes modelos sem problemas. Lembre-se de que os modelos variam nos conjuntos de dados em que foram treinados e, consequentemente, variam nas respostas que fornecem. Alguns modelos sequer suportam a chamada de ferramentas. Portanto, é possível alternar e testar diferentes modelos para ver qual oferece as melhores respostas, mas lembre-se de que provavelmente você terá que reescrever o prompt do sistema para cada um deles. Por exemplo, usando Llama3.3 Em comparação com o GPT-40, é necessário muito mais estímulo e instruções específicas para obter a resposta desejada.

Basquete de fantasia da NBA

O basquete de fantasia envolve a criação de uma liga com um grupo de amigos (atenção: dependendo do nível de competitividade do grupo, isso pode afetar o status das suas amizades), geralmente com algum dinheiro em jogo. Cada um de vocês monta uma equipe de 10 jogadores para competir contra a equipe de 10 jogadores de um amigo, alternando semanalmente. Os pontos que contribuem para a sua pontuação geral são definidos pelo desempenho de cada um dos seus jogadores contra os adversários em uma determinada semana.

Se um jogador da sua equipe se lesionar, for suspenso, etc., existe uma lista de jogadores disponíveis no mercado para adicionar à sua equipe. É aqui que entra em jogo grande parte da estratégia complexa nos esportes de fantasia, porque você tem um número limitado de jogadores para escolher e todos estão constantemente em busca do melhor jogador.

É aqui que nosso assistente de IA da NBA brilhará, especialmente em situações em que você precisa decidir rapidamente qual jogador escolher. Em vez de ter que pesquisar manualmente o desempenho de um jogador contra um adversário específico, o assistente pode encontrar esses dados rapidamente e comparar as médias para fornecer uma recomendação precisa.

Agora que você já conhece alguns conceitos básicos sobre RAG agentivo e basquete fantasy da NBA, vamos ver como funciona na prática.

Construindo o projeto

Se você ficar preso em algum ponto ou não quiser construir tudo do zero, consulte o repositório.

O que abordaremos

1. Estruturando o projeto:

   1. Backend (Mastra): Use o comando `npx create mastra@latest` para criar a estrutura do backend e definir a lógica do agente.

   2. Frontend (Vite + React): Use o comando `npm create vite@latest` para criar a interface de chat do frontend para interação com o agente.

2. Configurando variáveis de ambiente

   1. Instale o dotenv para gerenciar variáveis de ambiente.

   2. Crie um arquivo .env arquive e forneça as variáveis necessárias.

3. Configurando o Elasticsearch

   1. Crie um cluster Elasticsearch (localmente ou na nuvem).

   2. Instale o cliente oficial do Elasticsearch.

   3. Garanta que as variáveis de ambiente estejam acessíveis.

   4. Estabelecer conexão com o cliente.

4. Ingestão em massa de dados da NBA no Elasticsearch

   1. Crie um índice com os mapeamentos apropriados para habilitar agregações.

   2. Importar em massa estatísticas de jogo de jogadores de um arquivo CSV para um índice do Elasticsearch.

5. Definir agregações do Elasticsearch

   1. Consulta para calcular as médias históricas contra um adversário específico.

   2. Consulta para calcular as médias da temporada contra um adversário específico.

6. Arquivo utilitário de comparação de jogadores

   1. Consolida funções auxiliares e agregações do Elasticsearch.

7. Construindo o agente

   1. Adicione a definição do agente e o prompt do sistema.

   2. Instale o Zod e defina as ferramentas.

   3. Adicionar configuração de middleware para lidar com CORS.

8. Integrando o frontend

   1. Utilizando o useChat do AI-SDK para interagir com o agente.

   2. Crie a interface do usuário para manter conversas formatadas adequadamente.

9. Executando o aplicativo

   1. Inicie tanto o backend (servidor Mastra) quanto o frontend (aplicativo React).

   2. Exemplos de consultas e uso.

10. O que vem a seguir: tornar o agente mais inteligente.

    1. Adicionando recursos de busca semântica para possibilitar recomendações mais relevantes.

    2. Habilite consultas dinâmicas movendo a lógica de busca para o servidor Elasticsearch MCP (Model Context Protocol).

Pré-requisitos

• Node.js e npm: Tanto o backend quanto o frontend são executados em Node. Certifique-se de ter o Node 18+ e o npm v9+ instalados (que já vêm incluídos no Node 18+).

• Cluster Elasticsearch: Um cluster Elasticsearch ativo, seja localmente ou na nuvem.

• Chave da API da OpenAI: Gere uma na página de chaves da API no portal de desenvolvedores da OpenAI.

Estrutura do projeto

Etapa 1: Estruturando o projeto

1. Primeiro, crie o diretório nba-ai-assistant-js e navegue até ele usando:

Backend:

1. Utilize a ferramenta de criação do Mastra com o comando:

2. Você deverá receber algumas mensagens no seu terminal. Para a primeira, vamos nomear o backend do projeto:

3. Em seguida, manteremos a estrutura padrão para armazenar os arquivos Mastra, então insira src/.

4. Em seguida, escolheremos a OpenAI como nosso provedor padrão de LLM.

5. Por fim, será solicitada a sua chave de API da OpenAI. Por agora, vamos escolher a opção de ignorar e fornecer isso mais tarde em um arquivo .env .

Front-end:

1. Volte ao diretório raiz e execute a ferramenta de criação do Vite usando este comando: npm create vite@latest frontend -- --template react

Isso deverá criar um aplicativo React leve chamado frontend com um modelo específico para React.

Se tudo correr bem, dentro do diretório do seu projeto, você deverá ver um diretório backend que contém o código Mastra e um diretório frontend com seu aplicativo React.

Etapa 2: Configurando as variáveis de ambiente

1. Para gerenciar chaves sensíveis, usaremos o pacote dotenv para carregar nossas variáveis de ambiente do arquivo .env. arquivo. Navegue até o diretório backend e instale dotenv:

2. No diretório backend, um arquivo example.env é fornecido com as variáveis apropriadas para preenchimento. Se você criar o seu próprio, certifique-se de incluir as seguintes variáveis:

Nota: Certifique-se de que este arquivo seja excluído do seu controle de versão adicionando .env a .gitignore.

Etapa 3: Configurando o Elasticsearch

Primeiro, você precisa de um cluster Elasticsearch ativo. Existem duas opções:

• Opção A: Usar o Elasticsearch Cloud

  • Inscreva-se no Elastic Cloud.

  • Criar uma nova implantação

  • Obtenha o URL do seu endpoint e a chave da API (codificada).

• Opção B: Executar o Elasticsearch localmente

  • Instale e execute o Elasticsearch localmente.

  • Use http://localhost:9200 como seu endpoint.

  • Gere uma chave de API

Instalando o cliente Elasticsearch no servidor:

1. Primeiro, instale o cliente oficial do Elasticsearch no diretório do seu backend:

2. Em seguida, crie um diretório chamado lib para armazenar funções reutilizáveis e navegue até ele:

3. Dentro da pasta, crie um novo arquivo chamado elasticClient.js. Este arquivo inicializará o cliente Elasticsearch e o disponibilizará para uso em todo o seu projeto.

4. Como estamos usando módulos ECMAScript (ESM), os nomes de arquivo __dirname and __não estão disponíveis. Para garantir que suas variáveis de ambiente sejam carregadas corretamente a partir do arquivo .env No arquivo localizado na pasta backend, adicione esta configuração ao início do seu arquivo:

5. Agora, inicialize o cliente Elasticsearch usando suas variáveis de ambiente e verifique a conexão:

Agora, podemos importar essa instância de cliente para qualquer arquivo que precise interagir com o seu cluster Elasticsearch.

Etapa 4: Ingestão em massa de dados da NBA no Elasticsearch

Conjunto de dados:

Para este projeto, utilizaremos como referência os conjuntos de dados disponíveis no diretório backend/data do repositório. Nosso assistente da NBA usará esses dados como base de conhecimento para realizar comparações estatísticas e gerar recomendações.

• sample_player_game_stats.csv - Estatísticas de jogo de jogadores (por exemplo, pontos, rebotes, roubos de bola, etc., por jogo, por jogador, ao longo de toda a sua carreira na NBA). Usaremos esse conjunto de dados para realizar agregações. (Observação: estes são dados fictícios, pré-gerados para fins de demonstração e não provenientes de fontes oficiais da NBA.)

• playerAndTeamInfo.js - Substitui os metadados de jogadores e equipes que normalmente seriam fornecidos por uma chamada de API, permitindo que o agente associe nomes de jogadores e equipes a IDs. Como estamos usando dados de exemplo, não queremos a sobrecarga de buscar dados em uma API externa, então definimos alguns valores fixos que o agente pode referenciar.

Implementação:

1. No diretório backend/lib , crie um arquivo chamado playerDataIngestion.js.

2. Configure as importações, resolva o caminho do arquivo CSV e configure a análise sintática. Novamente, como estamos usando ESM, precisamos reconstruir __dirname para resolver o caminho para o CSV de amostra. Além disso, importaremos o Node.js. módulos integrados, fs e readline, para analisar o arquivo CSV fornecido linha por linha.

Isso prepara você para ler e analisar o CSV de forma eficiente quando chegarmos à etapa de ingestão em massa.

3. Crie um índice com o mapeamento apropriado. Embora o Elasticsearch possa inferir automaticamente os tipos de campo com mapeamento dinâmico, queremos ser explícitos aqui para que cada estatística seja tratada como um campo numérico. Isso é importante porque usaremos esses campos para agregações mais tarde. Também queremos usar o tipo float para estatísticas como pontos, rebotes, etc., para garantir que incluamos valores decimais. Finalmente, queremos adicionar a propriedade de mapeamento dynamic: 'strict' para que o Elasticsearch não mapeie dinamicamente campos não reconhecidos. 

4. Adicione a função para ingerir em massa os dados CSV no seu índice Elasticsearch. Dentro do bloco de código, omitimos a linha de cabeçalho. Em seguida, separe cada item da linha por vírgula e insira-os no objeto do documento. Esta etapa também os limpa e garante que sejam do tipo correto. Em seguida, inserimos os documentos na matriz bulkBody juntamente com as informações do índice, que servirão como carga útil para a ingestão em massa no Elasticsearch.

5. Então, podemos usar a API Bulk do Elasticsearch com elasticClient.bulk() para ingerir vários documentos em uma única solicitação. O tratamento de erros abaixo está estruturado para fornecer uma contagem de quantos documentos não foram ingeridos e quantos foram ingeridos com sucesso.

6. Execute a função main() abaixo para executar sequencialmente as funções createIndex() e bulkIngestCsv() .

Se você vir um registro no console indicando que a ingestão em massa foi bem-sucedida, faça uma verificação rápida no seu índice do Elasticsearch para confirmar se os documentos foram realmente ingeridos com sucesso.

Etapa 5: Definindo e consolidando as agregações do Elasticsearch

Essas serão as principais funções que serão utilizadas quando definirmos as ferramentas para o Agente de IA, a fim de comparar as estatísticas dos jogadores entre si.

1. Navegue até o diretório backend/lib e crie um arquivo chamado elasticAggs.js.

2. Adicione a consulta abaixo para calcular as médias históricas de um jogador contra um adversário específico. Esta consulta usa um filtro bool com 2 condições: uma que corresponde player_id e outra que corresponde a opponent_team_id, para recuperar apenas os jogos relevantes. Não precisamos retornar nenhum documento, só nos interessam as agregações, então definimos size:0. No bloco aggs , executamos várias agregações de métricas em paralelo em campos como points, rebounds, assists, steals, blocks e fg_percentage para calcular seus valores médios. Os cálculos dos LLMs podem ser inconsistentes, e essa solução transfere esse processo para o Elasticsearch, garantindo que nosso assistente de IA da NBA tenha acesso a dados precisos.

3. Para calcular as médias da temporada de um jogador contra um adversário específico, usaremos praticamente a mesma consulta que a consulta histórica. A única diferença nesta consulta é que o filtro bool tem uma condição adicional para game_date. O campo game_date tem que estar dentro do intervalo da temporada atual da NBA. Neste caso, o intervalo está entre 2024-10-01 e 2025-06-30. Essa condição adicional abaixo garante que as agregações subsequentes isolarão apenas os jogos desta temporada.

Etapa 6: Ferramenta de comparação de jogadores

Para manter nosso código modular e de fácil manutenção, criaremos um arquivo utilitário que consolida funções auxiliares de metadados e agregações do Elasticsearch. Isso alimentará a principal ferramenta usada pelo agente. Mais sobre isso adiante:

1. Crie um novo arquivo comparePlayers.js no diretório backend/lib .

2. Adicione a função abaixo para consolidar os auxiliares de metadados e a lógica de agregação do Elasticsearch em uma única função que alimenta a ferramenta principal usada pelo agente.

Etapa 7: Construindo o agente

Agora que você criou a estrutura básica do frontend e do backend, importou os dados dos jogos da NBA e estabeleceu uma conexão com o Elasticsearch, podemos começar a juntar todas as peças para construir o agente.

Definindo o agente

1. Navegue até o arquivo index.ts dentro do diretório backend/src/mastra/agents e adicione a definição do agente. Você pode especificar campos como:

• Nome: Dê ao seu agente um nome que será usado como referência quando ele for chamado na interface.

• Instruções/mensagem do sistema: Uma mensagem do sistema fornece ao LLM o contexto inicial e as regras a seguir durante a interação. É semelhante à mensagem que os usuários enviam pelo chat, mas esta é exibida antes de qualquer interação do usuário. Novamente, isso irá variar dependendo do modelo que você escolher.

• Modelo: Qual modelo de aprendizagem de linguagem (LLM) usar (o Mastra suporta modelos OpenAI, antrópicos, locais, etc.).

• Ferramentas: Uma lista de funções de ferramentas que o agente pode chamar.

• Memória: (Opcional) se quisermos que o agente se lembre do histórico da conversa, etc. Para simplificar, podemos começar sem memória persistente, embora o Mastra a suporte.

Ferramentas de definição

1. Navegue até o arquivo index.ts dentro do diretório backend/src/mastra/tools .

2. Instale o Zod usando o comando:

3. Adicionar definições de ferramentas. Observe que importamos a função dentro do arquivo comparePlayers.js como a função principal que o agente usará ao chamar esta ferramenta. Usando a função createTool() do Mastra, vamos registrar nosso playerComparisonTool. Os campos incluem:

• idEsta é uma descrição em linguagem natural para ajudar o agente a entender o que a ferramenta faz.

• input schemaPara definir o formato da entrada para a ferramenta, o Mastra utiliza o esquema Zod , que é uma biblioteca de validação de esquemas TypeScript. Zod ajuda garantindo que o agente insira dados estruturados corretamente e impede que a ferramenta seja executada caso a estrutura de entrada não corresponda.

• descriptionEsta é uma descrição em linguagem natural para ajudar o agente a entender quando ligar e usar a ferramenta.

• executeA lógica que é executada quando a ferramenta é chamada. No nosso caso, estamos usando uma função auxiliar importada para retornar estatísticas de desempenho.

Adicionando middleware para lidar com CORS

Adicione um middleware no servidor Mastra para lidar com CORS. Dizem que existem três coisas na vida que você não pode evitar: a morte, os impostos e, para desenvolvedores web, o CORS. Em resumo, o Compartilhamento de Recursos de Origem Cruzada (CORS) é um recurso de segurança do navegador que impede que o frontend faça solicitações a um backend executado em um domínio ou porta diferente. Embora executemos tanto o backend quanto o frontend em localhost, eles usam portas diferentes, acionando a política CORS. Precisamos adicionar o middleware especificado na documentação do Mastra para que nosso backend permita essas solicitações do frontend.

1. Navegue até o arquivo index.ts dentro do diretório backend/src/mastra e adicione a configuração para CORS:

• origin: ['http://localhost:5173']

  • Permite solicitações somente deste endereço (endereço padrão do Vite)

• allowMethods: ["GET", "POST"]

  • Métodos HTTP permitidos. Na maioria das vezes, será utilizado o método POST.

• allowHeaders: ["Content-Type", "Authorization", "x-mastra-client-type, "x-highlight-request", "traceparent"],

  • Essas configurações definem quais cabeçalhos personalizados podem ser usados nas solicitações.

Etapa 8: Integrando o frontend

Este componente React fornece uma interface de chat simples que se conecta ao agente de IA Mastra usando o gancho useChat() de @ai-sdk/react. Também usaremos esse recurso para exibir o uso de tokens, chamadas de ferramentas e para renderizar a conversa. No prompt do sistema acima, também pedimos ao agente para exibir a resposta em markdown, então usaremos react-markdown para formatar a resposta corretamente.

1. No diretório frontend, instale o pacote @ai-sdk/react para usar o gancho useChat().

2. Ainda no mesmo diretório, instale o React Markdown para que possamos formatar corretamente a resposta gerada pelo agente.

3. Implemente useChat(). Este gancho gerenciará a interação entre seu frontend e o backend do seu agente de IA. Ele gerencia o estado das mensagens, a entrada do usuário, o status e fornece ganchos de ciclo de vida para fins de observabilidade. As opções que passamos incluem:

• api: Isso define o ponto final do seu agente Mastra AI. A porta padrão é a 4111 e também queremos adicionar a rota que suporta respostas em fluxo contínuo.

• onToolCallEste comando é executado sempre que o agente chama uma ferramenta; estamos usando-o para rastrear quais ferramentas nosso agente está chamando.

• onFinishEsta ação é executada depois que o agente conclui uma resposta completa. Mesmo que tenhamos habilitado o streaming, onFinish ainda será executado após o recebimento da mensagem completa e não após cada parte. Aqui, estamos usando isso para rastrear o uso de nossos tokens. Isso pode ser útil para monitorar e otimizar os custos do LLM.

4. Finalmente, acesse o componente ChatUI.jsx no diretório frontend/components para criar a interface do usuário para manter nossa conversa. Em seguida, envolva a resposta em um componente ReactMarkdown para formatar corretamente a resposta do agente.

Etapa 9: Executando o aplicativo

Parabéns! Agora você está pronto para executar o aplicativo. Siga estes passos para iniciar tanto o backend quanto o frontend.

1. Em uma janela de terminal, partindo do diretório raiz, navegue até o diretório de backend e inicie o servidor Mastra:

2. Em outra janela do terminal, partindo do diretório raiz, navegue até o diretório frontend e inicie o aplicativo React:

3. Acesse seu navegador e navegue até:

http://localhost:5173

Você deverá conseguir visualizar a interface de bate-papo. Experimente estas sugestões:

• "Compare LeBron James e Stephen Curry"

• "Quem devo escolher entre Jayson Tatum e Luka Doncic?"

O que vem a seguir: tornar o agente mais inteligente.

Para tornar o assistente mais proativo e as recomendações mais relevantes, adicionarei algumas melhorias importantes na próxima versão.

Busca semântica para notícias da NBA

Existem inúmeros fatores que podem afetar o desempenho do jogador, muitos dos quais não aparecem nas estatísticas brutas. Informações como relatórios de lesões, alterações na escalação ou até mesmo análises pós-jogo só podem ser encontradas em artigos de notícias. Para capturar esse contexto adicional, adicionarei recursos de busca semântica para que o agente possa recuperar artigos relevantes da NBA e incorporar essa narrativa em suas recomendações.

Pesquisa dinâmica com o servidor Elasticsearch MCP

O MCP (Model Context Protocol) está rapidamente se tornando o padrão para a forma como os agentes se conectam às fontes de dados. Vou migrar a lógica de busca para o servidor Elasticsearch MCP, o que permite que o agente construa consultas dinamicamente em vez de depender de funções de busca predefinidas que fornecemos. Isso nos permite usar fluxos de trabalho em linguagem mais natural e reduz a necessidade de escrever manualmente cada consulta de pesquisa. Saiba mais sobre o servidor Elasticsearch MCP e o estado atual do ecossistema aqui.

Essas mudanças já estão em andamento, fique ligado!

Conclusão

Neste blog, criamos um assistente RAG interativo que fornece recomendações personalizadas para o seu time de basquete de fantasia usando JavaScript, Mastra e Elasticsearch. Nós abordamos os seguintes tópicos:

• Fundamentos do RAG agético e como a combinação da autonomia de um agente de IA com as ferramentas para usar o RAG de forma eficaz pode levar a agentes mais dinâmicos e com nuances.

• Elasticsearch e como seus recursos de armazenamento de dados e poderosas agregações nativas o tornam um excelente parceiro como base de conhecimento para um mestrado em Direito (LLM).

• O framework Mastra e como ele simplifica a criação desses agentes para desenvolvedores no ecossistema JavaScript.

Seja você um fanático por basquete, esteja explorando como construir agentes de IA, ou ambos como eu, espero que este blog tenha lhe dado algumas bases para começar. O repositório completo está disponível no GitHub. Sinta-se à vontade para cloná-lo e fazer alterações. Agora, vá ganhar essa liga de fantasia!

O Model Context Protocol (MCP) torna isso possível. Ele conecta perfeitamente a IA conversacional com seus bancos de dados e APIs externas, transformando solicitações complexas em conversas naturais. Embora os LLMs modernos sejam ótimos para entender a linguagem, seu verdadeiro potencial é revelado quando integrados a sistemas do mundo real. O MCP preenche a lacuna entre eles, tornando a interação de dados mais intuitiva e eficiente.

Nesta postagem, exploraremos:

• Arquitetura MCP – Como funciona nos bastidores

• Benefícios de um servidor MCP conectado ao Elasticsearch

• Construindo um servidor MCP com tecnologia Elasticsearch

Tempos emocionantes estão por vir! A integração do MCP com sua pilha Elastic transforma a maneira como você interage com as informações, tornando consultas complexas tão intuitivas quanto conversas cotidianas.

Protocolo de Contexto do Modelo

O Model Context Protocol (MCP), desenvolvido pela Anthropic, é um padrão aberto que conecta modelos de IA a fontes de dados externas por meio de canais bidirecionais seguros. Ele resolve uma grande limitação da IA: acesso em tempo real a sistemas externos, preservando o contexto da conversa.

Arquitetura MCP

A arquitetura do Protocolo de Contexto do Modelo consiste em dois componentes principais:

• Clientes MCP – Assistentes de IA e chatbots que solicitam informações ou executam tarefas em nome dos usuários.

• Servidores MCP – Repositórios de dados, mecanismos de busca e APIs que recuperam informações relevantes ou executam ações solicitadas (por exemplo, chamar APIs externas).

Os servidores MCP expõem quatro funcionalidades principais aos clientes:

• Recursos - Dados estruturados, documentos e conteúdo que podem ser recuperados e usados como contexto para interações de LLM. Isso permite que assistentes de IA acessem informações relevantes de bancos de dados, índices de pesquisa ou outras fontes.

• Ferramentas - Funções executáveis que permitem que os LLMs interajam com sistemas externos, realizem cálculos ou tomem ações no mundo real. Essas ferramentas estendem os recursos de IA além da geração de texto, permitindo que os assistentes acionem fluxos de trabalho, chamem APIs ou manipulem dados dinamicamente.

• Prompts - Modelos de prompts e fluxos de trabalho reutilizáveis para padronizar e compartilhar interações comuns de LLM.

• Amostragem - Solicite conclusões de LLM por meio do cliente para permitir comportamentos de agente sofisticados, mantendo a segurança e a privacidade.

Servidor MCP + Elasticsearch

Os sistemas tradicionais de Recuperação-Geração Aumentada (RAG) recuperam documentos com base em consultas do usuário, mas o MCP vai um passo além: ele permite que agentes de IA construam e executem tarefas dinamicamente em tempo real. Isso permite que os usuários façam perguntas em linguagem natural como:

• "Mostre-me todos os pedidos acima de US$ 500 do mês passado."

• "Quais produtos receberam mais avaliações de 5 estrelas?"

E obtenha respostas instantâneas e precisas, sem precisar escrever uma única consulta.

O MCP consegue isso por meio de:

• Seleção dinâmica de ferramentas – Os agentes escolhem de forma inteligente as ferramentas certas expostas por meio de servidores MCP com base na intenção do usuário. LLMs “mais inteligentes” geralmente são melhores em selecionar as ferramentas certas com os argumentos apropriados com base no contexto.

• Comunicação bidirecional – Agentes e fontes de dados trocam informações fluidamente, refinando consultas conforme necessário (por exemplo, primeiro mapeie o índice de pesquisa e só então construa a consulta ES).

• Orquestração de múltiplas ferramentas – Os fluxos de trabalho podem aproveitar ferramentas de vários servidores MCP simultaneamente.

• Contexto persistente – Os agentes lembram interações anteriores, mantendo a continuidade entre as conversas.

Um servidor MCP conectado ao Elasticsearch desbloqueia uma poderosa arquitetura de recuperação em tempo real. Os agentes de IA podem explorar, consultar e analisar dados do Elasticsearch sob demanda. Seus dados podem ser pesquisados por meio de uma interface de bate-papo simples.

Além de apenas recuperar dados, o MCP possibilita ações. Ele se integra a outras ferramentas para acionar fluxos de trabalho, automatizar processos e fornecer insights aos sistemas de análise. Ao separar a pesquisa da execução, o MCP mantém os aplicativos com tecnologia de IA flexíveis, atualizados e perfeitamente integrados aos fluxos de trabalho do agente.

Prático: servidor MCP para conversar com seus dados do Elasticsearch

Para interagir com o Elasticsearch por meio de um servidor MCP, precisamos de pelo menos funções para:

• Recuperar índices

• Obter mapeamentos

• Realizar pesquisas usando o Query DSL do Elasticsearch

Nosso servidor é escrito em TypeScript e usaremos o SDK oficial do MCP TypeScript. Para configuração, recomendamos instalar o aplicativo Claude Desktop (a versão gratuita é suficiente), pois ele inclui um cliente MCP integrado. Nosso servidor MCP essencialmente expõe o cliente oficial do JavaScript Elasticsearch por meio de ferramentas MCP.

Vamos começar definindo o cliente Elasticsearch e o servidor MCP:

Usaremos as seguintes ferramentas de servidor MCP que podem interagir com o Elasticsearch:

• Listar índices (list_indices): esta ferramenta recupera todos os índices disponíveis do Elasticsearch, fornecendo detalhes como nome do índice, status de integridade e contagem de documentos.

• Obter mapeamentos (get_mappings): esta ferramenta busca os mapeamentos de campos para um índice especificado do Elasticsearch, ajudando os usuários a entender a estrutura e os tipos de dados dos documentos armazenados.

• Pesquisar (search): Esta ferramenta executa uma pesquisa no Elasticsearch usando um DSL de consulta fornecido. Ele habilita automaticamente destaques para campos de texto, facilitando a identificação de resultados de pesquisa relevantes.

A implementação completa do servidor Elasticsearch MCP está disponível no repositório elastic/mcp-server-elasticsearch .

Converse com seu índice

Vamos explorar como configurar o servidor Elasticsearch MCP para que você possa fazer perguntas em linguagem natural sobre seus dados, como "Encontrar todos os pedidos acima de US$ 500 do mês passado".

Configure seu aplicativo Claude Desktop

• Abra o aplicativo Claude Desktop

• Navegue até Configurações > Desenvolvedor > Servidores MCP

• Clique em "Editar configuração" e adicione esta configuração ao seu claude_desktop_config.json:

Observação: esta configuração utiliza o pacote npm @elastic/mcp-server-elasticsearch publicado pela Elastic. Se você quiser desenvolver localmente, poderá encontrar mais detalhes sobre como configurar o servidor Elasticsearch MCP aqui.

Preencha seu índice Elasticseach

• Você pode usar nossos dados de exemplo para preencher o índice de "pedidos" para esta demonstração

• Isso permitirá que você tente consultas como "Encontrar todos os pedidos acima de US$ 500 do mês passado"

Comece a usar

• Abra uma nova conversa no aplicativo Claude Desktop

• O servidor MCP se conectará automaticamente

• Comece a fazer perguntas sobre seus dados do Elasticsearch!

Confira esta demonstração para ver como é fácil consultar seus dados do Elasticsearch usando linguagem natural:

Como funciona?

Quando perguntado "Encontre todos os pedidos acima de US$ 500 do mês passado", o LLM reconhece a intenção de pesquisar o índice do Elasticsearch com restrições especificadas. Para realizar uma busca eficaz, o agente deve:

• Descubra o nome do índice: orders

• Entenda os mapeamentos do índice orders

• Crie o DSL de consulta compatível com mapeamentos de índice e, finalmente, execute a solicitação de pesquisa

Essa interação pode ser representada como:

Conclusão

O Model Context Protocol aprimora a maneira como você interage com os dados do Elasticsearch, permitindo conversas em linguagem natural em vez de consultas complexas. Ao unir recursos de IA com seus dados, o MCP cria um fluxo de trabalho mais intuitivo e eficiente que mantém o contexto em todas as suas interações.

O servidor Elasticsearch MCP está disponível como um pacote npm público (@elastic/mcp-server-elasticsearch), tornando a integração simples para desenvolvedores. Com configuração mínima, sua equipe pode começar a explorar dados, acionar fluxos de trabalho e obter insights por meio de conversas simples.

Pronto para experimentar isso você mesmo? Experimente o servidor Elasticsearch MCP hoje mesmo e comece a conversar com seus dados.

1. Clone o repositório: Baixe o código da ferramenta do GitHub usando git clone https://github.com/elastic/elasticsearch-labs/supporting-blog-content/serverless-ai-agent ae navegue até o diretório com cd serverless-ai-agent.

2. Configurar ambiente: Crie um ambiente virtual (opcional) com python -m venv venv e ative-o (source venv/bin/activate ou venv\Scripts\activate no Windows). Em seguida, instale os pacotes Python necessários usando pip install -r requirements.txt.

3. Configure as credenciais: Crie um arquivo .env na raiz do projeto e preencha-o com o URL da API do Elasticsearch (ES_URL), a chave da API (API_KEY), a região (REGION) e a chave da API do OpenAI (OPENAI_API_KEY).

4. Execute a ferramenta: Execute a ferramenta executando python main.py em seu terminal. Isso iniciará o agente de IA e exibirá uma tela para que você insira seus comandos.

5. Gerencie projetos com linguagem natural: interaja com a ferramenta usando comandos em inglês simples, como "Criar um projeto serverless chamado my_project", "Obter o status do projeto serverless chamado my_project" ou "Excluir o projeto serverless chamado my_project". A IA interpretará seus comandos e executará as funções correspondentes.

Histórico

Esta pequena ferramenta de linha de comando permite gerenciar seus projetos Serverless Elasticsearch em linguagem simples. Ele se comunica com uma IA (neste caso, a OpenAI) para entender o que você quer dizer e chamar as funções corretas usando o LlamaIndex!

O que o agente de IA Serverless do Elasticsearch pode fazer?

• Criar um projeto: Inicie um novo projeto Elasticsearch sem servidor.

• Excluir um projeto: Remove um projeto existente (sim, ele limpa tudo depois).

• Obtenha o status do projeto: verifique como está o andamento do seu projeto.

• Obtenha detalhes do projeto: Descubra todas as informações relevantes sobre o seu projeto.

Confira o código no GitHub.

Como funciona o agente de IA sem servidor do Elasticsearch

Quando você digita algo como:

"Crie um projeto sem servidor chamado my_project"

…eis o que acontece nos bastidores:

• Entrada e contexto do usuário: Seu comando em linguagem natural é enviado ao agente de IA.

• Descrição das funções: O agente de IA já conhece algumas funções — como create_ess_project, delete_ess_project, get_ess_project_status e get_ess_project_details — porque fornecemos descrições detalhadas. Essas descrições informam à IA o que cada função faz e quais parâmetros elas precisam.

• Processamento LLM: Sua consulta, juntamente com as informações da função, é enviada para o LLM. Isso significa que a IA vê:

  • Consulta do usuário: Sua instrução em linguagem simples.

  • Funções e descrições disponíveis: Detalhes sobre o que cada ferramenta faz para que você possa escolher a mais adequada.

  • Informações de contexto/histórico do chat: Como se trata de uma conversa, o sistema se lembra do que foi dito anteriormente.

• Chamada e resposta de função: A IA determina qual função chamar, passa os parâmetros corretos (como o nome do seu projeto) e, em seguida, a função é executada. A resposta será enviada a você em um formato amigável.

Resumindo, estamos enviando ao LLM tanto sua consulta em linguagem natural quanto uma lista de descrições detalhadas das ferramentas para que ele possa "entender" e escolher a ação correta para sua solicitação.

Configure o agente de IA

Pré-requisitos:

Antes de executar o agente de IA, certifique-se de que a seguinte configuração esteja correta:

1. Python (versão 3.7 ou posterior) instalado.

2. Configuração de uma conta serverless do Elasticsearch no Elastic Cloud.

3. Conta OpenAI para interagir com o modelo de linguagem.

Passos:

1. Clone o repositório:

2. Criar um ambiente virtual (opcional, mas recomendado): Se você estiver enfrentando problemas relacionados ao ambiente, pode configurar um ambiente virtual para isolamento:

3. Instale as dependências: Certifique-se de que todas as dependências necessárias estejam instaladas executando o seguinte comando:

4. Configure seu ambiente: Crie um arquivo .env Arquivo na raiz do projeto com as seguintes variáveis. Aqui está um exemplo de arquivo .env.example para te ajudar:

Certifique-se de que você tem os valores corretos para ES_URL, API_KEY e OPENAI_API_KEY. Você pode encontrar suas chaves de API nos respectivos painéis de serviço.

5. Arquivo de Projetos: A ferramenta usa um arquivo projects.json para armazenar seus mapeamentos de projetos (nomes de projetos para seus detalhes). Este arquivo será criado automaticamente caso ainda não exista.

Executando o agente de IA

Você verá uma mensagem como esta:

Digite o comando e o agente de IA fará a sua mágica! Quando terminar, digite exit ou quit para sair.

Mais alguns detalhes

• Integração com o LLM: O LLM recebe tanto a sua consulta quanto descrições detalhadas de cada função disponível. Isso ajuda a entender o contexto e a decidir, por exemplo, se deve chamar create_ess_project ou delete_ess_project.

• Descrição das ferramentas: Cada ferramenta de função (criada usando FunctionTool.from_defaults) Possui uma descrição amigável. Essa descrição está incluída no prompt enviado ao LLM para que ele "saiba" quais ações estão disponíveis e o que cada ação espera.

• Persistência: Seus projetos e seus detalhes são salvos em projects.json. Assim você não precisa inserir as informações novamente toda vez.

• Registro detalhado: O agente está configurado para o modo detalhado, o que é ótimo para depuração e para ver como suas instruções são traduzidas em chamadas de função.

Exemplo de utilização do agente de IA do Elasticsearch