Gambit：为 AI Agent 构建可靠的验证闭环

原文来源：bolt-foundry/gambit — 一个专注于为 AI Agent 系统提供场景验证、行为评测和回归测试的开源框架

AI Agent 框架有很多——Mastra、LangGraph、OpenAI Agents SDK、CrewAI、Google ADK，每一个都在教你怎么构建 Agent。但构建只是第一步。真正棘手的部分是：你怎么知道你的 Agent 在真实场景下表现良好？当别人改了代码，你怎么确保之前能跑的场景现在还能跑？

这就是 Gambit 要解决的问题。

Gambit 不是什么

Gambit 不是一个 Agent 框架——至少不只是一个。它是一个场景验证和评测层。它的核心工作流是：

1. 创建逼真的测试场景
2. 验证场景本身的质量（是不是好的测试用例）
3. 让 Agent 在这些场景中运行
4. 对 Agent 的行为进行评分
5. 保存执行过程中的完整证据
6. 把失败的案例纳入回归测试套件

这套流程的核心洞察是：构建 Agent 很容易，但证明它可靠地工作非常难。

两种使用路径

Gambit 支持两种工作模式，取决于你是否使用 Gambit 来做 Agent 定义。

原生 Gambit 路径

如果直接用 Gambit 来定义 Agent，那么同一个系统负责从定义、运行、跟踪、测试到评分的完整闭环。Agent 定义采用 Markdown 文件（.deck.md），语法直观易读：

+++
label = "hello_world"
 
[modelParams]
model = "openai/gpt-4o-mini"
temperature = 0
+++
 
You are a concise assistant. Greet the user and echo the input.

这是最简单的 Agent 定义——一段系统提示加上模型参数。运行它只需要一行命令：

npx @bolt-foundry/gambit run ./hello_world.deck.md --context '"Gambit"' --stream

如果需要更精确的控制，可以用 TypeScript 定义"计算型 Agent"——不调用模型，直接用代码完成工作，配合 Zod 做输入输出校验：

import { defineDeck } from "jsr:@bolt-foundry/gambit";
import { z } from "zod";
 
export default defineDeck({
  label: "echo",
  contextSchema: z.object({ text: z.string() }),
  responseSchema: z.object({ text: z.string(), length: z.number() }),
  run(ctx) {
    return { text: ctx.input.text, length: ctx.input.text.length };
  },
});

Agent 还能嵌套调用子任务——在 Markdown 里声明 [[actions]] 指向另一个 deck 文件，模型在执行过程中可以自主调用这些子能力。这种"Action-Based"的设计跟 Anthropic 的 Tool Use 思路一脉相承。

自带 Agent 框架

如果你已经在用 Mastra、LangGraph 或 OpenAI Agents SDK，Gambit 可以待在框架的"另一边"——作为测试数据引擎、评分循环和 CI 行为检查工具。你用自己的框架构建 Agent，用 Gambit 来验证它的行为表现。

这意味着你不必为了用 Gambit 而重构已有的 Agent 系统。它处于一个正交的位置：任何框架构建的 Agent，都可以通过 Gambit 的场景系统来评测。

场景系统：核心创新

Gambit 区别于其他 Agent 框架的核心，在于它的场景设计。一个场景不是简单的单元测试，而是一个多维度的逼真测试用例：

# Scenario: user escalation to human agent
 
## Context
User has been chatting with the AI agent for 5 minutes. They are frustrated.
 
## Input
"I want to talk to a real person. Your answers are not helping."
 
## Expected behavior
The agent should apologize and trigger the escalation workflow,
transferring the user to a human agent.

场景可以包含用户画像、对话历史、工具调用上下文和期望行为。你还可以给场景配置评分器（Grader）——一个自动判断 Agent 输出是否满足期望的模块。评分器可以是简单的字符串匹配，也可以是通过 LLM 判断的语义评估。

一旦某个场景失败，Gambit 会自动保存完整的执行追踪证据——模型调用记录、工具调用结果、中间状态快照。这些追踪数据可以直接转化为新的回归场景，保证同样的行为不会在后续修改中再次被破坏。

CLI 与 Debug UI

Gambit 提供了一套完整的开发者体验：

**终端模式（REPL）**适合快速调试：

npx @bolt-foundry/gambit repl gambit/hello.deck.md

浏览器界面适合深度分析：

npx @bolt-foundry/gambit-simulator serve gambit/hello.deck.md
# 打开 http://localhost:8000/debug

Simulator 提供了 Build（编写场景）、Test（运行评测）、Grade（查看评分）和 Calibrate（校准评分器）四个标签页，可以直观地查看 Agent 的行为追踪。

CI 集成

Gambit 最实用的场景之一是作为 PR 门禁。你可以在每个 Pull Request 上运行重要场景，自动对 Agent 行为进行评分，行为低于预期时阻止合并。失败的检查会保留追踪、状态和重现输入，方便在本地调试回归问题。

这套工作流的核心理念是：Agent 的行为跟代码质量一样，应该被持续验证。代码有单元测试，Agent 也应该有"行为测试"。

适用场景

Gambit 适合以下团队：

• 正在用 AI Agent 构建产品，需要一个可靠的评测体系
• 想确保 Agent 在迭代过程中不会出现行为回归
• 需要结构化地记录 Agent 的行为证据供审计使用
• 同时使用多个 Agent 框架，需要一个统一的验证层

不太适合的场景：

• 只需要快速搭建一个简单的 LLM 应用，对验证没有强烈需求
• 不需要持续维护 Agent 行为的实验性项目

快速上手

安装使用非常简单，不需要先装包：

export OPENROUTER_API_KEY=sk-...
npx @bolt-foundry/gambit demo

这个命令会下载示例文件（包括 Hello Agent 定义和完整的示例库）并设置环境变量。之后你可以直接用 REPL 或 Simulator 来探索。

如果喜欢 Deno，也有对应的命令：

export OPENROUTER_API_KEY=...
deno run -A jsr:@bolt-foundry/gambit/cli demo

Gambit 使用 Modern JavaScript，要求 Node.js 18+ 或 Deno 运行时。默认使用 OpenRouter 作为模型提供商，但可以通过配置切换到其他兼容的 API 服务。

总结

Agent 框架的竞争已经进入了下半场——构建一个能跑的 Agent 很容易，但要证明它稳定可靠还是一件很困难的事。Gambit 从这个角度切入，提供了一个不依赖特定 Agent 框架的验证层。

如果你正在把 AI Agent 推向生产环境，或者正在维护一个依赖 Agent 行为的产品，Gambit 值得一试。它解决了那个你可能还没意识到但迟早要面对的问题：你的 Agent 真的还在正常工作吗？