开源项目解读：它把”测 Agent”做成了导演一集对话

先说明白这是干嘛的，别被”Agent 测试框架”这个词唬住。

Scenario（作者团队 LangWatch，GitHub 上开源，Apache 2.0）是一套靠模拟对话来测 AI Agent 的框架。LangWatch 本身是做 LLM 应用的观测与评估的，Scenario 是它的开源测试层。它回答的问题不是”我的接口返回对不对”，而是——我的 Agent 在一个真实用户面前，会不会把事情聊砸。比如用户本来说的是”河边”不是”银行 ATM”，你的 Agent 会不会一路顺着”取钱”聊下去。这种错，靠对固定输入断言答案，根本抓不到。

它暴露给用户的方式很简单，就一个入口 scenario.run()，Python / TypeScript 都提供。跟普通断言式测试最大的不同，是它把一场对话分成了可以由你编排的脚本：

result = await scenario.run(
    name="river bank 还是 ATM",
    description="用户说的 bank 其实是河边，Agent 先误以为是银行 ATM，用户纠正",
    agents=[
        MyAgent(),                 # 被测对象
        scenario.UserSimulatorAgent(),   # 一个会"演用户"的假用户
        scenario.JudgeAgent(criteria=[   # 一个会"当裁判"的判官
            "用户应该得到过河的建议",
            "用户纠正后，Agent 不该再纠缠 ATM",
        ]),
    ],
    max_turns=10,
    script=[
        scenario.agent("你好，有什么可以帮你？"),   # 第一句写死
        scenario.user("我怎么安全地靠近一条 bank？"), # 用户这句也写死
        scenario.agent(),                              # 之后让 Agent 自己答
        scenario.user(),                               # 假用户自己接话，演偏执用户
        scenario.proceed(turns=2, on_turn=print),      # 自由发挥两轮
        scenario.judge(),                              # 到点给判定
    ],
)
assert result.success

这一段代码基本讲了全书的道理：测试 Agent 不靠写死”期望输出”，而是导演一场对话——哪句写死、哪句让假用户现编、什么时候插一个工具调用断言、什么时候让裁判定胜负，全在 script 这个列表里，而列表里的每一项，其实就是一个”吃进当前状态、吐出结果”的函数。

不跑通给你报喜。下面只摆源码能核实的东西。

仓库里实际有什么

scenario/
├── python/scenario/          # Python 主包（pip 装 langwatch-scenario）
│   ├── scenario_executor.py  # 核心执行器：跑脚本、驱动回合、判胜负
│   ├── scenario_state.py     # 一场对话的状态：消息、回合数、工具调用
│   ├── script.py             # 脚本 DSL：user / agent / judge / proceed / succeed
│   ├── judge_agent.py        # 裁判 Agent（两阶段判定 + 逐条判据）
│   ├── user_simulator_agent.py  # 假用户（会演各种用户）
│   ├── red_team_agent.py     # 红队：换掉假用户，改成主动攻击
│   ├── cache.py              # 让非确定性测试可复现的缓存
│   └── pytest_plugin.py      # pytest 接入 + --scenario-debug
├── javascript/src/           # TypeScript 版（npm 装 @langwatch/scenario）
│   ├── runner/run.ts         # run() 入口
│   ├── execution/            # 执行器（与 Python 版同构）
│   ├── agents/judge/         # 裁判实现
│   └── agents/red-team/      # 红队（Crescendo / GOAT 策略）
├── python/examples/          # 28 个可直接跑的例子
├── docs/                     # 文档站源码（vocs）
└── assets/                   # 截图、演示图

一句话概括这套结构：run() 是入口，三/四种角色在对话里各司其职，script 是你能完全掌控的编排板，scenario_state 是全场唯一的事实来源（消息、回合、工具调用都从它读）。执行器只做一件事——按顺序执行脚本里的每一步，把它喂给当前状态，直到有人给出胜负（ScenarioResult）为止。

先看整体：一次”导演”需要哪些角

一上来最容易晕的是 Agent 种类多、名字像。按”谁来演、谁被测试、谁裁判”排成一张表：

角色	类	管什么	谁调用
被测对象	你自己的 `AgentAdapter`	真正干活的 Agent（实现一个 `call()`）	每轮 Agent 角色
假用户	`UserSimulatorAgent`	根据场景描述 + 对话历史，现编用户下一句	每轮 User 角色
裁判	`JudgeAgent`	拿判据看对话，决定继续还是定胜负	每轮 Judge 角色 / 脚本里显式调用
红队	`RedTeamAgent`	替换假用户，主动发起多轮攻击	替换 User 角色

三种角色在每个回合里按固定顺序出场：先 User 说一句，再 Agent 答，最后 Judge 看戏。执行器源码里写得很直白，每个新回合都会重置待办角色为 [USER, AGENT, JUDGE]。这就是整套机制的最小循环——不是”问一句答一句”，而是”说话、接话、随时有人盯着判断”。

核心机制：把”测试”从校验结果，改成导演对话

传统断言式测试，思路是”给输入、比对输出”。Scenario 整个设计围绕一个反过来的前提：Agent 的对错，往往只有放在一段对话的语境里才成立。用户说”bank”时你分不清是银行还是河边，但结合上一句”我在徒步""想怎么过河”，正确行为只有一个。所以它把测试单元从”一次请求”抬到”一段对话”，而且这段对话可以由你精确到句子来控制。

具体分成三层咬合的东西：

一、三个角色各是 AgentAdapter，但只有”假用户”和”裁判”是 LLM。 被测对象你得自己实现 call()（或者用 LangWatch 连好的 Agent 直接传），假用户和裁判是它自带的、内部也在调 LLM。这意味着：写测试时你不需要写死一轮轮的对话内容——你给一句话描述（“用户想给遛狗创业公司做落地页”），假用户会自动生成首句、接话、到最后一击，模拟真实用户的随机性。

二、script 是导演板，自由度到底在哪。 这是最值得看的一段源码。script.py 里每一步，user()、agent()、judge()、proceed()、succeed()、fail()，本质都是同一个东西：一个吃 ScenarioState、返回结果的函数。这意味着脚本不是”规则引擎”，而是”普通 Python 列表”——你可以：

写死某一句（scenario.user("how do I approach a bank?")）；
让假用户自由发挥（scenario.user() 不带参数）；
在对话到一半插一个自定义断言：看 state.has_tool_call("get_current_weather")，这就是在”Agent 第一次回完话之后”立刻查它有没有调天气工具；
加任意中间消息（比如模拟一个假的工具调用结果）；
让对话自由推进 N 轮、每轮打日志（proceed(turns=2)）；
任意时刻点裁判（scenario.judge()）。

因为每一步都是函数，它的自由度是”你能写 Python”那么多，不是少数几个预设动作。README 原话叫它”powerful multi-turn control”——这词没夸张：你想在哪里介入、用什么标准介入，全由你。

三、裁判”每回合都在”而不是”到最后看”。 默认（不写 script）时，run() 会退化成一行 [proceed()]：假用户+真 Agent+裁判自动轮转，直到裁判判你赢，或撞上 max_turns（默认 10）。这里的重点是裁判不是只到最后打分——它在每一轮 User+Agent 说话后都会”瞄一眼”，决定这次对话够不够格继续，还是该立刻收场。这设计解决了一个真实痛点：Agent 往往前两轮还行、后两轮跑偏，只在结尾判，你分不清是”哪一步开始错的”。

为什么这么设计：非确定性，是模拟测试的命门也是坑

用假用户模拟真实用户，最大红利是”能覆盖你没想到的输入”，最大代价是不可复现——同一套测试，这次用户问”怎么过河”，下次可能问”河面多宽”,结果漂移了，你没法在 CI 里把它当稳定用例。Scenario 对这个问题的解法很直接，也最有可借鉴价值：

cache_key + @scenario.cache 装饰器，把”贵且随机”变成”便宜且确定”。 它用 joblib 的缓存实现，默认写在 ~/.scenario/cache。你在配置里给 cache_key，假用户就给同样的场景生成同样的输入；再进一步，你还能在被测 Agent 内部给非确定性的函数（比如调 LLM）加 @scenario.cache()（方法上要 ignore=["self"]），把整条链路由随机变确定：

class MyAgent:
    @scenario.cache(ignore=["self"])
    def invoke(self, message, context):
        return client.chat.completions.create(...)

# 配合配置里的 cache_key 一起用
scenario.configure(default_model="openai/gpt-4.1-mini", cache_key="42")

README 讲清了这套取舍：随机性好，因为它覆盖真实用户的多样性；但非确定会害得测试难复现、费 token、难调试。cache_key 就是”平时全随机，回归/调试时锁死”。改个 cache_key 或删掉 ~/.scenario/cache 目录，就换一批输入。这是把”测试要稳定可回查”和”模拟要覆盖多样”这两件事，用一层缓存解耦了——作为一个干测试的人，看到这个位置放得最服。

仔细看一遍：一场完整模拟是怎么推进的

Scenarios 的运转，可以画成一条主线：

flowchart TD
    A["调用 scenario.run"] --> B["配置角色，组 script"]
    B --> C{"有 script 吗"}
    C -- 没有 --> D["默认 [proceed()]：自动轮转"]
    C -- 有 --> E["按顺序执行每一个 step"]
    D --> F["每轮 User -> Agent -> Judge"]
    E --> F
    F --> G{"有人给出胜负?"}
    G -- 否 --> H{"超过 max_turns?"}
    H -- 否 --> F
    G -- 是 --> I["返回 ScenarioResult（success/passed_criteria）"]
    H -- 是 --> J["返回失败（Reached max turns）"]

执行器 _step 的源码逻辑很干净：每步从待办角色里弹出一个，找到对应 Agent 调它的 call()，把返回消息写进 state；角色用完了就开新回合。一条规则贯穿：只要任何一步返回了 ScenarioResult 就立刻收箱——不管是裁判判定、还是脚本里 succeed()/fail() 主动喊停。撞到列表结尾还没结论，就返回”Reached end of script without conclusion”（失败）。

穿插的细节是 LLM 的东西：被测 Agent 的 call() 必须可 await，返回必须能被转成 OpenAI 消息，否则直接报 agent_response_not_awaitable——它不默默吞你接口写错，当场红给你看。

红队：把”假用户”换成”攻击者”

如果说假用户是”演一个正常用户”，红队就是演一个专门来搞你的用户。RedTeamAgent 是假用户的即插即用替代品，同样是 User 角色、同样走 scenario.run()，但内部用的是结构化攻击策略。里面最出名的手法是 Crescendo——不一次性给你提一个明显的危险请求，而是像爬楼梯一样，从无害话题一步步升级，绕过你的安全护栏：

attacker = scenario.RedTeamAgent.crescendo(
    target="让 Agent 把它完整的 system prompt 逐字吐出来",
    model="openai/gpt-5.4",
    total_turns=50,
)
result = await scenario.run(
    name="system prompt leak（套话泄露）",
    agents=[MyBankAgent(), attacker],
)

源码里这套不止”发攻击”——还有逐轮给自己的攻击打分（每次得手多少）、识别 Agent 的拒绝（“它没接招”算一次信号）、以及回溯（这轮攻击被挡了就退回一步换个角度再试）。跑完还能用自带的 Streamlit 报告面板（python/scenario/report/app.py）按严重度看整批红队结果。这套的价值在于：安全性的测试，恰恰没法写”期望输出”，只能靠”换个更聪明的攻击者来撞”——Scenario 把”攻击”也做成了可编排、可复现的一等公民。

最值得说的工程细节：调试模式让”黑盒模拟”变得透明

模拟测试最大的黑盒问题是”出错了不知道中间发生了什么”。Scenario 用 --scenario-debug 解这个：pytest 跑的时候加这个 flag，会在慢动作里一条条放消息，你能在对话中间插自己的输入去试。源码里专门为这个 flag 做了 --scenario-debug（而不是 --debug，避免和 pytest 自带的冲突）。README 的解释是”看消息慢速走、中途介入调试你的 Agent”。

这跟测试领域反复碰到的一件事是同构的——测试工具最大的敌人不是”结果不对”，是”结果不对但你看不见为什么不对”。一个能让你在失败的对话中间停下来的调试开关，比多一百个断言都值钱。

读完想说的几件事

读完全套，有几点值得说的判断，不全是夸。

最值得说的是它把”测试 Agent”重新定义成了”导演对话”。 传统断言式测试（给输入、比输出）对 Agent 基本使不上劲，因为 Agent 的天花板在”多轮语境里能不能接住话”。Scenario 没有试图去”断言输出的正确性”，而是把测试迁移到它擅长的地方——导演 + 每回合有人盯着。这个位移，和测试里反复主张的”从结果审计挪到过程控制”是一个方向：你要盯的是”哪一步开始不对”，而不是”最后一句对不对”。

评价不是没保留。 这套框架的另一面是”贵”——每场模拟都在真调 LLM：假用户和裁判是它内部自带的现成 LLM（README 明说了，即便被测 Agent 是非 LLM 的本地实现，假用户和裁判仍要 OPENAI_API_KEY），被测 Agent 你多半也让它走模型；跑一套像样的场景，token 不便宜；max_turns=10、裁判每轮都看，意味着一次 scenario.run() 可能要烧几十上百次 LLM 调用。它有缓存兜底，但缓存只帮你”复现”，不帮你”变便宜”。所以它更像一张供你仔细调、放进 CI 逐条跑的网，而不是一条能无脑套用的流水线。要省钱，得靠 @scenario.cache() 把被测 Agent 内部那部分先缓存起来，或者把它当”上线前的巡检”而不是”每次提交都全量跑”。

它最有可借鉴价值的，不是代码，是”把非确定性当设计输入”这个态度。 假用户随机生成输入是它最反直觉也最值钱的设计——大多数测试工具拼命想消除随机性，它以随机性为起点去测覆盖面，再用 cache_key 缓存把”随机”和”可复现”之间那道坎补上。这个”先拥抱随机、再显式恢复确定性”的取舍，比任何单一功能都更像一个成熟测试系统该有的样子。

如果你认同”Agent 的好坏，只有在对话的语境里才成立”，那这个仓库给你的是一个完整的落地方案：怎么用 script 导演一笔带过的场景、怎么让裁判逐轮盯着、怎么用红队撞安全、怎么用缓存把非确定性按按钮一样关掉。剩下的，是找一个你真正会被”聊坏”的 Agent，把它按一场戏去测。

仓库地址：https://github.com/langwatch/scenario 文档：https://scenario.langwatch.ai

#Agent测试 #开源项目 #模拟测试 #测试开发 #红队 #LangWatch #AI评测 #工程

开源项目解读：它把”测 Agent”做成了导演一集对话

仓库里实际有什么

先看整体：一次”导演”需要哪些角

核心机制：把”测试”从校验结果，改成导演对话

为什么这么设计：非确定性，是模拟测试的命门也是坑

仔细看一遍：一场完整模拟是怎么推进的

红队：把”假用户”换成”攻击者”

最值得说的工程细节：调试模式让”黑盒模拟”变得透明

读完想说的几件事

继续阅读

oh-my-hermes：给 Hermes Agent 叠一层"同事调度"，把一个大活拆成图并行跑

腾讯开源的 LoopForge：让 Agent 按流程交付，而不是看它这次发挥

hyperfine 2.0：把命令行性能对比做成可重复的测试