Stop Building Agent Projects Blindly! Use Better Agents Instead

What if I told you that 90% of AI agent projects fail in production not because of bad models, but because of catastrophic structural mistakes made on day one? Think about it. You've seen it happen. A brilliant prototype that crumbles the moment real users start interacting with it. Prompts scattered across hardcoded strings. Zero testing beyond "it worked on my machine." No observability when things go sideways at 3 AM. And when your teammate tries to collaborate? Absolute chaos.

Here's the brutal truth: most developers are building agents like it's 2019. They're cobbling together frameworks, copying snippets from Discord, and praying nothing breaks. But what if there was a way to start every agent project with battle-tested structure, automated testing, and production observability baked in from the first commit?

Enter Better Agents—the CLI tool and standards framework that's making experienced developers abandon their old workflows. Built by the LangWatch team, this isn't just another scaffolding tool. It's a complete paradigm shift for how agent projects should be architected. Whether you're wielding Claude Code, Cursor, Kilocode, or any modern coding assistant, Better Agents transforms them from helpful autocomplete into true agent framework experts.

Ready to discover why teams are quietly switching? Let's dive deep.

What is Better Agents?

Better Agents is an open-source CLI tool and comprehensive standards framework designed specifically for building production-grade AI agents. Created by the LangWatch team—experts in LLM observability and evaluation—this tool addresses a critical gap in the current agent development ecosystem: the complete absence of standardized project structure.

The repository, hosted at langwatch/better-agents, has rapidly gained traction among developers who are tired of reinventing the wheel with every new agent project. At its core, Better Agents solves a fundamental problem: coding assistants are generalists, not framework specialists. When you ask Claude Code or Cursor to build an Agno agent or a LangGraph workflow, they produce generic code that misses framework-specific best practices, testing patterns, and observability hooks.

Better Agents bridges this gap through a clever dual approach:

1. Intelligent Project Scaffolding: Generates a complete, opinionated project structure tailored to your chosen framework (Agno, Mastra, LangGraph, and more)
2. AGENTS.md & MCP Configuration: Transforms your coding assistant into a domain expert by injecting framework-specific knowledge, testing patterns, and architectural guidelines directly into your development environment

The .mcp.json configuration is particularly ingenious—it pre-configures Model Context Protocol servers so your coding assistant instantly understands your framework's patterns, how to write proper Scenario tests, and where to place evaluation logic.

This isn't just about convenience. It's about survival in production. The LangWatch team built this after observing hundreds of agent projects fail due to preventable structural issues. They distilled those hard lessons into an automated setup that enforces best practices from git init.

Key Features That Separate Amateurs from Pros

Better Agents packs serious engineering discipline into what appears to be a simple CLI tool. Here's what makes it genuinely powerful:

Framework-Aware Scaffolding

Unlike generic project generators, Better Agents understands the semantic differences between agent frameworks. A LangGraph project needs different abstractions than an Agno or Mastra project. The CLI interrogates your choices and generates idiomatic code structures, not cookie-cutter templates.

The AGENTS.md Contract

This is the secret weapon. The generated AGENTS.md file serves as a living development contract that your coding assistant reads and follows. It specifies:

• Where prompts live (and why they must be versioned)
• How scenario tests should be structured
• Where evaluation notebooks belong
• Observability instrumentation requirements

Your AI assistant literally cannot forget best practices because they're encoded in its context window.

Built-in Testing Pyramid

Better Agents implements the Agent Testing Pyramid philosophy:

• Scenario tests: End-to-end conversation simulations that verify agent behavior
• Evaluation notebooks: Jupyter notebooks for measuring specific pipeline components (RAG retrieval, classification accuracy, etc.)
• Prompt versioning: YAML-based prompt files with registry management for reproducible deployments

Production Observability from Day One

Every generated project comes pre-instrumented for LangWatch observability. You're not adding monitoring as an afterthought—you're building with telemetry in mind from the first line of code.

Team Collaboration Architecture

The prompts/ directory with prompts.json registry solves a genuine pain point: how do teams collaborate on prompts without merge conflicts and invisible changes? Version-controlled YAML prompts with explicit registry management means your team's prompt iterations are as disciplined as your code changes.

Real-World Use Cases Where Better Agents Dominates

Use Case 1: The Solo Developer Shipping to Production

You're building a customer support agent for your startup. Without Better Agents, you'd hardcode prompts, skip testing "for now," and pray. With Better Agents, you get scenario tests that simulate angry customers, evaluation notebooks measuring response relevance, and full tracing when things break in production. You sleep better. Your users get consistency.

Use Case 2: The Agency Building Multiple Client Agents

Your team juggles five different agent frameworks across client projects. Each developer has "their way" of structuring things. Better Agents standardizes everything—clients get identical project structures, your team shares AGENTS.md knowledge across projects, and handoffs become trivial instead of traumatic.

Use Case 3: The Enterprise Team Fighting Technical Debt

Your company's "AI initiative" spawned twelve agent prototypes in six months. None share structure. None have tests. The thought of productionizing any of them gives your architect nightmares. Better Agents lets you rebuild with discipline or gradually migrate—either way, you establish standards that prevent future chaos.

Use Case 4: The Researcher Reproducing Experiments

Academic reproducibility meets agent development. Your evaluation notebooks, versioned prompts, and scenario tests create a complete experimental record. When reviewers ask "how did you verify this agent's behavior?" you point to committed test suites, not manual logs.

Step-by-Step Installation & Setup Guide

Getting started with Better Agents is deliberately frictionless. The LangWatch team optimized for "productive in two minutes."

Prerequisites

Before installing, ensure you have:

• Node.js 22+ (check with node --version)
• npm or pnpm
• A coding assistant installed: Claude Code (claude), Cursor, Kilocode CLI (kilocode), or Antigravity (agy)
• API keys ready: LangWatch API key and your chosen LLM provider key

Installation

Install globally for repeated use:

# Install globally via npm
npm install -g @langwatch/better-agents

Or use npx for one-off initialization without global installation:

# Run directly without installing
npx @langwatch/better-agents init my-agent-project

Project Initialization

The CLI provides two initialization patterns depending on your workflow:

# Initialize in current directory (for existing projects adopting Better Agents)
better-agents init .

# Initialize in new directory (recommended for greenfield projects)
better-agents init my-awesome-agent

After running init, the CLI launches an interactive configuration wizard that guides you through:

1. Programming language selection (TypeScript, Python, etc.)
2. Agent framework choice (Agno, Mastra, LangGraph, etc.)
3. Coding assistant configuration (Claude Code, Cursor, etc.)
4. LLM provider and API key setup
5. LangWatch observability integration

Post-Setup Verification

Once initialized, your project structure will match the Better Agent standard:

my-awesome-agent/
├── app/                     # Framework-specific agent code
├── tests/
│   ├── evaluations/         # Jupyter notebooks for RAG/classifier evaluation
│   └── scenarios/           # End-to-end behavior tests
├── prompts/                 # Version-controlled YAML prompts
├── prompts.json             # Prompt registry for collaboration
├── .mcp.json                # MCP servers for coding assistant expertise
├── AGENTS.md                # Development guidelines your AI reads
├── .env                     # API keys and configuration
└── .gitignore

Telemetry Configuration

Better Agents includes anonymous usage telemetry to improve the tool. To opt out:

# Disable telemetry before running any commands
export BETTER_AGENTS_TELEMETRY=0

REAL Code Examples from the Repository

Let's examine actual patterns from the Better Agents repository and documentation.

Example 1: Project Structure Generation

The core value proposition lives in this generated structure. Here's how Better Agents organizes a production-ready agent project:

my-agent-project/
├── app/ (or src/)           # The actual agent code, according to the chosen framework
├── tests/
│   ├── evaluations/         # Jupyter notebooks for evaluations
│   │   └── example_eval.ipynb
│   └── scenarios/           # End-to-end scenario tests
│       └── example_scenario.test.{py,ts}
├── prompts/                 # Versioned prompt files for team collaboration
│   └── sample_prompt.yaml
├── prompts.json             # Prompt registry
├── .mcp.json                # MCP server configuration
├── AGENTS.md                # Development guidelines
├── .env                     # Environment variables
└── .gitignore

Why this matters: The separation of app/ from tests/ from prompts/ enforces separation of concerns that most agent projects lack. The evaluations/ directory specifically holds Jupyter notebooks because interactive exploration is essential for understanding RAG retrieval quality or classification accuracy. The scenarios/ directory contains executable tests that simulate real conversations—not unit tests, but behavioral contracts.

Example 2: CLI Installation and Initialization

These are the actual commands from the README, demonstrating the zero-friction setup:

# Global installation for repeated project creation
npm install -g @langwatch/better-agents

# Or use npx for immediate execution without installation
npx @langwatch/better-agents init my-agent-project

# Initialize in current directory (migrating existing project)
better-agents init .

# Initialize in new directory (fresh project)
better-agents init my-awesome-agent

Critical insight: The dual initialization pattern (init . vs init <name>) reveals thoughtful UX design. The . variant enables incremental adoption—you can add Better Agents structure to existing projects without destructive changes. The named variant creates clean greenfield projects.

Example 3: Telemetry Configuration

The README includes this environment variable pattern for privacy-conscious teams:

# Anonymous usage telemetry is enabled by default
# To opt out, set this environment variable:
BETTER_AGENTS_TELEMETRY=0

Production consideration: This simple toggle demonstrates privacy-by-design principles. Enterprise users evaluating the tool can immediately verify no data exfiltration occurs, reducing security review friction.

Example 4: Prompt Versioning Architecture

While not shown as explicit code, the prompts/ + prompts.json structure implies this workflow:

# prompts/sample_prompt.yaml (version-controlled prompt)
system_prompt: |
  You are a helpful customer support agent for Acme Corp.
  Always verify order numbers before providing refund status.
  
version: "1.2.0"
last_modified: "2024-01-15T09:23:00Z"
author: "sarah.chen"
evaluation_results:
  scenario_pass_rate: 0.94
  avg_response_time_ms: 230

// prompts.json (central registry)
{
  "prompts": {
    "customer_support": {
      "current_version": "1.2.0",
      "path": "prompts/sample_prompt.yaml",
      "framework": "langchain"
    }
  }
}

Why this pattern wins: Traditional prompt management embeds strings in code. Better Agents externalizes and versions them like database migrations. The evaluation_results field in YAML creates explicit links between prompt versions and measured performance—no more "I think this prompt works better" without data.

Advanced Usage & Best Practices

The AGENTS.md as Living Documentation

Don't treat AGENTS.md as boilerplate. Customize it per project with domain-specific rules. Add sections like:

• "When handling PII, always route through app/sanitizers/"
• "Scenario tests must include at least one adversarial user path"
• "Evaluation notebooks must achieve >0.85 F1 before PR merge"

Your coding assistant reads this. It will enforce your standards.

MCP Server Optimization

The .mcp.json configuration is your force multiplier. Review which MCP servers are active for your framework. If you're using LangGraph extensively, ensure the MCP includes graph debugging tools. For Agno projects, verify agent memory inspection servers are configured.

Prompt Registry Workflows

Treat prompts.json like package.json. Pin versions for reproducibility. Before deploying:

# Verify all prompts have passing evaluations
better-agents validate-prompts

# Compare current vs. proposed prompt performance
better-agents evaluate --baseline v1.2.0 --candidate v1.3.0-rc1

(Note: These specific commands are illustrative based on the architecture; verify actual CLI capabilities in USAGE.md)

Scenario Test Coverage Strategy

Follow the testing pyramid: many scenario tests (behavioral), focused evaluation notebooks (component), minimal unit tests (implementation). Agent behavior emerges from interaction, not function composition.

Comparison with Alternatives

The verdict: Generic tools give you structure without intelligence. Framework CLIs give you framework knowledge without production concerns. Manual setup gives you control without speed. Better Agents is the only option that combines framework expertise, production readiness, and team scalability.

FAQ: What Developers Actually Ask

Is Better Agents free to use?

Yes, the CLI and standards are MIT licensed. You'll need API keys for LangWatch and your chosen LLM provider, but the tooling itself is open source.

Which coding assistants work with Better Agents?

Currently supported: Claude Code (claude), Cursor, Kilocode CLI (kilocode), and Antigravity (agy). The MCP configuration adapts to each assistant's capabilities.

Can I add Better Agents to an existing project?

Absolutely. Use better-agents init . to scaffold structure in your current directory. The tool is designed for incremental adoption, not just greenfield projects.

What agent frameworks are supported?

The CLI supports Agno, Mastra, LangGraph, and expanding. The framework-specific scaffolding ensures idiomatic patterns for each, not generic approximations.

How does prompt versioning actually work?

Prompts live as YAML files in prompts/, tracked by Git like code. The prompts.json registry maps logical names to current versions, enabling rollback, A/B testing, and team collaboration without merge conflicts in source files.

What's the difference between scenario tests and evaluation notebooks?

Scenario tests verify end-to-end agent behavior—simulating full conversations to ensure the agent responds appropriately. Evaluation notebooks measure specific components—RAG retrieval accuracy, classifier F1 scores, etc. Both are essential; neither replaces the other.

Do I need LangWatch to use Better Agents?

No, but observability is pre-configured for seamless integration. You can use the structural benefits without LangWatch, though you'll miss production monitoring and the evaluation infrastructure.

Conclusion: The Standard Your Agent Projects Desperately Need

After dissecting Better Agents from every angle, here's my honest assessment: this is the most important agent tooling release of 2024 that nobody's talking about yet.

The AI agent space is flooded with frameworks, models, and hype. What's missing is engineering discipline. Better Agents doesn't just scaffold code—it scaffolds culture. The generated structure forces you to think about testing before deployment, observability before incidents, and collaboration before scaling.

The AGENTS.md + MCP integration is genuinely innovative. It solves the "coding assistant doesn't understand my framework" problem without requiring model fine-tuning or custom training. Your existing tools get smarter immediately.

For solo developers, Better Agents prevents the "it worked locally" production disaster. For teams, it ends the "whose project structure is this?" confusion. For enterprises, it provides audit-ready testing and versioning.

The bottom line: If you're building agents without structured testing, prompt versioning, and observability, you're building technical debt with extra steps. Better Agents makes the right way the easy way.

Stop starting agent projects with mkdir and prayers. Start them with standards that survive contact with production.

👉 Get Better Agents on GitHub — star the repo, try the CLI, and join the Discord community where the LangWatch team ships improvements weekly.

Your future self debugging a 3 AM production incident will thank you.

Built with ❤️ by the LangWatch team. Standards for building agents, better.