A LlamaIndex publicou no GitHub o legal-kb, uma aplicação de referência que demonstra um novo padrão de recuperação agentiva de documentos usando o Index v2 da plataforma LlamaParse. O projeto introduz o conceito de Retrieval Harness — um agente com ferramentas no estilo filesystem que vasculha bases de conhecimento jurídicas e corporativas.
O que é o legal-kb?
O legal-kb é uma aplicação web completa construída com TanStack Start, e não uma biblioteca. O usuário faz login, cria um projeto, faz upload de arquivos e interage com um agente de chat. Cada projeto é espelhado como um índice gerenciado no LlamaCloud Index v2. Os documentos enviados são analisados e indexados automaticamente em segundo plano, e o agente consulta esse índice em tempo real durante cada interação.
O Retrieval Harness explicado
O diferencial está na arquitetura. Em vez de uma única busca por similaridade vetorial por consulta — o modelo clássico de RAG —, o Retrieval Harness fornece um pipeline de dados persistente que expõe ferramentas no estilo filesystem ao agente. O agente pode listar arquivos, ler um arquivo completo, fazer grep dentro de um documento ou executar busca híbrida semântica.
Essa abordagem é multi-etapas: o agente primeiro descobre o inventário de documentos, depois refina com busca semântica e, por fim, confirma trechos exatos com leitura direta ou grep antes de citar. O resultado é um sistema que integra descoberta, recuperação e verificação em um único fluxo agentivo.
| Ferramenta | API de suporte | Parâmetros principais | Função |
|---|---|---|---|
retrieve | beta.retrieval.retrieve | query, top_k, score_threshold, rerank_top_n | Busca semântica híbrida com reranking opcional; retorna chunks com citações visuais |
findFiles | beta.retrieval.find | file_name, file_name_contains | Busca arquivos por nome exato ou substring; pagina automaticamente |
readFile | beta.retrieval.read | file_id, offset, max_length | Lê conteúdo bruto com controle de offset e janela de leitura |
grepFile | beta.retrieval.grep | file_id, pattern | Busca com regex dentro de um arquivo específico |
Como funciona internamente
O pipeline de upload segue um fluxo claro: os bytes são enviados para o diretório de origem do projeto no LlamaCloud, registros File e ProjectFile são persistidos no PostgreSQL via Prisma, e uma sincronização de índice é disparada de forma assíncrona. A interface acompanha o status até a conclusão.
O versionamento é feito por par (projeto, nome_do_arquivo). Reenviar um mesmo arquivo produz versões lado a lado (v1, v2, v3), e a camada de recuperação filtra por metadados de versão. Isso oferece controle de versão sobre a própria base de conhecimento.
O agente utiliza o ToolLoopAgent do Vercel AI SDK 6, com suporte a raciocínio estendido para modelos Claude e reasoning de esforço médio para modelos OpenAI. O desenvolvedor escolhe o provedor por interação e fornece suas próprias chaves.
RAG ingênuo vs. Retrieval Harness agentivo
| Dimensão | RAG ingênuo (single-shot) | Retrieval Harness agentivo (Index v2) |
|---|---|---|
| Fluxo de recuperação | Uma busca vetorial por consulta | Loop multi-etapas: find → retrieve → read/grep |
| Modos de busca | Apenas similaridade vetorial | Busca semântica híbrida, keyword e regex grep |
| Contexto | Top-k chunks fixos | Agente lê arquivos completos ou janelas sob demanda |
| Atualização | Índice estático | Pipeline persistente com sincronização e versionamento |
| Controle de precisão | Majoritariamente oculto | Parâmetros expostos: top_k, score_threshold, rerank_top_n |
| Citações | IDs de chunk | Citações visuais com bounding boxes sobre screenshots das páginas |
Casos de uso práticos
O design é pensado para domínios onde agentes precisam navegar grandes conjuntos de documentos estruturados, com exemplos declarados em jurídico e fintech:
- Contratos: o agente lista arquivos, executa
retrievee fazgrepda cláusula exata, respondendo com citação visual da página específica. - Due diligence: em um data room, o agente encontra candidatos com
findFiles, lê cada um comreadFilee cruza cláusulas sem abrir cada PDF manualmente. - Políticas versionadas: como o
retrieveaceita filtrofile_version, é possível consultar uma versão específica e rastrear mudanças ao longo do tempo.
Por que isso importa
O legal-kb é mais do que um demo: é uma implementação de referência que mostra como combinar busca semântica, ferramentas determinísticas de filesystem e agentes de raciocínio em um único fluxo. Para equipes que trabalham com bases de documentos corporativos ou regulatórios, o padrão de Retrieval Harness oferece um caminho claro para ir além do RAG tradicional, com versionamento de documentos, citações visuais rastreáveis e um loop de ferramentas que o agente controla de forma autônoma.
O código está disponível no GitHub sob licença open source, com stack baseada em TanStack Start, AI SDK 6, Prisma e WorkOS para autenticação.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
