Agent Bug Atlas

把真实的 Agent Bug 变成回归测试，检查你的 Agent 是否也会踩坑。

English

快速开始 · 接入自己的 Agent · 案例目录 · 贡献案例

升级框架、切换模型，或修改工具调用与会话存储时，一些已修复的故障可能再次出现。Agent Bug Atlas 从开源项目的真实问题中提炼测试输入，让它们经过你的实际组件，检查同类问题是否存在。

• 跑测试：通过 Python 适配器接入自己的实现，支持同步和异步入口。
• 定位问题：查看哪些输入失败，以及最早出现差异的观察点。
• 理解原因：每个案例附根因分析、上游修复和修复前后的执行证据。

当前阶段：早期原型，4 个可执行故障案例。 覆盖工具参数、重试预算、会话回复和流式失败状态；每个案例均已在真实上游修复前后版本上验证。通过测试只说明已接入的路径通过了选定检查。

快速开始

需要 Python 3.12+ 和 Git。以下示例无需安装第三方依赖，也不需要模型 API key。

git clone https://github.com/Wanming08/agent-bug-atlas.git
cd agent-bug-atlas
python -m agent_bug_atlas --target examples.json_roundtrip:create_target --report report.json

预期输出摘要：

PASS: JSON wiring example
PASS 5 / FAIL 0 / ERROR 0 / SKIP 0

report.json 保存每个输入和观察点的详细结果。这里运行的是内置 JSON 序列化示例，用于体验测试流程；测试自己的 Agent，请继续下一节。

接入自己的 Agent

1. 在 Agent 的 Python 环境中安装

将以下路径替换为你的实际目录：

cd /path/to/your-agent
python -m pip install -e /path/to/agent-bug-atlas

2. 连接要检查的组件

按接入指南，在 Agent 项目根目录创建 atlas_target.py，提供 create_target() 工厂。

适配器接收 Atlas 的测试输入，调用你的真实解析、存储或回放代码，再返回各阶段实际观察值。可以从工具参数接口开始；检查重试、会话或流式状态，使用场景接口。内置示例展示了最小接入形状。

3. 运行检查

在 Agent 项目根目录执行：

python -m agent_bug_atlas --target atlas_target:create_target --report atlas-report.json

结果区分 PASS、FAIL、ERROR 和 SKIP。只有全部检查通过才退出 0，可以接入 CI；完整用法见结果说明和 pytest 示例。

案例目录

案例	检查什么	来源
001 · 空工具参数丢失	工具参数经过解析、转换或回放后，是否保持原来的含义	Agno #8971 / 修复 #8970
002 · 重试预算被清零	交替调用其他工具后，失败工具是否仍受重试限制	Pydantic AI #6582
003 · 回复未持久化	新实例恢复会话时，是否完整保留已回复的消息	CrewAI #7026
004 · 错误事件早于保存	收到流式错误终态时，失败状态和已完成步骤是否已保存	Agno #10001

每篇案例附复现命令、真实修复前后对照和可接入自己 Agent 的断言。验证记录集中列出执行结果与覆盖范围。多个输入或同步/异步场景是同一案例的检查与对照，不计作额外 bug。

文档与贡献

• 接入指南：适配器接口、报告、退出码和 CI 集成。
• 场景接入：重试、会话和流式状态的测试契约。
• 验证记录：实际执行结果、覆盖范围和复现方法。
• 后续选题：尚未实现的候选案例。
• 贡献指南 · 案例模板：提交有来源、可复现的新案例。

Atlas 原创代码采用 MIT License。上游问题与修复的作者归属见 ATTRIBUTION.md，引用的 Agno 代码保留 Apache 2.0 许可。