CLI Reference

CLI 命令参考

AgentBench CLI 提供 13 个命令（v0.3.0），覆盖 Agent 测试全流程。新增 dataset、benchmark、dev、config、experiment 命令。

安装

pnpm install
pnpm --filter agentbench exec agentbench --help

或全局安装后直接使用 agentbench 命令。

全局选项

选项	说明
`-V, --version`	显示版本号
`-h, --help`	显示帮助信息

环境变量：

AGENTBENCH_API_URL — API 地址（默认 http://localhost:3000/api/v1）
AGENTBENCH_CONFIG — 配置文件路径（默认 ./agentbench.config.ts）

`agentbench init`

v0.3.0 全新设计。交互式初始化向导，支持多提供商配置。

agentbench init                          # 交互模式
agentbench init --provider openai        # 快速初始化（OpenAI）
agentbench init --provider anthropic     # 快速初始化（Anthropic）
agentbench init --provider deepseek      # 快速初始化（DeepSeek）
agentbench init --provider ollama        # 快速初始化（本地 Ollama）
agentbench init --force                  # 覆盖已有配置
agentbench init --template ci            # CI/CD 模板
agentbench init --template benchmark     # Benchmark 模板

选项	说明
`--provider <p>`	预设提供商：`openai`、`anthropic`、`gemini`、`deepseek`、`azure`、`openrouter`、`groq`、`ollama`
`--template <t>`	配置模板：`default`、`ci`、`benchmark`、`minimal`
`--force`	覆盖已有配置文件
`--ci`	非交互模式（适合 CI/CD）

生成的配置文件（v0.3.0 格式）：

import { defineConfig } from '@agentbench/core'

export default defineConfig({
  name: 'my-agent-project',
  version: '0.3.0',
  providers: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY,
      defaultModel: 'gpt-4o',
    },
    deepseek: {
      apiKey: process.env.DEEPSEEK_API_KEY,
      baseURL: 'https://api.deepseek.com/v1',
    },
    ollama: {
      baseURL: 'http://localhost:11434',
      defaultModel: 'llama3',
    },
  },
  tests: {
    timeout: 30000,
    maxSteps: 10,
    retries: 1,
    concurrency: 4,
  },
  datasets: {
    directory: './datasets',
    defaultFormat: 'jsonl',
  },
  benchmarks: {
    directory: './benchmarks',
  },
  reports: {
    formats: ['json', 'html', 'markdown', 'junit'],
    outputDir: './reports',
  },
})

`agentbench run`

创建并执行一个 Agent Run。v0.3.0 支持所有 8 个提供商。

agentbench run \
  --project <project-id> \
  --name "GPT-4o Baseline" \
  --provider openai \
  --model gpt-4o \
  --temperature 0.7 \
  --max-tokens 4096 \
  --verbose

# v0.3.0 新增提供商
agentbench run --provider deepseek --model deepseek-v3
agentbench run --provider groq --model llama-3.1-70b
agentbench run --provider ollama --model llama3
agentbench run --provider openrouter --model anthropic/claude-sonnet-4
agentbench run --provider gemini --model gemini-2.5-pro
agentbench run --provider azure --model gpt-4o

选项	必填	说明
`-p, --project <id>`	✅	项目 ID
`-n, --name <name>`	✅	Run 名称
`-m, --model <model>`		模型名称（默认 `gpt-4o`）
`--provider <p>`		LLM 提供商：`openai`、`anthropic`、`gemini`、`deepseek`、`azure`、`openrouter`、`groq`、`ollama`（默认 `openai`）
`--temperature <t>`		温度参数（默认 `0.7`）
`--max-tokens <n>`		最大 Token（默认 `4096`）
`--seed <n>`		[NEW] 随机种子（用于确定性回放）
`--concurrency <n>`		[NEW] 并发数（默认 `1`）
`--max-steps <n>`		最大步数（默认 `10`）
`-v, --verbose`		详细输出
`--dry-run`		[NEW] 仅验证配置，不实际执行
`--stream`		[NEW] 实时流式输出 Agent 响应

`agentbench test`

运行测试套件。v0.3.0 新增 --watch、--coverage、--replay、--json、--junit、--ci 等标志。

agentbench test \
  --project <project-id> \
  --suite <suite-id> \
  --grep "customer-support" \
  --verbose \
  --format table

# v0.3.0 新增用法
agentbench test --watch                              # 监听模式，文件变更自动重跑
agentbench test --coverage                           # 生成覆盖率报告
agentbench test --replay                             # 从上次运行的 trace 回放
agentbench test --json                               # JSON 输出
agentbench test --junit                              # JUnit XML 输出
agentbench test --ci                                 # CI 模式（非交互 + JUnit）
agentbench test --provider deepseek --model deepseek-v3  # 跨模型测试

选项	必填	说明
`-p, --project <id>`	✅	项目 ID
`-s, --suite <id>`		按套件过滤
`-g, --grep <pattern>`		按名称正则过滤
`--verbose`		显示每个用例的详细结果
`--format <fmt>`		输出格式：`table`、`json`、`junit`
`--watch`		[NEW] 监听文件变更，自动重跑测试
`--coverage`		[NEW] 生成覆盖率报告
`--replay`		[NEW] 从上次运行的 Trace 回放，适用于快速回归检测
`--json`		[NEW] 以 JSON 格式输出结果
`--junit`		[NEW] 以 JUnit XML 格式输出（CI/CD 集成）
`--ci`		[NEW] CI 模式：非交互 + JUnit 输出 + 退出码
`--provider <p>`		[NEW] 覆盖提供商配置
`--model <m>`		[NEW] 覆盖模型配置

输出示例：

⚡ Running tests...
  Suites: 3
  Test cases: 12

  ✓ greeting: 5/5 passed (2340ms)
  ✓ refund_check: 4/4 passed (1890ms)
  ✗ escalation: 2/3 failed (3200ms)

────────────────────────────────────────────
Summary:
  ✓ 10 passed
  ✗ 1 failed
  ⚠ 0 errors

`agentbench evaluate`

用规则评估一个 Run。v0.3.0 新增 --config 和 --auto-judge 标志。

agentbench evaluate <run-id> \
  --contains "退款" \
  --tool "search_docs" \
  --tool-not "hallucinate" \
  --latency-lt 5000 \
  --tokens-lt 4096 \
  --cost-lt 0.01 \
  --expected "用户可以在30天内退款" \
  --verbose

# v0.3.0 新增用法
agentbench evaluate <run-id> --config evaluate.config.ts  # 从配置文件加载规则
agentbench evaluate <run-id> --auto-judge                  # 自动 LLM Judge 评估
agentbench evaluate <run-id> --dimensions correctness,faithfulness,safety  # 指定评估维度

选项	说明
`--contains <text>`	输出包含指定文本
`--tool <name>`	指定工具被调用过
`--tool-not <name>`	指定工具未被调用
`--latency-lt <ms>`	延迟低于阈值
`--tokens-lt <n>`	Token 用量低于阈值
`--cost-lt <dollars>`	费用低于阈值
`--expected <text>`	期望输出（精确匹配）
`--json-schema <path>`	JSON Schema 文件路径
`--config <path>`	[NEW] 从文件加载评估规则配置
`--auto-judge`	[NEW] 使用 LLM Judge 自动评估
`--dimensions <list>`	[NEW] 评估维度（逗号分隔）：`correctness`、`faithfulness`、`safety`、`relevance`、`completeness`、`reasoning`、`conciseness`、`tool_use`
`--judge-model <m>`	[NEW] LLM Judge 使用的模型
`-v, --verbose`	显示每条规则的详细结果

`agentbench replay`

回放一个 Run。v0.3.0 新增快照回放模式。

agentbench replay <run-id> \
  --model claude-sonnet-5 \
  --provider anthropic \
  --mode cross_model

agentbench replay <run-id> \
  --mode batch \
  --batch-count 10 \
  --seed 42

# v0.3.0 新增用法
agentbench replay --from-snapshot <snapshot-id>   # 从快照回放
agentbench replay <run-id> --output-diff          # 回放后输出 diff
agentbench replay <run-id> --auto-evaluate        # 回放后自动评估

选项	说明
`-m, --model <model>`	回放时使用的模型
`--provider <p>`	回放时使用的提供商
`--temperature <t>`	覆盖温度参数
`--mode <mode>`	回放模式：`deterministic`、`cross_model`、`batch`
`--batch-count <n>`	批量回放次数（默认 5）
`--seed <n>`	确定性回放的种子
`--no-parallel`	禁用并行（批量模式）
`--from-snapshot <id>`	[NEW] 从快照回放
`--output-diff`	[NEW] 回放后输出与原始运行的 diff
`--auto-evaluate`	[NEW] 回放后自动触发评估

`agentbench compare`

对比两个 Run。

agentbench compare <run-a-id> <run-b-id>
agentbench compare <run-a-id> <run-b-id> --format json
agentbench compare <run-a-id> <run-b-id> --dimensions tokens,cost,latency,scores  # v0.3.0 新增

选项	说明
`--format <fmt>`	输出格式：`table`、`json`、`markdown`
`--dimensions <list>`	[NEW] 对比维度（逗号分隔）
`--threshold <n>`	[NEW] 差异阈值高亮（如 `--threshold 0.1` 表示 10% 差异时高亮）

输出：

Comparison:
  Status:    passed vs passed
  Duration:  2340ms vs 1890ms  (-19.2%)
  Tokens:    2847 vs 2103      (-26.1%)
  Cost:      $0.0089 vs $0.0065 (-27.0%)
  Steps:     3 vs 2
  Scores:    correctness 0.92 vs 0.88  ⚠ regression

`agentbench snapshot`

快照管理。

# 创建快照
agentbench snapshot create \
  --project <project-id> \
  --run <run-id> \
  --name "v1.0 基线"

# 列出快照
agentbench snapshot list --project <project-id>

# 恢复快照
agentbench snapshot restore <snapshot-id>
agentbench snapshot restore <snapshot-id> --model gpt-5

# v0.3.0 新增
agentbench snapshot diff <snapshot-a-id> <snapshot-b-id>  # 快照对比
agentbench snapshot export <snapshot-id> --format json     # 导出快照

`agentbench report`

生成报告。v0.3.0 新增多格式导出和批量报告。

agentbench report <run-id>
agentbench report <run-id> --format json
agentbench report <run-id> --format html      # [NEW] HTML 报告
agentbench report <run-id> --format junit     # [NEW] JUnit XML 报告
agentbench report --project <project-id> --format markdown   # 批量项目报告
agentbench report <run-id> --coverage         # [NEW] 包含覆盖率报告

选项	说明
`--format <fmt>`	报告格式：`json`、`markdown`、`html`、`junit`
`--output <path>`	[NEW] 输出文件路径
`--coverage`	[NEW] 包含覆盖率数据
`--open`	[NEW] 生成后自动在浏览器打开

`agentbench dataset` [NEW in v0.3.0]

数据集管理。10 个子命令。

# 导入数据集
agentbench dataset import ./data.jsonl --name "客服对话" --format jsonl
agentbench dataset import ./data.csv --name "训练集" --format csv
agentbench dataset import ./data.json --name "测试用例" --format json

# 导出数据集
agentbench dataset export <dataset-id> --format csv --output ./export.csv
agentbench dataset export <dataset-id> --format jsonl

# 验证数据集
agentbench dataset validate <dataset-id>
agentbench dataset validate <dataset-id> --strict   # 严格模式

# 数据集切分
agentbench dataset split <dataset-id> --train 0.7 --test 0.2 --val 0.1
agentbench dataset split <dataset-id> --stratify-by label  # 分层抽样

# 数据集采样
agentbench dataset sample <dataset-id> --count 100
agentbench dataset sample <dataset-id> --ratio 0.1 --stratified

# 版本管理
agentbench dataset version <dataset-id>                       # 查看版本列表
agentbench dataset version <dataset-id> --create "v2"         # 创建新版本
agentbench dataset version <dataset-id> --diff v1 v2          # 版本 diff

# 数据集对比
agentbench dataset diff <dataset-a-id> <dataset-b-id>
agentbench dataset compare <dataset-a-id> <dataset-b-id>      # 统计对比

# 列表
agentbench dataset list                                       # 列出所有数据集
agentbench dataset list --project <project-id>                # 按项目过滤

# 查看详情
agentbench dataset info <dataset-id>                          # 数据集详情

子命令	说明
`import`	从文件导入数据集（CSV、JSON、JSONL）
`export`	导出数据集到文件
`validate`	验证数据集完整性和质量
`split`	切分数据集（train/test/val）
`sample`	从数据集中采样
`version`	数据集版本管理（list、create、diff）
`diff`	两个数据集差异对比
`compare`	两个数据集统计对比
`list`	列出所有数据集
`info`	查看数据集详情和统计信息

`agentbench benchmark` [NEW in v0.3.0]

Benchmark 管理。7 个子命令。

# 搜索 Benchmark
agentbench benchmark search "客服"                              # 搜索注册表中的 benchmark
agentbench benchmark search --tag conversation                  # 按标签搜索

# 查看 Benchmark 详情
agentbench benchmark info customer-service                      # 查看 benchmark 信息
agentbench benchmark info customer-service --stats              # 含统计信息

# 安装 Benchmark
agentbench benchmark install customer-service                   # 从注册表安装
agentbench benchmark install customer-service --version 2.0.0   # 指定版本

# 运行 Benchmark
agentbench benchmark run customer-service                       # 运行已安装的 benchmark
agentbench benchmark run customer-service --provider deepseek   # 使用指定提供商
agentbench benchmark run customer-service --model deepseek-v3   # 使用指定模型
agentbench benchmark run customer-service --repeat 5            # 重复运行 5 次

# 提交结果到 Leaderboard
agentbench benchmark submit customer-service                    # 提交结果
agentbench benchmark submit customer-service --public           # 公开提交

# 发布 Benchmark（创建者）
agentbench benchmark publish ./my-benchmark                     # 发布新 benchmark
agentbench benchmark publish ./my-benchmark --version 1.1.0     # 更新版本

# 列出已安装的 Benchmark
agentbench benchmark list
agentbench benchmark list --installed                           # 仅已安装的

子命令	说明
`search`	搜索 AgentBench 注册表中的 Benchmark
`info`	查看 Benchmark 详情、任务、指标
`install`	从注册表安装 Benchmark
`run`	运行 Benchmark（支持多提供商、多模型）
`submit`	提交结果到公开 Leaderboard
`publish`	发布自定义 Benchmark 到注册表
`list`	列出可用/已安装的 Benchmark

`agentbench experiment` [NEW in v0.3.0]

A/B 实验管理。

# 创建实验
agentbench experiment create \
  --project <project-id> \
  --name "Prompt A vs B" \
  --variant-a '{"systemPrompt":"你是一个乐于助人的客服"}' \
  --variant-b '{"systemPrompt":"你是一个专业的客服，语气正式"}' \
  --runs-per-variant 10

# 运行实验
agentbench experiment run <experiment-id>

# 查看结果
agentbench experiment results <experiment-id>
agentbench experiment results <experiment-id> --format json

# 列出实验
agentbench experiment list --project <project-id>

选项	说明
`--name <name>`	实验名称
`--variant-a <json>`	变量 A 配置（JSON）
`--variant-b <json>`	变量 B 配置（JSON）
`--runs-per-variant <n>`	每个变量的运行次数（默认 10）
`--test-case <id>`	指定测试用例
`--suite <id>`	指定测试套件

`agentbench config` [NEW in v0.3.0]

配置管理。

agentbench config show                          # 显示当前生效配置
agentbench config show --source                 # 显示每个配置的来源
agentbench config validate                      # 验证配置文件
agentbench config path                          # 显示配置文件路径
agentbench config set tests.timeout 60000       # 设置配置项
agentbench config get tests.timeout             # 获取配置项
agentbench config edit                          # 在编辑器中打开配置文件

子命令	说明
`show`	显示当前生效的全部配置
`validate`	验证配置文件
`path`	显示配置文件路径
`set <key> <value>`	设置配置项
`get <key>`	获取配置项
`edit`	在编辑器中打开配置文件

`agentbench dev` [NEW in v0.3.0]

开发模式，提供交互式开发体验。

agentbench dev                                  # 启动开发模式
agentbench dev --project <project-id>           # 指定项目
agentbench dev --port 3001                      # 自定义端口
agentbench dev --open                           # 自动打开浏览器

开发模式特性：

热重载：配置文件变更自动重跑测试
交互式 REPL：即时测试 prompt 和断言
Trace 检查器：逐步查看 Agent 执行过程
内联错误提示：实时显示断言失败原因

→ 返回文档中心

AgentBench v0.3.0 · GitHub · Report Issue · Changelog

AgentBench v0.3.0

Home

Getting Started

Core Concepts

Core-Concepts
Replay & Snapshots
Assertions & Evaluation
Coverage & Non-Determinism

How-To Guides

Guides
Testing OpenAI / Anthropic
CI/CD Integration
Custom-Providers
Migration-Guide

Reference

Cookbook

Cookbook
Prompt Regressions
Model Migration
Cost Budgets
Safety Testing
A/B Testing

CLI Reference

CLI 命令参考

安装

全局选项

agentbench init

agentbench run

agentbench test

agentbench evaluate

agentbench replay

agentbench compare

agentbench snapshot

agentbench report

agentbench dataset [NEW in v0.3.0]

agentbench benchmark [NEW in v0.3.0]

agentbench experiment [NEW in v0.3.0]

agentbench config [NEW in v0.3.0]

agentbench dev [NEW in v0.3.0]

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AgentBench v0.3.0

Getting Started

Core Concepts

How-To Guides

Reference

Cookbook

Community

Ecosystem

Clone this wiki locally

`agentbench init`

`agentbench run`

`agentbench test`

`agentbench evaluate`

`agentbench replay`

`agentbench compare`

`agentbench snapshot`

`agentbench report`

`agentbench dataset` [NEW in v0.3.0]

`agentbench benchmark` [NEW in v0.3.0]

`agentbench experiment` [NEW in v0.3.0]

`agentbench config` [NEW in v0.3.0]

`agentbench dev` [NEW in v0.3.0]