langwatch/better-agents · 上手攻略

仓库：langwatch/better-agents
链接：https://github.com/langwatch/better-agents
分类：AI 智能体开发框架 · 测试与评估
作者：Tom
更新：2026-07-29

是什么

Better Agents 是由 LangWatch 团队开源的 CLI 工具 + 一套工程规范，旨在让 AI 编码助手（Claude Code、Cursor、Kilocode 等）成为真正的"Agent 专家"，能按照行业最佳实践构建、测试和评估 AI Agent 项目。

它不替换已有的 Agent 框架（Agno、Mastra、LangGraph 等），而是在这些框架之上叠加了一层结构：标准化目录、Scenario 测试、提示词版本化管理、可观测性接入。相当于给 Agent 项目立了"工程宪法"。

解决什么问题

大多数 Agent 项目死于"能跑但不可靠"：没有测试、没有评测、提示词随意改、部署后行为失控。Better Agents 通过以下机制解决：

目录结构标准化：任何框架都遵循同一套目录约定，降低协作成本
Scenario 测试（基于 Scenario）：用自然语言写端到端对话测试，模拟真实用户行为
提示词版本化管理：所有 prompt 存入 prompts/ 目录，配合 prompts.json 做版本注册表
可观测性接入：自动接入 LangWatch 进行追踪和评测
MCP 工具自动发现：.mcp.json 让编码助手自动了解项目用到的所有 MCP 服务

快速安装

# 全局安装（推荐）
npm install -g @langwatch/better-agents

# 或直接用 npx（无需安装）
npx @langwatch/better-agents init my-agent-project

环境要求： - Node.js 22+ - npm 或 pnpm - 至少一个编码助手：Claude Code、Cursor、Antigravity (agy)、Kilocode CLI - LangWatch API Key（免费注册：https://app.langwatch.ai/authorize） - 所选 LLM Provider 的 API Key（如 OpenAI/Anthropic）

关闭遥测（可选）：

BETTER_AGENTS_TELEMETRY=0

核心用法

初始化新项目

# 在当前目录初始化
better-agents init .

# 在新目录初始化
better-agents init my-awesome-agent

CLI 会交互式引导你选择：编程语言 → Agent 框架 → 编码助手 → LLM 提供商 → API Keys。

初始化后得到标准目录结构：

my-agent-project/
├── app/                    # Agent 代码（按选定框架的组织方式）
├── tests/
│   ├── evaluations/        # Jupyter 评测笔记本
│   └── scenarios/          # 端到端 Scenario 测试
│       └── example_scenario.test.{py,ts}
├── prompts/                # 版本化提示词（YAML）
│   └── sample_prompt.yaml
├── prompts.json            # 提示词注册表
├── .mcp.json               # MCP 服务器配置
├── AGENTS.md               # 开发规范（自动生成）
├── .env
└── .gitignore

编写 Scenario 测试

# tests/scenarios/refund_scenario.test.py
import scenario

class RefundScenario(scenario.Scenario):
    name = "refund request"
    description = "Customer requests refund for defective product"

    agents = [
        CustomerSupportAgent(),
        scenario.UserSimulatorAgent(),
        scenario.JudgeAgent(criteria=[
            "Agent should acknowledge the issue",
            "Agent should check order status",
            "Agent should process refund if eligible",
        ]),
    ]

运行测试：

scenario test
# 或通过 LangWatch Scenario CLI

提示词管理

# 新增一条提示词
better-agents prompt add "refund-greeting" --file prompts/refund_greeting.yaml

# 查看所有提示词版本
better-agents prompt list

典型适用场景

从零构建 Agent 项目：不想每次从零搭架子，一行命令生成标准结构
多框架统一管理：团队用 Agno、Mastra、LangGraph 混用，需要统一测试和评测方式
Agent 行为可靠性验证：用 Scenario 做端到端测试，避免"好像能用但实际会崩"的情况
提示词工程协作：多人协作时用 prompts.json 做版本控制，避免 prompt 随意修改引发回归
Agent 可观测性：接入 LangWatch 追踪每次运行的输入输出、耗时、成本

坑与注意

需要 Node.js 22+：旧版 Node 可能遇到兼容性问题，建议用 nvm 或 fnm 管理版本
LangWatch API Key 必需：Better Agents 本身免费，但可观测性功能需要 LangWatch Key；若不接入，核心功能（测试、结构）仍可用
Scenario 测试需要真实 API：测试 Agent 时会真实调用 LLM，有成本；建议在 .env 中配置测试用低额 Key
不支持纯后端无界面 Agent：Better Agents 强调"编码助手协同"，对纯 API 型后端 Agent 覆盖相对薄弱
框架覆盖范围：当前文档明确支持 Agno、Mastra、LangGraph、Vercel AI、Google ADK，其他框架需自行适配目录结构
遥测默认开启：安装后默认上报匿名使用数据，介意的话设 BETTER_AGENTS_TELEMETRY=0

与同类对比

工具	定位	测试能力	框架依赖	上手难度
Better Agents	Agent 工程规范 + CLI	Scenario 端到端测试	框架无关	低（交互式引导）
LangGraph	Agent 框架本身	无内置测试工具	强依赖 LangGraph	中
Agno	Agent 框架	内置追踪，非专项测试	强依赖 Agno	中
CrewAI	多 Agent 协作框架	无	强依赖 CrewAI	低
manual + pytest	自搭规范	自行实现	任意	高

Better Agents 的核心差异化在于"框架无关"——无论你用 Agno 还是 Mastra，规范和测试都能复用。

一句话推荐结论

如果你想认真做 Agent 项目（而非只是 demo 跑通），Better Agents 是目前最轻量、最实用的"工程化起点"，特别适合团队协作和长期维护。