A ferramenta shell não é uma solução milagrosa para engenharia de contexto

As ferramentas mais importantes para o agente são as ferramentas de busca que ele pode usar para construir o próprio contexto. Postagens recentes do LlamaIndex e LangChain suscitaram uma discussão: uma ferramenta de linha de comando e um sistema de arquivos são tudo o que o agente precisa para engenharia de contexto? Infelizmente, a discussão rapidamente se desviou para o foco errado: sistema de arquivos x banco de dados.

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