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.
@article{arxiv.2602.21806,
title = {An Empirical Study of Bugs in Modern LLM Agent Frameworks},
author = {Xinxue Zhu and Jiacong Wu and Xiaoyu Zhang and Tianlin Li and Yanzhou Mu and Juan Zhai and Chao Shen and Chunrong Fang and Yang Liu},
journal= {arXiv preprint arXiv:2602.21806},
year = {2026}
}