@new-ui/agents NPM

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:

ai-policy.json - Main AI policy configuration
- Policy rules and settings
- Supported languages and agent types
- Contact information
- Security configurations
agents.json - List of registered AI agents
- Agent identifiers and roles
- Access levels and permissions
- Version compatibility
llms.txt - LLM access rules (robots.txt format)
- Path allow/disallow rules
- Rate limiting directives
- API endpoint access
semantic-sitemap.json - Site structure for AI navigation
- SEO-optimized metadata
- Path priorities and access rules
- Content relationships
- Role-based access controls
security-rules.json - Detailed security configurations
- OAuth2 with PKCE settings
- JWT configuration
- IP access controls
- CORS policies
- TLS requirements
- Audit logging
agent-capabilities.json - Standard and custom agent capabilities
- Capability definitions and permissions
- Version requirements
- Usage examples
- Dependency relationships