An Empirical Study of Bugs in Modern LLM Agent Frameworks

TL;DR

This paper empirically analyzes 998 bug reports from LLM agent frameworks, identifying common root causes and symptoms to improve understanding and debugging of framework-level issues in real-world applications.

Contribution

It provides the first comprehensive taxonomy of framework-level bugs in LLM agent systems, highlighting prevalent causes and symptoms across different lifecycle stages.

Findings

Framework bugs mainly stem from API misuse and incompatibility.

Most bugs occur during the 'Self-Action' stage.

Symptoms include functional errors, crashes, and build failures.

Abstract

LLM agents have been widely adopted in real-world applications, relying on agent frameworks for workflow execution and multi-agent coordination. As these systems scale, understanding bugs in the underlying agent frameworks becomes critical. However, existing work mainly focuses on agent-level failures, overlooking framework-level bugs. To address this gap, we conduct an empirical study of 998 bug reports from CrewAI and LangChain, constructing a taxonomy of 15 root causes and 7 observable symptoms across five agent lifecycle stages: 'Agent Initialization','Perception', 'Self-Action', 'Mutual Interaction' and 'Evolution'. Our findings show that agent framework bugs mainly arise from 'API misuse', 'API incompatibility', and 'Documentation Desync', largely concentrated in the 'Self-Action' stage. Symptoms typically appear as 'Functional Error', 'Crash', and 'Build Failure', reflecting disruptions to task progression and control flow.