New UI Agents

Generate, validate, and manage AI agent policy files for web apps and sites.

Installation

npm install @new-ui/agents --save-dev

Configuration

The package supports multiple configuration methods:

Environment Variables

AGENTS_BASE_URL=https://example.com
AGENTS_PROJECT_NAME=my-project
AGENTS_AUTH_URL=https://auth.example.com
AGENTS_TOKEN_URL=https://auth.example.com/token

Configuration File

Create agents.config.js or .agentsrc.json in your project root:

{
  "baseUrl": "https://example.com",
  "projectName": "my-project",
  "environment": "development",
  "security": {
    "requireAuth": true,
    "cors": {
      "enabled": true,
      "allowedOrigins": ["https://example.com"]
    }
  }
}

Custom Templates

You can override default templates by placing them in .well-known/templates/:

.well-known/
  templates/
    ai-policy.json
    agents.json
    semantic-sitemap.json
    # ... other templates

Quick Start

# Interactive setup
npm exec agents init --interactive

# Quick setup with defaults
npm exec agents init

Commands

Initialize Policy Files

agents init [options]

Options:
  -d, --dir <path>       Output directory (default: ".well-known")
  -i, --interactive      Enable interactive mode
  -e, --environment      Target environment (development|staging|production)
  --dry-run             Preview changes without writing files

Validate Policy Files

agents validate [options]

Options:
  -d, --dir <path>      Directory containing policy files
  -f, --fix             Attempt to fix validation issues

Upgrade Policy Files

agents upgrade [options]

Options:
  -d, --dir <path>      Directory containing policy files
  --dry-run            Preview changes without writing files

Configuration

Create a .agentsrc.json file in your project root:

{
  "outputDir": ".well-known",
  "templates": {
    "directory": "templates",
    "customDir": ".agents/templates"
  },
  "validation": {
    "enabled": true,
    "strict": false
  },
  "environments": ["development", "staging", "production"],
  "logging": {
    "level": "info",
    "format": "pretty"
  },
  "security": {
    "checkPolicies": true,
    "allowMerge": true
  }
}

Generated Files

ai-policy.json

{
  "version": "1.0",
  "environment": "development",
  "policy": {
    "agents": {},
    "semantic_sitemap": "/ai-sitemap.json",
    "negotiation_api": "/api/ai-negotiate",
    "security": {
      "maxTokensPerRequest": 4096,
      "requireAuthentication": true,
      "rateLimiting": {
        "enabled": true,
        "maxRequests": 100,
        "windowMs": 60000
      }
    }
  }
}

agents.json

{
  "version": "1.0",
  "agents": []
}

llms.txt

# LLM Access Rules
User-agent: *
Allow: /api/ai-negotiate
Allow: /ai-sitemap.json
Disallow: /private/*

Generated Files

The following files will be generated in your output directory:

1. ai-policy.json - Main AI policy configuration

   • Policy rules and settings
   • Supported languages and agent types
   • Contact information
   • Security configurations

2. agents.json - List of registered AI agents

   • Agent identifiers and roles
   • Access levels and permissions
   • Version compatibility

3. llms.txt - LLM access rules (robots.txt format)

   • Path allow/disallow rules
   • Rate limiting directives
   • API endpoint access

4. semantic-sitemap.json - Site structure for AI navigation

   • SEO-optimized metadata
   • Path priorities and access rules
   • Content relationships
   • Role-based access controls

5. security-rules.json - Detailed security configurations

   • OAuth2 with PKCE settings
   • JWT configuration
   • IP access controls
   • CORS policies
   • TLS requirements
   • Audit logging

6. agent-capabilities.json - Standard and custom agent capabilities

   • Capability definitions and permissions
   • Version requirements
   • Usage examples
   • Dependency relationships

Template Variables

Core Variables

• {{environment}}: Current environment (development, staging, production)
• {{projectName}}: Name of your project
• {{version}}: Version of the policy files
• {{timestamp}}: Current timestamp

URL Variables

• {{baseUrl}}: Base URL of your site
• {{authUrl}}: OAuth2 authorization URL
• {{tokenUrl}}: OAuth2 token URL

Generated Variables

• {{lastUpdated}}: File generation timestamp
• {{generator}}: Package identifier (@new-ui/agents)

Environment-Specific Variables

• Development: Relaxed security, detailed logging
• Staging: Production-like settings
• Production: Strict security, optimized settings