简体中文 | English

agent-choice-bench

面向面试场景的 Agent 技术选型基准：受控的 A/B 对比单元（记忆、长期记忆路由、工具、编排、相似度、可观测性），判分只由外部判分器完成，判据先冻结，重算全程离线。

诚实的范围界定

范围内	范围外
合成的离线场景	真实用户数据 / 生产多租户
默认使用确定性 stub LLM	把付费 API 当作默认路径
在测试编排的地方使用 LangGraph 编排臂	LLM 质量排行榜
预注册对比臂 + 可区分性检验	宣称生产级 SOTA
一条命令重算 + 双 OS CI	改动其他已发布的 RAG 仓库

langgraph 由 D 组编排臂在 try/except 保护下导入（src/agent_choice_bench/arms/d_orch.py），并由 tests/test_arms_smoke.py 断言导入成功；langchain 只是 pyproject.toml 里声明的依赖，基准代码从未导入。

这是一个面向常见面试取舍的决策记录基准，不是聊天产品。

快速开始

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix: source .venv/bin/activate
pip install -e ".[dev]"
python -m agent_choice_bench.run_all
pytest -q

环境要求：Python ≥3.11（推荐 3.12）。安装完成后，默认路径无需联网。

覆盖单元

15 个冻结单元（A1–F2），共 36 个对比臂，数量记录在 results/freeze_report.json。

ID	主题	对比臂	主指标
A1–A4	摘要 / 保留 / 持久化	见 config/coverage.yaml	事实保留 / 泄漏 / 一致性
B1–B3	长期记忆注入与意图路由	always / on-demand / 路由器	task_success / router_f1
C1–C2	工具数量与渐进式披露	n4/n8/n16/n32；渐进式 vs 全量暴露	tool_select_accuracy
D1–D3	编排 / 重规划 / 多智能体	ReAct、plan-exec、route；重规划；双判分	task_success / recovery / false-pass
E1	相似度度量	cosine / dot / L2 × 原始与单位归一	rank_agreement
F1–F2	账本与追踪	全量 vs 无；全量 vs 扁平	completeness / span_coverage

评测纪律

1. 先冻结——给出任何结论之前，先把 config/*.yaml 的哈希写入 results/freeze_report.json。
2. 只用外部判分——对比臂只产出结构化输出与事件，由 judges.py 对照 gold 打分。
3. 可区分性——主指标使用配对 bootstrap 置信区间；不可区分的对比对记录在 docs/non_discriminative.md（这不算失败）。
4. 一次重算——python -m agent_choice_bench.run_all。
5. D3 审计——results/d3_audit_instance.json 记录自评通过 ∧ 外部判分不通过的实例（只做格式自检，与 gold 不符）。

目录结构

config/          # 冻结的 coverage、criteria、arms、selection_rules
data/scenarios/  # 仅合成 JSONL
src/agent_choice_bench/
results/         # 冻结报告 + 单元指标 + D3 实例
docs/            # master_table、non_discriminative、status
tests/
.github/workflows/ci.yml   # ubuntu-latest + windows-latest

重算后产出的文档

• docs/master_table.md——覆盖单元 × 对比臂 × 读数 × 不超过 3 句的取舍说明
• docs/non_discriminative.md——主指标上不可区分的对比对
• docs/status.md——OK / NEEDS_REPLAN
• DATA_CARD.md——合成数据说明

许可证

MIT——见 LICENSE。