{"id":102071,"date":"2026-07-05T18:51:36","date_gmt":"2026-07-05T18:51:36","guid":{"rendered":"https:\/\/youzum.net\/llamaindex-legal-kb-agentic-retrieval-over-index-v2-with-retrieve-find-read-and-grep-tools\/"},"modified":"2026-07-05T18:51:36","modified_gmt":"2026-07-05T18:51:36","slug":"llamaindex-legal-kb-agentic-retrieval-over-index-v2-with-retrieve-find-read-and-grep-tools","status":"publish","type":"post","link":"https:\/\/youzum.net\/es\/llamaindex-legal-kb-agentic-retrieval-over-index-v2-with-retrieve-find-read-and-grep-tools\/","title":{"rendered":"LlamaIndex \u2018legal-kb\u2019: Agentic Retrieval over Index v2 with retrieve, find, read, and grep Tools"},"content":{"rendered":"

LlamaIndex has published legal-kb<\/a><\/code>, a public reference application on GitHub. It is described as a knowledge base for legal documents, powered by LlamaIndex Index v2 (the LlamaParse Platform). The project demonstrates a pattern the team calls a Retrieval Harness for agentic retrieval.<\/p>\n

The approach differs from single-shot retrieval. Instead of one embedding search per query, an agent is given filesystem-style tools. It can then crawl a large, evolving knowledge base to solve a task. The tools mirror operations engineers already know: semantic and keyword search, regex grep, file search, and read.<\/p>\n

What is legal-kb?<\/strong><\/h2>\n

legal-kb<\/code> is a working TanStack Start web app, not a library. You sign in, create a project, upload files, and chat with an agent. Each project is mirrored as a managed LlamaCloud Index v2. Uploaded files are parsed and indexed automatically in the background. The chat agent then queries that index live during each turn.<\/p>\n

The Retrieval Harness, in plain terms<\/strong><\/h2>\n

The harness provides a persistent data pipeline over your documents. It connects to a data source, indexes it, and keeps it updated. On top of that pipeline, it exposes a set of tools to the agent.<\/p>\n

Those tools are deliberately close to filesystem operations. An agent can list files, read a file, grep inside a file, or run hybrid search. Because the tools are generic, you can plug the harness into your own agents.<\/p>\n

The four agent tools<\/strong><\/h2>\n

The agent in src\/lib\/agent.ts<\/code> is given four tools. Each maps to an Index v2 retrieval API. The table below lists them as implemented.<\/p>\n

\n\n\n\n\n\n\n\n\n
Tool<\/th>\nBacking API<\/th>\nKey parameters<\/th>\nWhat it does<\/th>\n<\/tr>\n<\/thead>\n
retrieve<\/code><\/td>\nbeta.retrieval.retrieve<\/code><\/td>\nquery<\/code>, top_k<\/code>, score_threshold<\/code>, rerank_top_n<\/code>, file_name<\/code>, file_version<\/code><\/td>\nRuns hybrid semantic search; optional reranking; returns chunks plus citations<\/td>\n<\/tr>\n
findFiles<\/code><\/td>\nbeta.retrieval.find<\/code><\/td>\nfile_name<\/code>, file_name_contains<\/code><\/td>\nSearches files by exact name or substring; paginates automatically<\/td>\n<\/tr>\n
readFile<\/code><\/td>\nbeta.retrieval.read<\/code><\/td>\nfile_id<\/code>, offset<\/code>, max_length<\/code><\/td>\nReads raw file content, with offset and length windows<\/td>\n<\/tr>\n
grepFile<\/code><\/td>\nbeta.retrieval.grep<\/code><\/td>\nfile_id<\/code>, pattern<\/code>, context_chars<\/code>, limit<\/code><\/td>\nMatches a pattern in one file; returns character positions<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n

The system prompt enforces an order. The agent must call findFiles<\/code> first to establish the document inventory. It then narrows with retrieve<\/code>, and confirms exact wording with readFile<\/code> or grepFile<\/code> before citing.<\/p>\n

How it works under the hood<\/strong><\/h2>\n

Uploads follow a clear pipeline in src\/lib\/files.ts<\/code>. Bytes are pushed to the project\u2019s LlamaCloud source directory. A File<\/code> and ProjectFile<\/code> row are written to PostgreSQL via Prisma. An index sync is triggered but not awaited; the UI polls status until ready.<\/p>\n

Versioning is scoped to the (project, filename) pair. Re-uploading nda.pdf<\/code> to the same project produces v1, v2, v3 side by side. The retrieval layer filters on the version<\/code> metadata field. This gives version control over the knowledge base itself.<\/p>\n

The agent uses the ToolLoopAgent<\/code> from Vercel AI SDK 6. You pick OpenAI or Anthropic per turn and bring your own keys. Reasoning is streamed: Claude models use extended thinking; OpenAI reasoning models use a medium reasoning effort.<\/p>\n

Here is a condensed but faithful view of the retrieve<\/code> tool and the agent.<\/p>\n

\n
\n
\n
\n
<\/div>\n
<\/div>\n
<\/div>\n<\/div>\n
Copy Code<\/span>Copied<\/span>Use a different Browser<\/span><\/a><\/div>\n<\/div>\n
import { LlamaCloud } from '@llamaindex\/llama-cloud'\nimport { tool, ToolLoopAgent } from 'ai'\nimport { z } from 'zod'\nimport { makeCitationId } from '.\/citations'\n\n\/\/ One tool closure per index. Wraps Index v2 retrieval APIs.\nfunction createLlamaParseTools(apiKey: string, projectId: string, indexId: string) {\n  const client = new LlamaCloud({ apiKey })\n\n  const retrieve = tool({\n    description: 'Run a semantic retrieval query against an index.',\n    inputSchema: z.object({\n      query: z.string(),\n      top_k: z.number().nullable(),\n      score_threshold: z.number().nullable(),\n      rerank_top_n: z.number().nullable(),   \/\/ set to enable reranking\n      file_name: z.string().nullable(),      \/\/ metadata filter\n      file_version: z.number().nullable(),\n    }),\n    execute: async ({ query, top_k, score_threshold, rerank_top_n, file_name }) => {\n      const custom_filters = file_name\n        ? { file_name: { operator: 'eq' as const, value: file_name } }\n        : undefined\n\n      const response = await client.beta.retrieval.retrieve({\n        index_id: indexId,\n        project_id: projectId,\n        query,\n        top_k,\n        score_threshold,\n        rerank: rerank_top_n != null ? { enabled: true, top_n: rerank_top_n } : undefined,\n        custom_filters,\n      })\n\n      \/\/ Return a model-readable list plus citations that drive the UI chips.\n      const citations = response.results.map((r) => ({\n        id: makeCitationId(),                    \/\/ e.g. \"c7f2qa\"\n        fileName: r.metadata?.file_name,\n        score: r.rerank_score ?? r.score ?? null,\n        preview: r.content.slice(0, 500),\n      }))\n      const formatted = response.results\n        .map((r, i) => `### Result #${i + 1}nn${r.content.slice(0, 600)}`)\n        .join('nn---nn')\n      return { formatted, citations }\n    },\n  })\n\n  \/\/ findFiles \/ readFile \/ grepFile follow the same shape, backed by\n  \/\/ client.beta.retrieval.find \/ .read \/ .grep\n  return { retrieve \/* , findFiles, readFile, grepFile *\/ }\n}\n\nexport function buildAgent(model, apiKey: string, projectId: string, indexId: string) {\n  return new ToolLoopAgent({\n    model,\n    tools: createLlamaParseTools(apiKey, projectId, indexId),\n    instructions:\n      'Always call findFiles first, ground every answer in the documents, ' +\n      'and cite ids inline as `cite:<id>`.',\n  })\n}<\/code><\/pre>\n<\/div>\n<\/div>\n
Answers carry visual citations. Each retrieved chunk gets a short id, such as cite:c7f2qa<\/code>. The agent references that id inline, and the UI renders a clickable citation chip. Clicking it opens the source page screenshot with bounding-box rectangles over the cited text.<\/p>\n
Naive RAG vs the agentic Retrieval Harness<\/h2>\n
The harness is a different execution model from single-shot RAG. The comparison below focuses on behavior.<\/strong><\/p>\n
\n\n\n\n\n\n\n\n\n\n\n\n
Dimension<\/th>\nNaive \/ single-shot RAG<\/th>\nAgentic Retrieval Harness (Index v2)<\/th>\n<\/tr>\n<\/thead>\n
Retrieval flow<\/td>\nOne vector search per query<\/td>\nMulti-step tool loop: find \u2192 retrieve \u2192 read\/grep<\/td>\n<\/tr>\n
Search modes<\/td>\nVector similarity only<\/td>\nHybrid semantic search, keyword, and regex grep<\/td>\n<\/tr>\n
Context<\/td>\nFixed top-k chunks<\/td>\nAgent reads full files or windows on demand<\/td>\n<\/tr>\n
Freshness<\/td>\nStatic index<\/td>\nPersistent pipeline with sync and versioning<\/td>\n<\/tr>\n
Precision control<\/td>\nMostly hidden<\/td>\ntop_k<\/code>, score_threshold<\/code>, rerank_top_n<\/code> exposed<\/td>\n<\/tr>\n
Citations<\/td>\nChunk ids<\/td>\nVisual citations with page screenshots and bboxes<\/td>\n<\/tr>\n
Best fit<\/td>\nShort question answering<\/td>\nLong-horizon document tasks<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/figure>\n
Use cases, with examples<\/strong><\/h2>\n
The design targets domains where agents navigate large document sets. Legal and fintech are the stated examples.<\/p>\n