AgentLint : Detecting Architectural Smells in LLM-Based Agent Systems - A Taxonomy of 14 Design Rules with Combined Static and Runtime Analysis

Sammanfattning

Background. Large Language Model (LLM)-based agent systems are now widely used in software engineering, yet their non-deterministic reasoning, dynamic context management, and tool-based interaction introduce failure modes that traditional software quality approaches do not address. While code smells have been studied in conventional and machine learning systems, no prior work provides an architecture-level taxonomy of design issues specific to agentic AI architectures. Objectives. This thesis aims to construct a taxonomy of architectural smells in LLM-based agent systems, develop a detection tool that implements the taxonomy through combined static and runtime analysis, and evaluate the combined effectiveness of static analysis and runtime instrumentation for detecting these smells. Methods. The study employed a Design Science Research Methodology. The taxonomy was constructed by combining a literature review (2022–2026) with repository mining of 52 open-source agent frameworks covering 96,120 commits. The taxonomy was then implemented in AgentLint, a Python library implementing 14 design rules via AST-based static analysis and decorator-based runtime interception. The evaluation comprised a quantitative detection experiment across four agent frameworks (PraisonAI, PydanticAI, CrewAI, DeerFlow) with 200 runtime trials, and a qualitative developer evaluation with eight practitioners at an industrial site. Results. Static analysis detected 279 findings spanning 11 of 14 rules across the four repositories, with missing tool-call error handling (DR-6) as the most prevalent smell (45.5%). Runtime analysis detected 268 smell instances across 200 trials covering 4 rules, confirming that code-level issues manifest as observable problems during live agent execution. The developer evaluation rated report clarity at 4.25/5 and location accuracy at 4.50/5, with practitioners confirming that the detected smell categories correspond to issues experienced in production. Conclusions. Architectural smells in LLM-based agent systems can be classifiedand detected through combined static and runtime analysis. The taxonomy and tool provide a diagnostic framework that enables developers to identify reliability, maintainability, and cost-efficiency issues in agent-based systems before they reach production.