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.

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.

1. Utilizando a API _mapping para recuperar informações de campo

2. Utilizando a API _search para exibir valores de campo

3. Exibição de subcampos

4. _source sintética

5. Campos de tempo de execução

1. Utilizando a API _mapping para recuperar informações de campo

A API _mapping permite recuperar a definição de mapeamento para um índice ou vários índices. Isso inclui informações sobre os campos, seus tipos de dados e outras propriedades. Para recuperar o mapeamento de um índice específico, utilize a seguinte solicitação:

Por exemplo, se você tiver um índice chamado my_index, poderá recuperar seu mapeamento com a seguinte solicitação:

A resposta incluirá a definição de mapeamento para o índice, que contém informações sobre os campos e suas propriedades.

Também é possível recuperar o mapeamento de um campo específico. Isso pode ser útil se o seu mapeamento for muito extenso e você quiser se concentrar apenas em um campo específico. Para obter o mapeamento de um campo específico, utilize a seguinte solicitação:

Você também pode recuperar os mapeamentos de vários campos separando seus nomes por vírgulas, como na seguinte solicitação:

2. Usando a API _search para exibir valores de campo

Para exibir os valores dos campos em um índice do Elasticsearch, você pode usar a API _search . A API _search oferece várias maneiras de controlar quais campos são retornados; as duas principais são:

1. _sourceO campo _source contém o corpo original do documento JSON exatamente como foi indexado, incluindo quaisquer alterações feitas pelos pipelines de ingestão ou etapas de pré-processamento. Para exibir campos específicos do documento de origem, implemente a filtragem de origem, como veremos a seguir.

2. fieldsO parâmetro fields permite recuperar campos específicos dos seus documentos ao realizar uma pesquisa, com base no mapeamento do índice. Ao contrário de _source, fields também pode retornar valores de campos armazenados, valores de documentos ou campos de tempo de execução sem fazer referência a _source, embora para campos padrão sem valores de documentos ou configurações armazenadas, ele recorra a _source. Isso pode trazer muitos benefícios, como melhoria de desempenho e outros, como veremos a seguir.

Usando o campo _source

Por padrão, a API _search retorna o campo _source , que contém o documento JSON original que foi indexado. Para exibir campos específicos, você pode adicionar filtros no parâmetro _source da solicitação de pesquisa; isso é chamado de filtragem de origem.

Aqui está um exemplo de uma solicitação de pesquisa que retorna os valores dos campos title e author para documentos no índice my_index :

Neste exemplo, o parâmetro _source especifica os campos a serem retornados.

Se você precisar de ainda mais controle, pode usar as propriedades includes e excludes do objeto _source . Por exemplo, a consulta abaixo retorna o campo de nível superior title e todos os subcampos de author exceto author.description.

Neste exemplo, usamos o padrão author.* para recuperar todos os subcampos diretos do objeto author . Então excluímos explicitamente author.description para que apenas os outros campos de autor sejam retornados. Note que isso não traz nenhuma melhoria de desempenho, já que ainda precisa carregar e analisar o JSON de origem, mas pode reduzir o tamanho da resposta enviada pela rede.

Usando o parâmetro de campos

Você pode usar o parâmetro fields para filtrar os campos retornados na resposta da pesquisa. O uso de fields em vez de _source oferece diversas vantagens, incluindo:

• Desempenho aprimorado: fields pode retornar valores diretamente de campos armazenados ou valores de documentos sem ter que carregar o _source completo, tornando o tamanho da carga útil da resposta menor.

• Saída formatada: Para campos padrão, fields pode recorrer a _source para obter os valores, mas ele analisa o mapeamento do índice para formatar corretamente a saída, como datas formatadas, tornando-as consistentes com o que é usado para agregações e classificação.

• Acesso a campos de tempo de execução: fields pode retornar campos de tempo de execução, que não existem no _source original.

• Você pode encontrar mais benefícios aqui.

Por exemplo, para retornar apenas os campos title e author no índice my_index , você pode usar a seguinte solicitação de pesquisa:

Na consulta acima, definimos o campo _source como falso para não retornarmos o documento de origem. Isso pode minimizar drasticamente o tamanho da carga útil da resposta, mas lembre-se de que isso só funciona porque os campos title e author são do tipo de campo keyword , que têm doc_values habilitado por padrão. Se o campo não tiver doc_values habilitado e _source estiver definido como falso, o Elasticsearch não terá como recuperá-los e eles serão ignorados na resposta.

É importante notar que a resposta fields sempre retorna uma matriz de valores para cada campo, mesmo que haja apenas um único valor. Isso ocorre porque o Elasticsearch não possui um tipo de array dedicado, e qualquer campo pode ter vários valores. Para obter mais informações sobre arrays no Elasticsearch, clique aqui.

Outras formas de recuperar campos

Embora a recuperação de campos usando _source ou fields sejam os métodos recomendados, existem outros métodos disponíveis para casos de uso específicos, como:

Campos de valor do documento: Se você quiser evitar _source completamente, você pode pesquisar usando o parâmetro docvalue_fields . Os valores do documento armazenam os mesmos valores de campo que _source , mas em uma estrutura de dados em disco, otimizada para classificação e agregações.

Como é separado dos valores armazenados com _source, você pode solicitar campos específicos sem carregar todo o _source. Isso é útil se você estiver consultando documentos grandes, mas precisar apenas de alguns campos pequenos que suportem valores do tipo "doc". Outro caso de uso para usar docvalue_fields é quando você deseja usar formatação personalizada nos campos date e numeric , como veremos no exemplo abaixo.

Observe que isso só funciona para campos que você habilita doc_values ou para tipos de campo que o têm habilitado por padrão, como keyword, date, tipos numéricos e boolean, não para text ou annotated_text.

Neste exemplo, usamos o parâmetro docvalue_fields para recuperar os campos title, author e published sem carregar o documento _source completo:

Quando esta consulta é executada, o Elasticsearch obtém os valores diretamente de seu armazenamento colunar em disco, em vez de referenciar o _source para cada documento. O campo published é retornado com o formato epoch_millis em vez do formato padrão, graças ao parâmetro format fornecido na consulta.

Campos armazenados: Se você marcou explicitamente campos específicos como armazenados no mapeamento, você pode usar o parâmetro stored_fields para filtrar esses campos. Isso é útil se você deseja respostas resumidas apenas com esses campos específicos ou para campos que você armazenou deliberadamente para recuperação posterior. É armazenado separadamente de _source, portanto, este método também é útil para evitar a necessidade de carregar _source.

É importante notar que esta opção está desativada por padrão e geralmente não é recomendada. Em vez disso, utilize a filtragem de origem para retornar determinados subconjuntos do documento de origem original.

Na consulta de exemplo abaixo, usamos o parâmetro stored_fields para recuperar o campo summary , que tem a configuração de mapeamento de índice de ”store”: true.

Quando esta consulta é executada, o Elasticsearch verifica se este campo foi marcado com ”store”: true, se não o encontrar, irá ignorar o campo completamente.

3. Exibição de subcampos

Se o seu índice contiver subcampos, você pode usar a notação de ponto para especificar o caminho do campo no parâmetro fields . Note que os subcampos são diferentes do tipo de campo aninhado. Por exemplo, se você tiver um subcampo chamado address.city, poderá incluí-lo na resposta da pesquisa desta forma:

Neste exemplo, a resposta da pesquisa incluirá os valores dos campos title, author e address.city .

4. Fonte sintética

Se você quiser manter a funcionalidade de usar _source , mas também economizar espaço em disco, você tem a opção de usar _source sintético em seu mapeamento de índice. _source sintético é um recurso que permite ao Elasticsearch reconstruir o _source a partir de dados existentes, como campos armazenados e valores de documentos, mesmo quando _source está desativado. Isso permite economizar bastante espaço de armazenamento, ao custo de velocidades ligeiramente menores no momento da consulta, já que a reconstrução ocorre em tempo real. Ative este recurso usando os valores abaixo nas configurações do seu índice:

Algumas vantagens de usar _source sintético incluem: exibição do documento completo ao usar a API _search , filtragem de origem e compatibilidade com outros recursos e ferramentas como o Kibana que esperam que _source esteja disponível, tudo isso evitando a necessidade de armazenar o documento _source completo.

5. Campos de tempo de execução

Os campos de tempo de execução permitem definir campos com script no momento da consulta ou no mapeamento do índice, dentro de um bloco de tempo de execução. Esses campos nunca são indexados, portanto, adicionar um campo de tempo de execução não aumenta o tamanho do índice, mas nunca aparecerá em _source. Os campos de tempo de execução definidos no mapeamento são persistentes e estão disponíveis para todas as consultas, enquanto os campos de tempo de execução definidos no momento da consulta são temporários e estão disponíveis apenas nessa solicitação de pesquisa.

A principal vantagem de usar campos em tempo de execução é a capacidade de adicionar campos aos documentos depois de já os ter importado, simplificando as decisões de mapeamento. Os campos de tempo de execução também são ótimos para enriquecer seus documentos com valores que não existem no documento original, mas são gerados por meio de um script, como formatar uma string ou calcular uma pontuação.

Vale ressaltar também que os campos de tempo de execução podem prejudicar o desempenho, pois será necessário executar um script para cada documento no conjunto de resultados. Para recuperar um campo de tempo de execução, você também pode usar o parâmetro fields na API _search .

Conclusão

A exibição de campos de um índice Elasticsearch pode variar desde a simples recuperação de valores usando o mapeamento de índice ou o _source, até métodos mais avançados usando fields, docvalue_fields ou campos de tempo de execução para maior controle e eficiência. Compreender as vantagens e desvantagens de diferentes métodos é fundamental para otimizar suas experiências de busca. Seja para otimizar payloads, enriquecer documentos ou usar dados sintéticos _source para economizar armazenamento, o Elasticsearch oferece diversas ferramentas e recursos para encontrar os dados que você precisa, da maneira que você precisa. Essas técnicas podem ajudá-lo a entender a estrutura de seus dados, identificar campos específicos e solucionar problemas.

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 que é o Protocolo de Contexto do Modelo (MCP)?

Para quem não conhece, o Model Context Protocol é um padrão aberto que oferece uma maneira estruturada e bidirecional de conectar modelos de IA a várias fontes de dados e ferramentas, permitindo que eles gerem respostas mais relevantes e informadas. É comumente chamada de “porta USB-C para aplicativos de IA”.

Aqui está um diagrama arquitetônico que destaca sua natureza bidirecional:

Esta é uma mudança significativa para os profissionais de IA, pois um dos principais desafios para dimensionar aplicativos de IA é ter que criar integrações personalizadas para cada nova fonte de dados. O MCP oferece uma arquitetura sustentável e reutilizável para gerenciar e fornecer contexto aos modelos. É independente de modelo, independente de servidor e totalmente de código aberto.

O MCP é a mais recente iteração de uma linhagem de especificações de API que buscam padronizar a integração entre aplicativos. No passado, tínhamos OpenAPI para serviços RESTful, GraphQL para consulta de dados e gRPC para comunicação de microsserviços. O MCP não apenas compartilha o rigor estruturado dessas especificações mais antigas, mas também as traz para um ambiente de IA generativo, facilitando a conexão de agentes em diferentes sistemas sem conectores personalizados. De muitas maneiras, o MCP pretende fazer pelos agentes de IA o que o HTTP fez pela web. Assim como o HTTP padronizou a comunicação entre navegadores e sites, o MCP busca padronizar como os agentes de IA interagem com o mundo de dados ao seu redor.

MCP vs. outros protocolos de agentes

O cenário de protocolos de agentes está se expandindo rapidamente, com mais de uma dúzia de padrões emergentes competindo para definir como os agentes interagem. Laurie Voss, do LlamaIndex, descreve como a maioria pode ser categorizada em dois tipos: protocolos interagentes, que se concentram em agentes conversando entre si, e protocolos orientados a contexto, como o MCP, que se concentram em fornecer contexto estruturado aos LLMs.

Outros protocolos populares, como o A2A (Agent to Agent) do Google, o ACP (Agent Communication Protocol) da Cisco e da IBM e o Agora, visam permitir negociações entre agentes, construção de coalizões e até mesmo sistemas de identidade descentralizados. O MCP adota uma abordagem um pouco mais pragmática, pois se concentra em como os agentes acessam ferramentas e dados e não necessariamente como eles se comunicam entre si (embora o MCP também possa permitir isso no futuro de diferentes maneiras).

Atualmente, o que diferencia o MCP é sua tração e impulso. Assim como o React nos primeiros dias dos frameworks de front-end, o MCP começou com um problema de nicho e agora é um dos protocolos de agente mais adotados e extensíveis na prática.

Recapitulação da cúpula: Prioridades em evolução para o MCP

A cúpula contou com palestrantes de colaboradores da Anthropic, Okta, OpenAI, AWS, GitHub e muitos outros. As palestras abrangeram desde melhorias no protocolo principal até implementações no mundo real e delinearam prioridades imediatas e de longo prazo. Essas palestras refletiram uma mudança da experimentação inicial e da simples chamada de ferramentas para a construção de sistemas de IA confiáveis, escaláveis e modulares usando o MCP como base.

Vários palestrantes sugeriram um futuro em que o MCP será mais do que apenas um protocolo de encanamento; ele poderá se tornar a base de uma web nativa de IA. Assim como o JavaScript permitiu que os usuários clicassem e interagissem com páginas da web, o MCP poderia permitir que agentes realizassem as mesmas ações em nosso nome. Por exemplo, no comércio eletrônico, em vez de os usuários navegarem manualmente até um site para comprar, eles poderiam simplesmente dizer a um agente para fazer login, encontrar um produto específico, adicioná-lo ao carrinho e finalizar a compra.

Isso não é apenas pura especulação e exagero; o PayPal apresentou seu novo kit de ferramentas para agentes e servidor MCP na cúpula, o que possibilita exatamente essa experiência de comércio com agentes. Com o MCP fornecendo acesso seguro e confiável a ferramentas e fontes de dados, os agentes não apenas lerão a web, mas também poderão agir com base nela. Hoje, o MCP já é um padrão poderoso e com muita força e, no futuro, pode se tornar o padrão de interações de usuários aprimoradas por IA na web.

Atualizações do projeto MCP: transporte, elicitação e ferramentas estruturadas

Jerome Swannack, um dos principais colaboradores do MCP, compartilhou algumas atualizações da especificação do protocolo dos últimos 6 meses. Os principais objetivos dessas mudanças são:

1. Para habilitar o MCP remoto com a adição do Streamable HTTP

2. Para permitir modelos de interação de agentes mais ricos com a adição de Elicitação e Esquemas de Saída de Ferramentas

Como o MCP é de código aberto, mudanças como o Streamable HTTP já estão disponíveis para os desenvolvedores implementarem. Os esquemas de elicitação e saída de ferramentas ainda não foram lançados; eles estão em fase de rascunho e podem evoluir.

HTTP transmissível (lançado em 26/03/2025): Uma atualização técnica impactante foi a introdução do HTTP transmissível como um novo mecanismo de transporte. Isso substitui eventos enviados pelo servidor (SSE) por um modelo bidirecional mais escalável que oferece suporte à codificação de transferência em blocos e à entrega progressiva de mensagens em uma única conexão HTTP. Isso permite que você implante servidores MCP em infraestrutura de nuvem como AWS Lambda e ofereça suporte a restrições de rede corporativa sem conexões de longa duração ou necessidade de sondagem.

Elicitação (lançado em 18/06/2025): a elicitação permite que os servidores definam um esquema de como eles querem que o contexto seja estruturado a partir de um cliente. Basicamente, o servidor pode descrever o que precisa e o tipo de entrada que espera. Isso tem algumas implicações: para os construtores de servidores, eles podem criar interações de agentes mais complexas. Para construtores de clientes, eles podem implementar interfaces de usuário dinâmicas que se adaptam a esses esquemas. No entanto, a elicitação não deve ser usada para extrair informações confidenciais ou pessoalmente identificáveis dos usuários. Os desenvolvedores devem seguir as melhores práticas para garantir que os prompts de elicitação permaneçam seguros e apropriados, especialmente à medida que o MCP amadurece. Isso está ligado a preocupações de segurança mais amplas que discutiremos mais adiante neste post.

Esquemas de saída de ferramentas (lançados em 18/06/2025): este conceito permite que o cliente e o LLM conheçam as formas de saída da ferramenta com antecedência. Os esquemas de saída da ferramenta permitem que os desenvolvedores descrevam o que se espera que uma ferramenta retorne. Esses esquemas abordam uma das principais limitações da chamada direta de ferramentas, que é o uso ineficiente da janela de contexto. A janela de contexto é considerada um dos recursos mais importantes ao trabalhar com LLMs e, quando você chama uma ferramenta diretamente, ela retorna conteúdo bruto que é totalmente inserido no contexto do LLM. Os esquemas de saída da ferramenta podem ajudar você a fazer melhor uso dos seus tokens e da janela de contexto, permitindo que o servidor MCP forneça dados estruturados. Aqui estão algumas práticas recomendadas sobre ferramentas em geral.

Juntas, essas novas atualizações e adições futuras ajudarão o MCP a se tornar um protocolo de agente mais modular, tipado e pronto para produção.

Recursos de energia subutilizados: amostragem e raízes

Embora não seja novidade na especificação MCP, tanto a amostragem quanto as raízes foram destacadas durante a palestra. Essas duas primitivas são atualmente negligenciadas e pouco exploradas, mas podem contribuir significativamente para interações mais ricas e seguras entre agentes.

Amostragem - Os servidores podem solicitar conclusões do cliente: A amostragem permite que os servidores MCP solicitem conclusões do LLM do lado do cliente. Isso aumenta a natureza bidirecional do protocolo, onde o servidor não está apenas respondendo às solicitações; ele pode solicitar e pedir ao modelo do cliente para gerar uma resposta. Isso permite que o cliente mantenha controle total sobre o custo, a segurança e qual modelo o servidor MCP usa. Portanto, no caso de usar um servidor MCP externo com um modelo pré-configurado, você não precisará fornecer suas próprias chaves de API ou configurar sua própria assinatura para esse modelo, pois o servidor pode simplesmente solicitar o modelo já conectado ao cliente. Isso permite comportamentos de agentes mais complexos e interativos.

Raízes - Acesso com escopo aos recursos: As raízes foram projetadas para fornecer uma maneira para os clientes informarem os servidores sobre recursos e espaços de trabalho relevantes nos quais se concentrar. Isso é útil para definir o escopo no qual os servidores operam. É importante observar que as raízes são “informativas e não estritamente obrigatórias”, o que significa que elas não definem direitos ou permissões para servidores ou agentes MCP. Em outras palavras, você não pode confiar apenas nas raízes para impedir que um servidor ou agente execute determinadas ferramentas ou realize ações de gravação. Com raízes, as permissões ainda devem ser manipuladas no lado do cliente com mecanismos para aprovação do usuário. Além disso, os desenvolvedores ainda devem estar atentos ao uso de servidores projetados para respeitar os limites definidos pelas raízes e usar as melhores práticas.

Autenticação para agentes: OAuth 2.1 e metadados protegidos

Esta seção se concentra no OAuth 2.1, que é a iteração mais recente do OAuth 2.0 que remove fluxos inseguros e consolida as melhores práticas.

O suporte ao OAuth era um tópico muito aguardado, especialmente porque a segurança e a escalabilidade são vistas como os principais obstáculos que impedem o MCP de se tornar o padrão para conectar agentes a ferramentas. Aaron Parecki (editor do OAuth 2.1 e especialista em padrões de identidade na Okta) discutiu como o MCP pode adotar um fluxo OAuth limpo e escalável que alivia a maior parte da complexidade dos desenvolvedores de servidores. A especificação oficial de autorização OAuth 2.1 foi publicada recentemente na última revisão do protocolo em 18/06/2025.

Nesta implementação, as responsabilidades do OAuth podem ser divididas entre o cliente MCP e o servidor. A maior parte do fluxo de autenticação é iniciada e gerenciada pelo cliente MCP, envolvendo apenas o servidor no final para receber e verificar o token seguro. Essa divisão ajuda a resolver um problema crítico de dimensionamento de como autenticar em muitas ferramentas sem exigir que os desenvolvedores configurem cada conexão e garante que os desenvolvedores do servidor MCP não precisem se tornar especialistas em OAuth.

Dois destaques principais da palestra:

1. Metadados de recursos protegidos: os servidores MCP podem publicar um arquivo JSON descrevendo sua finalidade, pontos de extremidade e métodos de autenticação. Isso permite que os clientes iniciem fluxos OAuth apenas com a URL do servidor, simplificando o processo de conexão. Saiba mais: Vamos corrigir o OAuth no MCP

2. Suporte para IDPs e SSO: as empresas podem integrar provedores de identidade para gerenciar o acesso centralmente. Isto é uma vitória tanto para a experiência do usuário quanto para a segurança. Os usuários não precisariam clicar em 10 telas de consentimento diferentes e as equipes de segurança poderiam ter visibilidade de cada conexão.

Ao enviar a lógica do OAuth para o cliente e confiar nos metadados dos servidores, o ecossistema MCP evita um grande gargalo. Isso alinha o MCP mais de perto com a forma como as APIs modernas são protegidas nos ambientes de produção atuais.

Leitura adicional: OAuth 2 simplificado.

Desafios de segurança em um ecossistema componível

Novos desenvolvimentos também trazem novas superfícies de ataque. Arjun Sambamoorthy, da Cisco, lista diversas ameaças importantes no cenário do MCP, incluindo:

Ameaça

Descrição

Remediação e melhores práticas

Injeção imediata e envenenamento por ferramentas

Uma maneira de injetar um prompt malicioso dentro do contexto do sistema LLM ou da descrição da ferramenta, fazendo com que o LLM execute ações não intencionais, como ler arquivos ou vazar dados.

Use ferramentas como o MCP Scan para realizar verificações nos metadados das ferramentas. Valide descrições e parâmetros antes de incluí-los nos prompts. Por fim, considere implementar aprovações de usuários para ferramentas de alto risco. Para mais detalhes, consulte o guia de injeção rápida do OWASP na lista de leitura adicional abaixo da tabela.

Ataques de amostragem

No contexto do MCP, a amostragem abre a porta para o servidor MCP realizar ataques de injeção rápida no LLM.

Desative a amostragem para servidores não confiáveis e considere adicionar aprovações humanas para solicitações de amostragem.

Servidores MCP maliciosos

Nas coleções atuais de servidores MCP, é difícil verificar cada um deles para garantir a segurança. Servidores invasores podem coletar e expor silenciosamente seus dados a agentes maliciosos.

Conecte-se somente a servidores MCP de registros confiáveis ou listas internas. Execute servidores de terceiros em contêineres com sandbox.

Ferramentas de instalação de MCP maliciosas

Instaladores de linha de comando e scripts são convenientes para implementar rapidamente servidores ou ferramentas MCP, mas você pode acabar instalando código comprometido e não verificado.

Instale em ambientes sandbox e valide assinaturas de pacotes. Nunca atualize automaticamente a partir de fontes não verificadas.

Para combater ainda mais isso, Arjun sugere um registro MCP confiável para lidar com todas as verificações (um tópico que estava em destaque — para mais detalhes, veja os dois principais itens na lista de leitura abaixo), bem como usar esta lista de verificação de segurança.

Leitura adicional:

• Melhores práticas oficiais de segurança do MCP

• Top 10 de inscrições para o OWASP LLM

• Pesquisa de ameaças HiddenLayer

• Varredura MCP

• Guia de injeção rápida OWASP

O que vem a seguir: Registros, governança e ecossistema

Um registro centralizado do MCP está em desenvolvimento e foi um dos tópicos mais consistentemente discutidos na cúpula. O ecossistema de servidores atual sofre de fragmentação, baixa confiança e capacidade de descoberta. É difícil para os desenvolvedores encontrar servidores MCP, verificar o que eles fazem e instalá-los com segurança, especialmente em um ecossistema descentralizado onde os metadados podem estar incompletos ou falsificados.

Um registro centralizado aborda esses pontos problemáticos diretamente, agindo como uma fonte confiável de verdade, melhorando a capacidade de descoberta, garantindo a integridade dos metadados do servidor e reduzindo o risco de instalação de ferramentas maliciosas.

Os objetivos do registro MCP são:

• Oferecendo uma única fonte de verdade para metadados do servidor (o que um servidor faz, como autenticar, instalá-lo e chamá-lo)

• Eliminar registros de terceiros incompletos e fragmentação para que, quando um servidor quiser ser registrado, ele não precise atualizar todos os outros registros na Internet.

• Fornecendo um fluxo de registro de servidor que inclui uma ferramenta CLI e um arquivo server.json que contém os metadados mencionados anteriormente.

A esperança mais ampla é que um registro confiável ajude a dimensionar o ecossistema com segurança, permitindo que os desenvolvedores criem e compartilhem novas ferramentas com confiança.

Governança foi outra questão prioritária para a Anthropic. Eles deixaram claro que o MCP deve permanecer aberto e orientado pela comunidade, mas dimensionar esse modelo de governança ainda é um trabalho em andamento. Atualmente, eles estão buscando ajuda nessa área e pedem que qualquer pessoa que tenha experiência com governança em protocolos de código aberto entre em contato. Isso nos leva ao outro tópico que eu queria mencionar. Durante o evento, os palestrantes enfatizaram que o ecossistema só pode crescer com contribuições dos desenvolvedores internos. É preciso haver um esforço concentrado para tornar o MCP o novo padrão da web e se destacar dos outros protocolos de agentes populares.

MCP no mundo real: estudos de caso e demonstrações

Várias organizações compartilharam como o MCP já está sendo usado em aplicações práticas:

• PayPal - Servidor MCP para comércio de agentes: o PayPal apresentou seu novo kit de ferramentas de agente e servidor MCP, que pode mudar fundamentalmente a experiência de compra do usuário. Em vez de vasculhar as redes sociais para encontrar itens, comparar preços e finalizar a compra, os usuários podem conversar com um agente que se conecta ao servidor MCP do PayPal para lidar com todas essas ações.

• EpicAI.pro - Jarvis: Os desenvolvimentos no MCP nos deixam cada vez mais perto de ter um assistente real do tipo Jarvis. Para quem não conhece os filmes do Homem de Ferro, Jarvis é um assistente de IA que usa linguagem natural, responde a entradas multimodais, tem latência zero ao responder, é proativo em antecipar as necessidades do usuário, gerencia integrações automaticamente e pode alternar o contexto entre dispositivos e locais. Se imaginarmos Jarvis como um assistente robótico físico, o MCP dá a Jarvis “mãos” ou a capacidade de lidar com tarefas complexas.

• Postman - Gerador de servidor MCP: fornece uma experiência de carrinho de compras para solicitações de API, onde você pode escolher diferentes solicitações de API, colocá-las em uma cesta e baixar a cesta inteira como um servidor MCP.

• Bloomberg - A Bloomberg resolveu um gargalo importante no desenvolvimento empresarial de GenAI. Com quase 10.000 engenheiros, eles precisavam de uma maneira padronizada de integrar ferramentas e agentes entre as equipes. Com o MCP, eles transformaram suas ferramentas internas em componentes modulares e remotos que os agentes podem facilmente chamar em uma interface unificada. Isso permitiu que seus engenheiros contribuíssem com ferramentas em toda a organização, enquanto as equipes de IA se concentravam na criação de agentes em vez de integrações personalizadas. A Bloomberg agora oferece suporte a fluxos de trabalho de agentes escaláveis e seguros que desbloqueiam total interoperabilidade com o ecossistema MCP. A Bloomberg não divulgou nenhum recurso público, mas foi isso que eles apresentaram publicamente na cúpula.

• Block - O Block usa o MCP para impulsionar o Goose, um agente de IA interno que permite aos funcionários automatizar tarefas de engenharia, vendas, marketing e muito mais. Eles criaram mais de 60 servidores MCP para ferramentas como Git, Snowflake, Jira e Google Workspace para permitir interação em linguagem natural com os sistemas que eles usam todos os dias. Os funcionários da Block agora usam o Goose para consultar dados, detectar fraudes, gerenciar incidentes, navegar em processos internos e muito mais, tudo isso sem precisar escrever código. O MCP ajudou a Block a escalar a adoção de IA em muitas funções de trabalho em apenas 2 meses.

• AWS - Servidores MCP da AWS: a AWS apresentou um divertido servidor MCP com tema de Dungeons and Dragons que simula o lançamento de dados, rastreia lançamentos anteriores e retorna resultados usando Streamable HTTP. Este exemplo simples destacou como é fácil construir e implantar servidores MCP usando ferramentas e infraestrutura da AWS, como Lambda e Fargate. Eles também introduziram o Strands SDK, um kit de ferramentas de código aberto para criar agentes multimodais que interagem com servidores MCP.

Suporte a MCP no Elastic Agent Builder

Você pode começar a experimentar o MCP hoje mesmo usando o Elastic Agent Builder, que é a maneira mais fácil de criar agentes diretamente sobre seus dados. O Agent Builder permite expor ferramentas baseadas em Elasticsearch para agentes compatíveis com MCP e já vem com algumas ferramentas integradas poderosas, incluindo:

• platform.core.search - Executa pesquisas usando a DSL de consulta completa do Elasticsearch

• platform.core.list_indices - Lista todos os índices disponíveis no Elasticsearch (ajuda os agentes a descobrir quais dados existem)

• platform.core.get_index_mapping - Recupera mapeamentos de campos para um índice específico (ajuda os agentes a entenderem o formato e os tipos dos seus dados)

• platform.core.get_document_by_id - Busca um documento específico por ID (para uma recuperação precisa)

Somente com essas ferramentas, você pode equipar seu agente com pesquisa e relevância de nível empresarial, o que é fundamental para a criação de agentes de IA confiáveis.

O que torna o Agent Builder ainda mais poderoso é a capacidade de definir e expor suas próprias ferramentas personalizadas, adaptadas às necessidades do seu aplicativo. Isso é especialmente útil para fluxos de trabalho repetitivos ou com critérios predefinidos, nos quais você deseja que o agente execute um tipo específico de pesquisa em um índice específico, sem precisar redescobrir essa lógica a cada vez. Em vez de gastar tokens em planejamento e raciocínio para chegar à mesma conclusão, você pode codificar essa intenção diretamente em uma ferramenta, tornando seus agentes mais rápidos, confiáveis e econômicos.

Na interface do usuário do Agent Builder, aqui está um exemplo de definição de ferramenta personalizada que usa ES|QL:

Depois de definir suas ferramentas personalizadas, você pode expô-las (além das ferramentas nativas integradas) usando o MCP clicando no menu suspenso para Manage MCP e copiando o URL do servidor MCP.

Agora você pode importar este endpoint MCP para qualquer cliente que utilize MCP, conectando-o ao Agent Builder e dando-lhe acesso a todas as ferramentas disponíveis. Para obter mais informações, leia esta introdução ao Agent Builder.

Conclusão

O MCP Dev Summit deixou claro que o MCP está moldando a maneira como esses agentes de IA interagem entre si e com o mundo de dados ao seu redor. Não importa se você está conectando um agente a dados corporativos ou projetando agentes totalmente autônomos, o MCP oferece uma maneira padronizada e combinável de integração que está rapidamente se tornando útil em escala. De protocolos de transporte e padrões de segurança a registros e governança, o ecossistema MCP está amadurecendo rapidamente. O MCP continuará aberto e orientado pela comunidade, para que os desenvolvedores de hoje tenham a chance de moldar sua evolução.