💻 computer science

BLAgent: Agentic RAG for File-Level Bug Localization

BLAgent is a novel agentic Retrieval-Augmented Generation framework that enhances file-level bug localization through code structure-aware encoding, dual-perspective query transformation, and two-phase agentic reranking, achieving state-of-the-art accuracy on SWE-bench Lite while significantly reducing costs and improving downstream automated program repair success.

Original authors: Md Afif Al Mamun, Gias Uddin

Published 2026-05-19

📖 5 min read🧠 Deep dive

CC BY 4.0

Original authors: Md Afif Al Mamun, Gias Uddin

Original paper licensed under CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ This is an AI-generated explanation of the paper below. It is not written or endorsed by the authors. For technical accuracy, refer to the original paper. Read full disclaimer

The Big Problem: Finding a Needle in a Haystack

Imagine you are a mechanic (a software developer) trying to fix a broken car. A customer hands you a complaint: "The car makes a weird noise when I turn left."

In the world of software, this complaint is a bug report. The car is a massive code repository containing millions of lines of code (the hay). The specific line of code causing the noise is the needle.

For a long time, AI tools trying to fix these bugs have struggled because they can't find the needle first. If the AI guesses the wrong part of the engine (the wrong file), it will try to fix the wrong thing, and the car will still be broken. This is called Bug Localization.

The Solution: BLAgent (The Super-Detective)

The authors created a new system called BLAgent. Think of it as a super-detective that doesn't just guess; it uses a smart, step-by-step investigation process to find the exact file that needs fixing before trying to repair it.

BLAgent uses a technique called Agentic RAG (Retrieval-Augmented Generation). In plain English, this means the AI doesn't just "hallucinate" an answer; it goes to a library (the code repository), finds the right books (code files), reads them, and then thinks about the answer.

Here is how BLAgent works, broken down into three simple steps:

1. Organizing the Library (Smart Chunking)

Imagine your library is a mess. Books are ripped in half, and pages are glued together randomly. If you ask the librarian for a book about "engines," they might hand you a page that says "engine" but is actually from a cookbook.

Old Way: Traditional AI splits code into random chunks of text, like tearing a book page by page.
BLAgent Way: BLAgent uses a structural map (called an AST). It knows that a "function" or a "class" is like a complete chapter. It cuts the code only at the end of these chapters.
The Secret Sauce: It also stamps the file path (the address of the book) on every page. If the bug report mentions a specific folder name, BLAgent can instantly match that address to the right book.

2. Asking Better Questions (Dual-Perspective Queries)

Imagine you are asking a librarian for help.

Bad Question: "My car is broken." (Too vague).
BLAgent's Strategy: It asks two different questions to get the best results:
1. The Structural Question: "Which file contains the turn_signal function?" (Looking for specific names and code structures).
2. The Behavioral Question: "Which file handles the situation where the car makes a noise when turning?" (Looking for the symptoms and behavior).

By asking both, BLAgent casts a wider net, ensuring it doesn't miss the right file just because the bug report used different words than the code.

3. The Detective's Investigation (Agentic Reranking)

This is the most important part. The library gives BLAgent a list of the top 15 most likely books (files). But which one is actually the culprit?

Old AI: Picks the first book on the list and tries to fix it.
BLAgent (The Agent): It acts like a detective. It doesn't just read the cover; it opens the books and looks at the skeleton (the table of contents and chapter titles) of the top candidates.
- It asks itself: "Does this file's structure match the crime?"
- It assigns a score (0 to 10) to each file.
- Then, for the top few suspects, it reads the actual text of the relevant sections to make a final, evidence-based decision.

This "bounded reasoning" means the detective only investigates the most likely suspects, saving time and money, rather than searching the whole library.

Why This Matters: The Repair Shop

The paper tested BLAgent on a famous benchmark called SWE-bench (a collection of real-world software bugs).

The Result: BLAgent found the correct file to fix 78% to 86% of the time (depending on the AI model used).
The Comparison: Previous methods found the right file less often.
The Cost: BLAgent is 18 times cheaper than the previous best method. The old methods were like hiring a team of 100 people to search the library; BLAgent is like hiring one very smart detective with a map.

The Impact on Fixing Bugs:
When BLAgent was plugged into an automated repair system, the system successfully fixed 20% more bugs than before.

Analogy: If you give a mechanic the wrong engine part, they can't fix the car. If you give them the right part (accurate localization), they can fix it. BLAgent ensures the mechanic gets the right part.

What the Paper Doesn't Say

It does not claim to fix every bug. About 14% of the time, the correct file was so hidden or the bug report so vague that even BLAgent couldn't find it in the top list.
It does not claim to be a magic wand for all software. It works best on Python projects (like the ones in the test) and relies on the quality of the bug report.
It does not say that finding the file is the only step. Once the file is found, the AI still has to write the actual code fix, which can still fail. But finding the file is the biggest hurdle.

Summary

BLAgent is a smarter way for AI to find broken code. Instead of guessing randomly, it organizes the code library better, asks smarter questions, and uses a "detective" step to verify the evidence before making a move. This makes it much faster, cheaper, and more accurate at finding the root cause of software bugs.

Technical Summary: BLAgent: Agentic RAG for File-Level Bug Localization

Problem Statement

Bug localization remains a critical bottleneck in software maintenance, particularly for downstream tasks like root cause analysis, triage, and Automated Program Repair (APR). While Large Language Model (LLM)-based repair systems have advanced, their effectiveness is fundamentally constrained by the quality of file-level localization. In hierarchical pipelines, inaccurate file selection propagates errors to subsequent stages (e.g., statement-level localization or patch generation), often causing repair failures.

Existing Retrieval-Augmented Generation (RAG) approaches for code often rely on static retrieval and naive text-based chunking, failing to capture the structural intricacies of code or the reasoning required to identify faulty files accurately. Furthermore, purely embedding-based methods lack the reasoning capabilities to assess functional relevance, while existing agentic approaches often employ unbounded graph-based traversal, incurring prohibitive computational costs.

Methodology: BLAgent Framework

The authors propose BLAgent, a novel agentic RAG framework designed for file-level bug localization. The system integrates three core components to balance accuracy and cost:

1. Repository Encoding with Path-Augmented AST-Based Chunking

Instead of naive text splitting, BLAgent employs CodeSplitter to segment source files based on Abstract Syntax Tree (AST) boundaries (e.g., functions, classes, logical blocks). This ensures semantic preservation, preventing the fragmentation of code constructs.

Path Augmentation: Each code chunk is prepended with its relative file path (e.g., src/utils/math.py). This creates a direct alignment channel between path-like signals in bug reports (e.g., tracebacks, module references) and the code chunks, addressing vocabulary mismatches between natural language descriptions and code identifiers.

2. Dual-Perspective Query Transformation

To bridge the semantic gap between bug reports and code, BLAgent decomposes every bug report into two complementary queries using LLMs:

Structural Transformation ( $T_0$ ): Focuses on static, syntactic aspects, extracting identifiers, modules, function names, and traceback context.
Behavioral Transformation ( $T_1$ ): Focuses on runtime behavior, capturing observed symptoms, expected vs. actual outputs, and triggering conditions.
Both queries are independently used to retrieve candidate files from a vector database. The resulting candidate sets are merged (deduplicated) to form a compact pool (limited to 15 files) for the agent.

3. Two-Phase Agentic Reranking

BLAgent performs bounded reasoning over the retrieved candidate set through a two-phase process:

Phase 1: Skeleton-Based Agent Scoring (SAS): A ReAct-based agent iteratively inspects the structural skeletons (classes, function signatures, docstrings) of candidate files. It assigns relevance scores (0–10) based on hypotheses about which files require modification. This phase operates efficiently within context limits by avoiding full source code processing.
Phase 2: Evidence-Anchored Reranking (EAR): To resolve ties and verify implementation-level relevance, the top- $M$ (set to 5) files from Phase 1 undergo a single-shot inference. The context is pruned to include only the file's global structure and the full implementation of methods highlighted by the retriever. The LLM performs a final ranking based on this grounded evidence.

Key Contributions

Agentic RAG for Localization: BLAgent introduces a bounded reasoning framework that integrates retrieval with iterative, tool-augmented reasoning, avoiding the high costs of unbounded graph traversal.
AST-Aware, Path-Augmented Chunking: The paper demonstrates that preserving syntactic boundaries and augmenting chunks with file paths significantly improves retrieval recall compared to standard text-based or code-aware chunking.
Dual-Perspective Querying: The framework shows that decomposing bug reports into structural and behavioral queries provides complementary retrieval signals, enhancing the recall of the initial candidate pool.
Cost-Efficient Design: By limiting reasoning to a compact, retrieval-filtered candidate set and using code skeletons, BLAgent achieves high accuracy with significantly lower token consumption and API costs compared to graph-based agentic baselines.

Experimental Results

The framework was evaluated on the SWE-bench-Lite dataset (300 real-world Python bugs).

Localization Accuracy:
- Using an open-source model (GPT-OSS-120B), BLAgent achieved a Top-1 accuracy of 78.6% and an MRR of 0.851.
- Using a closed-source model (Claude-4.6-Sonnet), it achieved a Top-1 accuracy of 86.7% and an MRR of 0.900.
- These results outperform state-of-the-art baselines, including LocAgent (a graph-based agentic approach) and Agentless (an APR framework with localization), often by significant margins.
Cost Efficiency: BLAgent is over 18× cheaper than the strongest baseline (LocAgent) when using the same closed-source model, completing all 300 instances for approximately $27 total, whereas LocAgent exhausted a $300 budget after only 182 instances.
Impact on Automated Program Repair (APR): When integrated into the Agentless APR framework, BLAgent improved the end-to-end issue resolution rate by over 20% (from 27.6% to 34.0% with majority voting).
Generalizability: The architecture successfully extended to function-level localization with a single prompt modification, achieving state-of-the-art results without structural changes to the pipeline.

Significance and Claims

The paper claims that BLAgent establishes a new state-of-the-art for file-level bug localization by effectively combining retrieval and agentic reasoning. Its primary significance lies in demonstrating that:

Localization is a decisive factor: Accurate file-level localization directly translates to measurable gains in end-to-end automated repair success.
Bounded reasoning is superior to unbounded traversal: Agentic reasoning constrained to a high-quality, retrieval-filtered candidate set outperforms complex graph-based approaches in both accuracy and cost.
Retrieval quality bounds performance: The effectiveness of the agentic pipeline is fundamentally limited by the recall of the initial dense retriever; thus, improvements in chunking and query transformation are critical.
Cost-effective scalability: High-performance localization can be achieved using open-source models and efficient context management (skeletons), making advanced bug localization accessible without the prohibitive costs of proprietary models or graph traversal.

The authors conclude that while precise localization is necessary, it is not sufficient for perfect repair, as downstream failures (function/line-level localization and patch generation) remain significant bottlenecks. However, BLAgent provides a robust, cost-efficient foundation for addressing the upstream localization challenge in LLM-based software maintenance.