> ## Documentation Index
> Fetch the complete documentation index at: https://qitor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tau-Bench

> 通过 `TauBenchAdapter` 在零售与航空客服环境中评测工具-智能体-用户交互。

Tau-Bench 用来评测智能体作为客服代表时的表现：它需要阅读策略文档、调用数据工具，并在不违反业务规则的前提下完成模拟用户请求。

QitOS 提供：

* `TauBenchAdapter`
* 自包含运行时 `TauRuntimeEnv`

因此你不必额外安装上游 `tau_bench` 包，就可以直接运行该基准测试。`TauRuntimeEnv` 提供了自包含的运行时环境。

## 可用环境

| 环境        | 可用划分                 | 终止工具                       |
| --------- | -------------------- | -------------------------- |
| `retail`  | `train`、`dev`、`test` | `transfer_to_human_agents` |
| `airline` | `test`               | `transfer_to_human_agents` |

## 准备工作

```bash theme={null}
pip install "qitos[benchmarks]"
export OPENAI_API_KEY="sk-..."
```

<Note>
  Tau-Bench 的任务数据已经内置于 QitOS 包中，无需额外下载。
</Note>

## 加载任务

```python theme={null}
from qitos.benchmark import TauBenchAdapter

adapter = TauBenchAdapter(env_name="retail", task_split="test")
records = adapter.load_records()
tasks = adapter.to_tasks(records, split="test", limit=5)
```

也可以用一行式加载器：

```python theme={null}
from qitos.benchmark.tau_bench.adapter import load_tau_bench_tasks

tasks = load_tau_bench_tasks(env_name="retail", split="test", limit=10)
```

## 运行评测

优先使用官方命令行：

```bash theme={null}
qit bench run \
  --benchmark tau-bench \
  --split test \
  --subset retail \
  --limit 50 \
  --output results/tau_retail_test.jsonl \
  --model-name "Qwen/Qwen3-8B"
```

然后继续做聚合与检查：

```bash theme={null}
qit bench eval --input results/tau_retail_test.jsonl --json
qita board --logdir runs
```

`tau_bench_eval.py` 依然保留，但它现在只是同一套官方结果结构与追踪记录契约上的基准测试封装器。

运行单个任务：

```bash theme={null}
python examples/benchmarks/tau_bench_eval.py \
  --tau-env retail \
  --tau-split test \
  --task-index 0 \
  --max-steps 30 \
  --model-name "Qwen/Qwen3-8B" \
  --api-key "$OPENAI_API_KEY"
```

运行完整基准测试：

```bash theme={null}
python examples/benchmarks/tau_bench_eval.py \
  --run-all \
  --tau-env retail \
  --tau-split test \
  --num-trials 3 \
  --limit 50 \
  --concurrency 4 \
  --output-jsonl results/tau_retail_test.jsonl \
  --trace-logdir runs \
  --model-name "Qwen/Qwen3-8B" \
  --api-key "$OPENAI_API_KEY"
```

## 运行时如何工作

`TauRuntimeEnv` 提供了最小可替换的 `reset / step / calculate_reward` 接口。奖励通过重放真实动作序列并比较最终状态哈希来计算。

智能体只有在工具调用引起了正确状态转移、且文本回复中包含了要求的输出值时，才会得到 `1.0`。

## 检查结果

典型结果 JSONL 会记录：

* `task_id`
* `trial`
* `env`
* `reward`
* `success`
* `stop_reason`
* `steps`
* `latency_seconds`

你也可以用 `qita` 检查具体运行：

```bash theme={null}
qita board --logdir runs
qita replay --run runs/<run_id>
```