更好的代理

Better Agents 是一款命令行工具，同时也是一套用于构建代理的标准。

它能大幅提升你的编码助手（如 Kilocode、Claude Code、Cursor 等）的能力，使其成为你所选任何代理框架（如 Agno、Mastra、LangGraph 等）及其最佳实践方面的专家。

这是启动任何新代理项目的最佳方式。

Better Agent 结构和生成的 AGENTS.md 文件确保了行业最佳实践，使你的代理可以直接投入生产：

• 为每个功能编写 Scenario 代理测试，以确保代理行为正确
• 对提示进行版本控制，便于团队协作
• 提供评估笔记本，用于衡量特定提示的表现
• 已经集成完整的可观测性工具
• 标准化项目结构，提高项目的可维护性

Better Agent 结构

my-agent-project/
├── app/ (或 src/)           # 实际的代理代码，根据所选框架而定
├── tests/
│   ├── evaluations/         # 用于评估的 Jupyter 笔记本
│   │   └── example_eval.ipynb
│   └── scenarios/           # 端到端场景测试
│       └── example_scenario.test.{py,ts}
├── prompts/                 # 用于团队协作的版本化提示文件
│   └── sample_prompt.yaml
├── prompts.json             # 提示注册表
├── .mcp.json                # MCP 服务器配置
├── AGENTS.md                # 开发指南
├── .env                     # 环境变量
└── .gitignore

该结构以及 AGENTS.md 中的指导原则，确保编码助手所需的每一项新功能都经过适当的测试和评估，并且提示被正确地版本化。

.mcp.json 配置文件中预设了所有必要的 MCP，使你的编码助手能够精通你选择的框架，并掌握为你的代理编写 Scenario 测试的方法。

scenarios/ 测试保证代理的行为符合预期，通过模拟与代理的对话来验证其是否按预期工作。

evaluations/ 笔记本包含数据集和用于评估代理流水线中各个部分的笔记本，例如 RAG 或分类任务等。

最后，prompts/ 目录以 YAML 格式存储所有版本化的提示，并通过 prompts.json 进行同步和管理，以便于实验和团队协作。

快速开始

安装

npm install -g @langwatch/better-agents

或者使用 npx：

npx @langwatch/better-agents init my-agent-project

初始化一个新项目

# 在当前目录下
better-agents init .

# 在新目录下
better-agents init my-awesome-agent

CLI 将引导你选择编程语言、代理框架、编码助手、LLM 提供商以及 API 密钥。

文档

• 快速入门 - 快速入门指南（2 分钟）
• 教程 - 详细分步指南
• 项目结构 - 理解 Better Agent 的结构
• 功能 - 关键功能和能力
• 使用方法 - CLI 的使用方法及示例
• 理念 - 代理测试金字塔方法
• 贡献 - 如何为 Better Agents 做贡献
• 变更日志 - 版本历史

系统要求

• Node.js 22+
• npm 或 pnpm
• 以下任一编码助手：
  • Claude Code (claude CLI)
  • Cursor
  • Antigravity (agy)
  • Kilocode CLI (kilocode)
• API 密钥：
  • LangWatch API 密钥（可在 https://app.langwatch.ai/authorize 获取）
  • 你所选择的 LLM 提供商的 API 密钥
• 遥测（可选）：
  • 默认启用匿名使用遥测。
  • 若要退出，请设置环境变量：

    BETTER_AGENTS_TELEMETRY=0
    

资源

• LangWatch
• Scenario 文档
• 代理测试金字塔
• Agno
• Mastra
• Discord

许可证

MIT

---

由 LangWatch 团队用心打造

Better Agents 快速上手指南

Better Agents 是一款命令行工具（CLI）和一套智能体（Agent）开发标准。它能将你的编程助手（如 Cursor、Claude Code、Kilocode 等）转化为特定框架（如 Agno、Mastra、LangGraph）的专家，确保项目从第一天起就遵循行业最佳实践，具备完整的测试、评估和可观测性。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• Node.js: 版本 22 或更高 (node -v 检查)
• 包管理器: npm 或 pnpm
• 编程助手 (任选其一):
  • Cursor
  • Claude Code (需安装 claude CLI)
  • Kilocode CLI (kilocode)
  • Antigravity (agy)
• API Keys:
  • LangWatch API Key: 用于可观测性和提示词管理，可在 LangWatch Console 获取。
  • LLM Provider API Key: 你所选大模型提供商的密钥。

提示: 默认开启匿名使用遥测。如需关闭，请设置环境变量 BETTER_AGENTS_TELEMETRY=0。

安装步骤

你可以通过全局安装或直接使用 npx 运行。

方式一：全局安装（推荐）

npm install -g @langwatch/better-agents

方式二：临时运行 (无需安装)

npx @langwatch/better-agents init my-agent-project

基本使用

初始化一个新项目是使用 Better Agents 的核心步骤。CLI 会引导你配置语言、框架、编程助手及 API 密钥。

1. 初始化项目

在当前目录初始化：

better-agents init .

在新目录初始化：

better-agents init my-awesome-agent

执行后，按照终端提示依次选择：

1. 编程语言 (TypeScript/Python 等)
2. Agent 框架 (Agno, Mastra, LangGraph 等)
3. 使用的编程助手 (Cursor, Claude Code 等)
4. LLM 提供商
5. 输入对应的 API Keys

2. 项目结构概览

初始化完成后，你将获得一个符合生产标准的项目结构：

my-agent-project/
├── app/                 # 核心 Agent 代码
├── tests/
│   ├── evaluations/     # Jupyter notebooks (用于评估 RAG 或分类任务)
│   └── scenarios/       # 端到端场景测试 (模拟对话行为)
├── prompts/             # 版本化的提示词文件 (.yaml)
├── prompts.json         # 提示词注册表
├── .mcp.json            # MCP 服务器配置 (让编程助手成为框架专家)
├── AGENTS.md            # 开发指南与规范
├── .env                 # 环境变量
└── .gitignore

3. 开始开发

现在你可以直接使用配置的编程助手（如 Cursor 或 Claude Code）打开该项目。由于 .mcp.json 已预配置好上下文，你的编程助手将自动理解所选框架的最佳实践，并能协助你编写符合 scenarios/ 标准的测试用例和管理 prompts/ 中的提示词。