What is AgentGuard?

AgentGuard is the structural backbone of AI-generated artifacts. It works as an MCP server alongside any AI agent — Claude, Cursor, Windsurf, or any MCP-compatible tool — providing the scaffolding, validation, and self-challenge layer that turns a raw prompt into a production-ready result. When you ask an AI agent to build something, AgentGuard makes sure it builds it right.

Instead of asking an AI agent to produce an artifact in one shot, AgentGuard breaks it into structured steps: skeleton (structure) → contracts (interfaces & schemas) → wiring (dependencies) → logic (implementation) → validation (automated checks). This pipeline applies to software, research papers, strategic plans, technical documentation, and any other artifact an AI agent can generate.

Archetypes are the core concept. They are battle-tested blueprints that encode quality standards for a specific artifact type — think of them as “quality recipes” that define:

• Expected project structure (files, folders, purposes)
• Tech stack requirements (language, framework, database, testing)
• Validation rules (5 automated checks with auto-fix)
• Quality criteria (adversarial self-challenge for reliability)

Why It Matters

How It Works (Buyers)

Your journey from discovery to shipping code, in five steps:

What You Get

Why Sell on AgentGuard?

You are an expert in a specific domain: healthcare APIs, e-commerce frontends, data pipelines, whatever. That expertise has real value.

AgentGuard lets you package your best practices as a sellable archetype. Once published, developers discover it, use it, and you earn recurring revenue — passive income from your engineering standards.

How It Works (Authors)

Turn your knowledge into a published archetype in five steps:

What Makes a Great Archetype

Domain expertise matters. A great archetype:

• Solves a real problem. Healthcare APIs need different checks than e-commerce frontends. Your specialty is the advantage.
• Has concrete quality criteria. Not "code is clean," but "all endpoints have authentication," "error responses follow RFC 7807," "database uses migrations."
• Includes reference patterns. Show developers how to write code that passes your criteria.
• Is versioned and maintained. Quality standards evolve. Update your archetype as tech stacks change.

Author Inspiration

Installation

Install AgentGuard as a pip package:

pip install rlabs-agentguard

Then configure it as an MCP server in your AI agent. Add to your claude_desktop_config.json (Claude Desktop) or MCP settings (Cursor, Windsurf):

{
  "mcpServers": {
    "agentguard": {
      "command": "agentguard-mcp",
      "args": [],
      "env": {
        "AGENTGUARD_API_KEY": "your-key-here"
      }
    }
  }
}

Quick Start

Once AgentGuard is configured as an MCP server, your AI agent (Claude, Cursor, etc.) can call these tools directly:

# Step 1: Get skeleton prompt
> @agentguard skeleton --archetype api_backend --spec "A user auth API"

# Step 2: Generate contracts and wiring
> @agentguard contracts_and_wiring --archetype api_backend --skeleton <output>

# Step 3: Implement logic
> @agentguard logic --archetype api_backend --contracts <output>

# Step 4: Validate code
> @agentguard validate --files <your_code>

# Step 5: Get quality criteria
> @agentguard get_challenge_criteria --archetype api_backend

AgentGuard provides structured prompts and validation — your AI agent generates the actual code using its own AI model.

Pipeline

AgentGuard provides structured MCP tools that guide an AI agent through a 4-level top-down code generation flow: skeleton → contracts → wiring → logic → validation.

# Tool 1: Generate file structure prompt
skeleton = await client.call_tool("skeleton", {
    "archetype": "api_backend",
    "spec": "A user authentication API with JWT"
})

# Tool 2: Generate contracts + wiring
contracts_wiring = await client.call_tool("contracts_and_wiring", {
    "archetype": "api_backend",
    "skeleton": skeleton
})

# Tool 3: Generate implementation logic
logic = await client.call_tool("logic", {
    "archetype": "api_backend",
    "contracts": contracts_wiring
})

# Tool 4: Validate the generated code
validation = await client.call_tool("validate", {
    "archetype": "api_backend",
    "files": generated_files
})

Pipeline Flow

When an AI agent uses AgentGuard tools, the following happens:

1. L1 — Skeleton: Get a structured prompt for file structure planning (which files to create, their purpose)
2. L2 — Contracts: Get a prompt to generate function signatures, types, and interfaces for each file
3. L3 — Wiring: Get a prompt to add import statements and inter-file references so modules connect correctly
4. L4 — Logic: Get a prompt to implement function bodies with actual business logic
5. Validation Gate: Run the validate tool to check 5 categories (syntax, lint, imports, structure, types). Auto-fixes and reports issues.
6. Challenge Gate: Call the get_challenge_criteria tool to get quality criteria for the archetype and manually review the code against them.

Archetypes

An archetype defines a project type — its tech stack, expected file structure, validation rules, and quality criteria. Archetypes are the key to generating code that matches real-world best practices.

Built-in Archetypes

from agentguard import Archetype

# Load a built-in archetype
arch = Archetype.load("api_backend")

# Inspect it
print(arch.name)            # "api_backend"
print(arch.tech_stack)      # TechStack(language="python", framework="fastapi", ...)
print(arch.pipeline)        # PipelineConfig(max_files=25, parallel=True, ...)
print(arch.self_challenge)  # SelfChallengeConfig(criteria=[...], max_rework=3)

# Load from a custom YAML file
custom = Archetype.from_file("my_archetype.yaml")

Custom Archetypes

Create your own archetype as a YAML file:

name: django_api
version: "1.0.0"
description: "Django REST Framework API"

tech_stack:
  language: python
  framework: django
  runtime: python3.12
  package_manager: pip
  test_framework: pytest

pipeline:
  max_files: 20
  parallel: true

validation:
  checks:
    - syntax
    - lint
    - imports
    - structure

self_challenge:
  max_rework: 3
  criteria:
    - "All endpoints have proper authentication"
    - "Database models use migrations"
    - "Error responses follow RFC 7807"

Top-Down Generation

The core of AgentGuard is a 4-level top-down code generation strategy. Instead of asking an AI agent to generate an entire project in one shot, AgentGuard breaks it into structured, composable levels with focused prompts:

Validation

After code generation, AgentGuard runs 5 automated checks in fast-to-slow order. If the first check (syntax) fails, the pipeline stops early — no point running expensive type-checking on invalid code.

# Call the validate tool
result = await client.call_tool("validate", {
    "archetype": "api_backend",
    "files": {
        "main.py": "def greet(name: str) -> str:\n    return f'Hello {name}'"
    }
})

# Result includes:
# - passed: true/false
# - checks: List of individual check results
# - issues: Any syntax, lint, import, or type errors
# - fixed: Auto-fixed files (if fixable)

Self-Challenge

Self-challenge is an optional quality review step. Each archetype defines its own challenge criteria — these are quality requirements the AI agent can use to evaluate generated code. For example, api_backend has 15 criteria including authentication, error handling, and input validation checks.

# Get challenge criteria for an archetype
criteria = await client.call_tool("get_challenge_criteria", {
    "archetype": "api_backend"
})

# Criteria are a checklist the AI agent can use to review code:
# - All endpoints require authentication
# - Error responses follow RFC 7807
# - Database models use migrations
# - No hardcoded secrets or credentials
# ... and 11 more

# The AI agent uses these to manually review the generated code

Tracing & Usage

When using AgentGuard MCP tools, your AI agent handles all model calls — AgentGuard provides the structured prompts and validation logic. Token consumption depends entirely on your agent's model. You can track tool call durations and usage through the AgentGuard dashboard analytics.

CLI Reference

The CLI provides utility functions for archetype management and local validation:

# List available archetypes
agentguard list

# Show archetype details
agentguard info api_backend

# Validate existing files
agentguard validate ./my-project --archetype api_backend

# Validate an archetype YAML file
agentguard validate-archetype my_archetype.yaml

# Start the MCP server (for Claude Desktop, Cursor, etc.)
agentguard mcp-serve

# Reload archetype definitions
agentguard reload-archetypes

Archetype Author Guide

This section is a complete reference for writing, customizing, and publishing archetype YAML files. Archetypes are the primary extension point of AgentGuard — they encode the tech stack, expected structure, validation rules, quality criteria, and configuration for a specific class of software project.

Identity Fields

tech_stack

Declares the canonical tech stack. All values are validated against known identifiers and included in every structured prompt sent to AI agents.

tech_stack:
  defaults:
    language: "python"       # python | typescript | javascript | go | rust | ...
    framework: "fastapi"     # fastapi | django | express | react | click | none | ...
    database: "postgresql"   # postgresql | mysql | sqlite | mongodb | none | ...
    testing: "pytest"        # pytest | jest | vitest | go_test | ...
    linter: "ruff"           # ruff | eslint | golangci-lint | none | ...
    type_checker: "mypy"     # mypy | pyright | tsc | none
  overridable: true          # allow users to override when using the archetype

pipeline

context_recipes

Controls what context is included in the structured prompt at each generation level and the recommended token budget per call.

context_recipes:
  skeleton:
    include: ["spec", "archetype_structure"]
    max_tokens: 3000
  contracts:
    include: ["spec", "skeleton", "reference_patterns"]
    max_tokens: 6000
  wiring:
    include: ["contracts", "skeleton"]
    max_tokens: 8000
  logic:
    include: ["function_stub", "function_tests", "function_deps", "reference_patterns"]
    max_tokens: 5000

validation

type_strictness controls mypy mode: off, basic, or strict (--strict flag).

Writing self_challenge Criteria

Each criterion is a checklist item that an AI agent can use to review generated code. Concrete, verifiable statements produce reliable results.

Schema Validation Rules

• id must match ^[a-z][a-z0-9_]{1,62}[a-z0-9]$
• version must be valid semver
• No path traversal (..) or absolute paths in structure
• Self-challenge criteria: 1–500 chars each, max 50 per archetype

MCP Tools

AgentGuard is primarily used as an MCP server. It exposes 17 MCP (Model Context Protocol) tools that AI agents can call directly. This is how Claude Desktop, Cursor, Windsurf, and other MCP-compatible agents integrate AgentGuard.

MCP Setup

# Install AgentGuard
pip install rlabs-agentguard

# Run the MCP server
agentguard-mcp

Add to your Claude Desktop or Cursor MCP config:

{
  "mcpServers": {
    "agentguard": {
      "command": "agentguard-mcp",
      "args": []
    }
  }
}

Available MCP Tools

The 17 tools are organized into categories:

Agent Frameworks

AgentGuard works with any MCP-compatible agent framework:

• Claude Desktop — Native MCP support. Add agentguard-mcp to your MCP config.
• Cursor — MCP support. Configure in Cursor settings.
• Windsurf — MCP support. Use MCP tools in your workflows.
• Custom Agent Frameworks — Any framework that supports MCP can integrate AgentGuard tools.

Platform Architecture

The AgentGuard Platform is a cloud service that extends the open-source library with team features, analytics, and the archetype marketplace.

Platform Features

• Dashboard — View usage analytics, token consumption, cost breakdowns by model and archetype
• Team Management — Invite team members, set roles, share archetype libraries
• Archetype Publishing — Submit your custom archetypes to the marketplace for others to use
• Usage Reports — Detailed reports on generation quality, validation pass rates, and model comparison

Marketplace

The Archetype Marketplace is where the community shares and discovers project archetypes. Think of it like an app store — but for code generation templates.

For Users (Browsing & Installing)

1. Register for free on the platform (no credit card required)
2. Browse archetypes by category (backend, frontend, fullstack, CLI, library, data, devops)
3. Filter by price (many are free), rating, and download count
4. Purchase or install free archetypes with one click (one-time purchase, not a subscription)
5. Use them immediately with the library or CLI: agentguard generate --archetype marketplace/fastapi-celery-redis
6. Rate and review archetypes to help the community

For Authors (Publishing)

1. Create your archetype as a YAML file (see Custom Archetypes)
2. Submit it through the dashboard — our team reviews it to ensure quality and safety
3. Set your price (or make it free). Taxes and processing fees are deducted first, then a 20% platform commission is applied.
4. Track downloads, revenue, and ratings on your author dashboard

Quality Assurance

Every archetype published to the marketplace goes through a review process:

• Automated validation — YAML schema checks, attribute completeness, criteria coherence
• Human review — Our team checks for accuracy, safety, and alignment with stated purpose
• Community feedback — Ratings and reviews surface the best archetypes naturally

Customer Journey

AgentGuard is designed to meet developers where they are and grow with them. Here is the intended progression:

pip install rlabs-agentguard
# Configure agentguard-mcp in your AI agent's MCP settings
# Free. Forever. No account needed.

agentguard mcp-serve
# Claude Desktop or Cursor can now use agentguard tools

Pricing Model

AgentGuard is free to use. The library, CLI, and MCP tools are free and open-source forever. Registration and platform access are free. The marketplace enables authors to sell archetypes at prices they set.

Key principle: AgentGuard is the structural layer — your AI agent (Claude, Cursor, Windsurf, or any MCP-compatible tool) provides the generation power. AgentGuard makes sure what gets generated meets the quality bar you defined.