FAQ

常见问题（FAQ）

New to AgentBench?

Q: I just opened the Dashboard. What am I looking at?

A: Read the Web Dashboard Guide. In short: Web Dashboard = view results, CLI = run tests. They work together.

Q: Why do all Runs show PENDING / 0 / Unknown?

A: PENDING means "created but never executed". These runs haven't actually called any LLM. You need to run agentbench test via CLI to create runs with real data.

Q: What's the difference between a Test Suite and a Run?

A: Test Suite = the definition (what to test). Run = one execution of that test. Creating a Test Suite in the Dashboard doesn't produce results — you need to execute it via CLI.

Q: Do I need both the Web Dashboard and CLI?

A: Yes. The Dashboard manages tests and shows results. The CLI actually executes them (calls LLMs, checks assertions). Think of it like Jest's HTML report vs the jest command.

Q: Can I use DeepSeek models?

A: Yes! AgentBench supports DeepSeek Chat (V3) and DeepSeek Reasoner (R1) via the @agentbench/deepseek provider. Set DEEPSEEK_API_KEY in your .env file, then select deepseek-chat or deepseek-reasoner in Settings or Experiments.

---

基础

Q: AgentBench 是什么？

A: AgentBench 是一个 AI Agent 的回归测试框架。它让你像测试软件一样测试 Agent——回放、评估、对比、断言、检测回归。类比 Playwright + Jest + LangSmith 的组合。

Q: AgentBench 和 LangSmith / Braintrust 有什么区别？

A: LangSmith 和 Braintrust 侧重于 LLM 调用的监控和调试。AgentBench 侧重于测试和回归——它提供快照、回放、A/B 实验、覆盖率分析、断言 DSL 等测试框架特有的能力。

Q: AgentBench 和 LangSmith 的具体差异是什么？[NEW in v0.3.0]

A: 两者的核心定位不同：

维度	AgentBench	LangSmith
核心定位	Agent 回归测试框架	LLM 可观测性/调试平台
测试方式	断言 DSL、快照测试、回放测试	手动评估、标注
回归检测	自动 diff + 阈值告警	需人工对比
CI/CD 集成	GitHub Action、JUnit 输出、PR 评论	API 调用
离线/本地	✅ 完全支持（SQLite + 本地模式）	❌ 依赖云服务
提供商	8 个原生提供商 + 通用适配器	通过 LangChain 间接支持
自托管	✅ Docker Compose 一键部署	✅ 企业版
开源	✅ MIT	✅ Apache 2.0

简单说：LangSmith 帮你看懂 Agent 的行为，AgentBench 帮你验证 Agent 的行为是否正确。

Q: 支持哪些 LLM 提供商？

A: v0.3.0 原生支持 8 个提供商：OpenAI、Anthropic、Google Gemini、DeepSeek、Azure OpenAI、OpenRouter、Groq、Ollama。MCP 协议支持任意 MCP 兼容的工具服务器。通用适配器可对接任意 Agent。详见 SDK 使用指南。

---

安装与部署

Q: 一定要用 Docker 吗？

A: Docker 用于运行 PostgreSQL 和 Redis。如果你已有这两个服务，可以直接配置 .env 中的连接字符串，无需 Docker。

Q: 能用 SQLite 代替 PostgreSQL 吗？

A: 目前不支持。v0.1.0 仅支持 PostgreSQL。SQLite 适配器在路线图中。

Q: 如何部署到生产环境？

A: 参考 部署指南。推荐 Docker Compose 一键部署，或部署到 Vercel + 外部 PostgreSQL。

Q: API 有认证吗？

A: v0.3.0 中 API 认证是可选的（支持 ab- 前缀的 API Key）。v1.0 将完整集成 NextAuth.js。

Q: 如何从 v0.2.0 迁移到 v0.3.0？[NEW in v0.3.0]

A: 迁移步骤：

1. 更新配置文件：v0.3.0 引入了 providers 配置节。将原来的 model.provider 和 model.model 迁移到新的 providers 格式：

   // v0.2.0（旧格式）
   model: { provider: 'openai', model: 'gpt-4o', temperature: 0.7, maxTokens: 4096 }
   
   // v0.3.0（新格式）
   providers: {
     openai: { apiKey: process.env.OPENAI_API_KEY, defaultModel: 'gpt-4o' }
   }

2. 运行配置验证：agentbench config validate 检查配置兼容性
3. 重新生成配置（可选）：agentbench init --force 生成 v0.3.0 标准配置
4. 更新 SDK 包：新增的 6 个提供商按需安装
5. 数据库兼容：v0.3.0 向后兼容 v0.2.0 数据库，pnpm db:push 会自动添加新表（datasets、benchmarks）

---

使用

Q: 如何创建一个测试？

A: 完整流程：

1. 创建 Project → 2. 创建 Test Suite → 3. 创建 Test Case（含断言和评估器）→ 4. 创建 Run → 5. 评估 Run 参考 快速入门。

Q: 断言 DSL 怎么用？

A: 链式 API，读起来像英文：

expect(run)
  .tool("search").toBeCalled()
  .output().toContain("退款")
  .tokens().toBeLessThan(4096)
  .run()

详见 API 参考。

Q: 可以不给 API 调用付费就测试 Agent 吗？[NEW in v0.3.0]

A: 可以！v0.3.0 提供了三种低/零成本方案：

1. 回放测试（agentbench test --replay）：从之前的 Trace 回放，不需要新的 API 调用
2. 本地模型（agentbench run --provider ollama --model llama3）：使用 Ollama 运行本地模型，零 API 费用
3. 快照测试：创建基线快照后，后续对比不需要重新调用 LLM
4. Groq 免费层：Groq 提供免费的推理 API 额度，适合开发阶段快速迭代

Q: 如何添加新的 LLM 提供商支持？[NEW in v0.3.0]

A: v0.3.0 提供了 Provider Plugin 架构，支持两种方式：

1. API 兼容方式（推荐）：如果你的提供商 API 兼容 OpenAI 格式，继承 OpenAICompatibleProvider 基类即可：

   import { OpenAICompatibleProvider } from '@agentbench/provider-utils'
   
   class MyProvider extends OpenAICompatibleProvider {
     constructor() {
       super('my-provider', 'My Provider', 'https://api.myprovider.com/v1')
     }
     // 大多数方法已由基类实现，只需重写差异部分
   }

2. 完整实现方式：实现 AgentBenchProvider 接口，自定义所有方法。 详见 SDK 使用指南 中的「构建自定义 Provider」章节。

Q: AgentBench 支持流式输出吗？[NEW in v0.3.0]

A: 完全支持。所有 8 个提供商的 SDK 都支持流式和非流式两种模式：

• createChatCompletion() — 非流式，返回完整结果
• createStreamingChatCompletion() — 流式，实时回调每个 chunk

CLI 中使用 --stream 标志实时查看 Agent 响应：

agentbench run --provider openai --model gpt-4o --stream

Q: Replay 测试和 Snapshot 测试有什么区别？[NEW in v0.3.0]

A:

特性	Replay	Snapshot
原理	使用保存的 Trace 重新执行相同的 LLM 调用序列	保存完整的执行上下文（状态、变量、工具结果）
是否需要 API	是（实际调用 LLM）	否（纯状态恢复）
用途	跨模型对比、回归检测	快速状态恢复、调试
确定性	依赖 seed 和模型	完全确定
速度	慢（需要真实 API 调用）	快（纯数据操作）
典型场景	"换 Claude 跑一遍看结果差多少"	"回到上次的状态再调试"

简单说：Replay 是"重跑一遍"，Snapshot 是"回到那个状态"。

Q: 能用本地模型（Ollama）吗？[NEW in v0.3.0]

A: 完全支持。v0.3.0 提供了 @agentbench/ollama 包：

# 安装 Ollama 并拉取模型
ollama pull llama3

# 初始化 AgentBench 配置
agentbench init --provider ollama

# 运行测试
agentbench run --provider ollama --model llama3
agentbench test --project <project-id> --provider ollama --model llama3

Ollama 支持所有 AgentBench 功能：运行、测试、回放、评估、实验。注意本地模型的性能可能与云端模型有差异，建议在 CI/CD 中使用快照测试，本地开发中使用 Ollama 快速迭代。

Q: LLM Judge 是什么？

A: LLM Judge 使用一个 LLM（如 GPT-4o）来评判另一个 Agent 的输出质量。支持 8 个维度：正确性、忠实度、安全性、相关性、完整性、推理质量、简洁性、工具使用。

Q: LLM Judge 的费用怎么算？

A: 每次 Judge 调用都会消耗 Token。建议使用便宜的模型（如 gpt-4o-mini）作为 Judge，并在配置中设置最大 Token 限制。

Q: 如何对比两个 Prompt 哪个更好？

A: 使用 Experiment（A/B 实验）功能。创建两个 Variant，各运行 N 次，AgentBench 会自动计算 t-test、p-value 和效应量，给出统计结论。

Q: 如何检测 Agent 是否退化？

A: 创建基线快照 → 修改 Prompt/模型 → 回放 → AgentBench 自动对比 Metrics 和 Scores，标记回归。

Q: 支持的断言类型有哪些？

A: 14 种规则评估器 + 8 种 LLM Judge 维度。包括：contains、exact_match、regex_match、json_schema、tool_called、tool_not_called、tool_called_with、tool_called_times、latency_lt、tokens_lt、tokens_gt、cost_lt、cost_gt、status_code。

---

故障排查

Q: 启动报错 "Foreign key constraint violated"

A: 这是数据库初始化问题。确保你运行了 pnpm db:push（不是 db:migrate），这将自动创建所有表。

Q: 创建 Project 返回 500

A: 检查 PostgreSQL 是否在运行：docker compose ps。确保 DATABASE_URL 环境变量正确。

Q: pnpm dev 启动失败

A: 最常见的原因是 CLI 包的 tsup 找不到配置文件。已修复为 tsc --watch。如果仍有问题，可以单独启动 web：

cd apps/web && npx next dev --port 3000

Q: TypeScript 类型错误

A: 当前版本 0 TypeScript 错误（strict mode）。如果你看到类型错误，确保运行了 pnpm db:generate 生成 Prisma Client。

---

→ 返回文档中心