Vai al contenuto principale

AX

Il Toolkit di Agent Experience

Tre strumenti open source che lavorano insieme per preparare il tuo sito web per gli agenti IA. ax-audit ti dice cosa manca. ax-init lo genera. ax-cite rende il tuo contenuto estraibile.

ax-audit

v3.0.0

Lighthouse per Agenti IA

npm versionlicensenode version

Verifica la preparazione di qualsiasi sito web per l'esperienza degli agenti IA (AX) in pochi secondi. ax-audit esegue 14 controlli ponderati — llms.txt, robots.txt, rendering HTML, dati strutturati, header HTTP, Agent Card, MCP, SEO base, security.txt, meta tag, OpenAPI, TLS / HTTPS, sitemap e file AI well-known emergenti — e produce un punteggio unico da 0 a 100 con risultati azionabili. Supporta confronto con baseline, audit batch e report HTML.

  • 14 controlli ponderati: llms.txt, robots.txt, rendering HTML, dati strutturati, header HTTP, Agent Card, MCP, SEO base, security.txt, meta tag, OpenAPI, TLS / HTTPS, sitemap e file AI well-known emergenti
  • Audit batch di più URL in un'unica esecuzione con riepilogo aggregato
  • Formati di output: terminale, JSON e report HTML autocontenuto
  • Pronto per CI/CD: applica soglie di punteggio AX a ogni deploy con GitHub Actions o GitLab CI
  • API programmatica: importa come libreria per integrazioni e workflow di automazione personalizzati
  • TypeScript, 2 dipendenze runtime, 198 test, Node.js 18+, Apache 2.0
Vedi su GitHub Vedi su npm Dataset su HF Demo Live
$ npx ax-audit https://your-site.com

ax-init

v1.4.0

Genera file AX per il tuo sito

npm versionlicense

CLI interattivo che genera i 10 tipi di file AX di cui il tuo sito ha bisogno — tramite un prompt interattivo o automatizzato dalla scansione di un URL. Supporta file di configurazione per pipeline CI/CD.

  • Genera 10 tipi di file AX: llms.txt, robots.txt, agent.json, mcp.json, security.txt, openapi.yaml, JSON-LD, meta tag e header HTTP
  • Modalità auto-detect: scansiona un URL, scopri file esistenti e pre-compila i prompt con i metadati rilevati
  • Supporto file config: salva le risposte in ax.json per esecuzioni non-interattive ripetibili in CI/CD
  • Modalità update: rigenera da config, confronta con file esistenti, scrivi solo ciò che è effettivamente cambiato
  • Anteprima dry-run: vedi esattamente cosa verrebbe generato senza scrivere alcun file
Vedi su GitHub Vedi su npm 
$ npx ax-init --from https://your-site.com

ax-cite

v1.0.0

Blocchi di citazione estraibili dall'IA

npm versionlicense

Web component ultra-leggero che renderizza blocchi di citazione semantici con attributi data-* che i crawler IA possono analizzare. Funziona con React, Vue, HTML e qualsiasi framework. ~2.8 KB gzipped.

  • 10 tipi di citazione: prodotto, articolo, servizio, evento, organizzazione, persona, luogo, recensione, FAQ e generico
  • Genera JSON-LD automaticamente con l'attributo jsonld — conforme a schema.org
  • Modalità nascosta: incorpora dati leggibili dalle macchine invisibili agli utenti, visibili ai crawler IA
  • API programmatica: toJSON(), extractAll() ed eventi ax-cite:render
  • Zero dipendenze, ~2.8 KB gzipped, Custom Element vanilla, TypeScript strict, ESM-only
Vedi su GitHub Vedi su npm 
<ax-cite type="product" name="Espresso Machine"
         price="USD 239" in-stock="true" jsonld
         summary="Available at USD 239. Ships free.">
</ax-cite>

Cosa controlla

LLMs.txt

11%

/llms.txt presence, llmstxt.org spec, and Content-Type

  • /llms.txt file exists and returns 200
  • Content-Type is text/plain or text/markdown
  • H1, blockquote, sections, and links per spec
  • /llms-full.txt extended version (bonus)

Robots.txt

11%

AI crawler configuration (47 known bots)

  • 8 core AI crawlers explicitly configured
  • 47 known AI crawlers can be allow-listed
  • Sitemap directive present
  • No wildcard Disallow blocking AI bots

HTML Rendering

9%

Server-rendered content for AI crawlers without JS

  • Visible text + word count thresholds
  • No empty SPA mount points (#root, #__next, …)
  • Semantic landmarks (main, article, header, …)
  • Single <h1>, alt coverage, noscript fallback

Structured Data

9%

JSON-LD on homepage (schema.org, @graph, entity types)

  • JSON-LD <script> in <head>
  • @context set to schema.org
  • @graph array with multiple entities
  • Person / Organization / WebSite / WebPage

HTTP Headers

9%

Security headers + AI discovery Link headers + CORS

  • HSTS, X-Content-Type-Options, CSP, Referrer-Policy
  • Link: </llms.txt>; rel="alternate"
  • CORS Access-Control-Allow-Origin on .well-known
  • X-Robots-Tag noindex on /llms.txt (bonus)

Agent Card

7%

A2A + same-origin url + skill quality

  • /.well-known/agent.json + Content-Type
  • Required fields (name, description, url, skills)
  • url is absolute and matches site origin
  • Every skill has id + description

MCP

7%

/.well-known/mcp.json Model Context Protocol server config

  • /.well-known/mcp.json + Content-Type
  • Valid JSON with server metadata
  • Tools array with descriptions
  • CORS + protocol version

SEO Basics

7%

title / description / canonical / lang / charset / hreflang

  • <title> length 20–70 chars
  • Meta description 70–160 chars
  • Single absolute <link rel="canonical">
  • <html lang>, charset, viewport, hreflang

Security.txt

6%

/.well-known/security.txt RFC 9116 compliance

  • /.well-known/security.txt exists
  • Contact field (required by RFC 9116)
  • Expires field with valid future date
  • Canonical, Preferred-Languages, Policy

Meta Tags

6%

AI meta tags + OpenGraph + Twitter Card completeness

  • ai:summary / ai:content_type / ai:author / …
  • rel="alternate" to llms.txt and agent.json
  • rel="me" identity links
  • Full OpenGraph (title/description/url/type/image)
  • Twitter Card (card/title/description/image)

OpenAPI

6%

/.well-known/openapi.json presence + schema + Content-Type

  • /.well-known/openapi.json + Content-Type
  • OpenAPI 3.x version field
  • info.title + info.description
  • Paths and servers documented

TLS / HTTPS

5%

HTTPS, HTTP→HTTPS redirect, HSTS preload eligibility

  • Site served over HTTPS
  • HTTP requests redirect to HTTPS
  • HSTS max-age ≥ 1 year
  • includeSubDomains + preload directive

Sitemap

4%

sitemap.xml validation, freshness, sitemap-index handling

  • Located via robots.txt or /sitemap.xml
  • Valid XML, correct Content-Type
  • <lastmod> coverage and freshness
  • Sitemap-index children reachable

AI Well-Known

3%

Emerging AI discovery files (5 probes)

  • /.well-known/ai.txt (Spawning)
  • /.well-known/genai.txt
  • /ai-plugin.json (legacy ChatGPT)
  • /agents.json (Wildcard / OpenAgents)
  • /.well-known/nlweb.json (Microsoft NLWeb)
NewEnglish only

Guide di Remediation

Istruzioni passo passo per correggere ogni risultato di ax-audit.

Vedi Guide di Remediation →

Avvio Rapido

$ npx ax-audit https://your-site.com

Esempio di Output

Output JSON

Usa il flag --json per ottenere un output leggibile dalla macchina per l'integrazione programmatica.

$ npx ax-audit https://lucioduran.com --json
{
  "url": "https://lucioduran.com",
  "overallScore": 88,
  "grade": { "label": "Good", "color": "yellow", "min": 70 },
  "timestamp": "2026-04-30T12:00:00.000Z",
  "duration": 807,
  "results": [
    {
      "id": "llms-txt",
      "name": "LLMs.txt",
      "score": 100,
      "findings": [
        { "status": "pass", "message": "/llms.txt exists" },
        { "status": "pass", "message": "Content-Type OK (text/plain)" },
        { "status": "pass", "message": "/llms-full.txt available" }
      ]
    },
    {
      "id": "robots-txt",
      "name": "Robots.txt",
      "score": 100,
      "findings": [
        { "status": "pass", "message": "8 core AI crawlers configured" },
        { "status": "pass", "message": "32/47 known crawlers have rules" }
      ]
    },
    {
      "id": "html-rendering",
      "name": "HTML Rendering",
      "score": 90,
      "findings": [
        { "status": "pass", "message": "Server-rendered content (473 words)" },
        { "status": "warn", "message": "Low text-to-markup ratio (2.4%)" }
      ]
    },
    {
      "id": "tls-https",
      "name": "TLS / HTTPS",
      "score": 100,
      "findings": [
        { "status": "pass", "message": "HSTS preload-eligible" }
      ]
    }
  ]
}

Riferimento CLI

Tutti i flag e le opzioni della riga di comando disponibili.

--jsonOutput results as JSON to stdout
--output <format>Output format: terminal, json, html
--checks <ids>Run only specified checks (comma-separated IDs)
--timeout <ms>HTTP request timeout in milliseconds (default: 10000)
--verboseShow detailed request and check execution logs
--only-failuresOnly show checks/findings with failures or warnings
--save-baseline <path>Save the current audit as a baseline JSON file
--baseline <path>Compare against a previous baseline (per-check deltas)
--fail-on-regression <n>Exit with code 1 if any check regresses by more than n points
--help, -hShow help information
--version, -vPrint version number and exit

Uso Programmatico

Importa ax-audit come libreria per integrazioni e flussi di automazione personalizzati.

TypeScript
import { audit, batchAudit } from 'ax-audit';

// Single URL
const result = await audit({
  url: 'https://your-site.com',
  checks: ['llms-txt', 'robots-txt', 'structured-data'],
  timeout: 15000,
});

console.log(result.overallScore);  // 98
console.log(result.grade.label);   // "Excellent"

for (const check of result.results) {
  console.log(`${check.name}: ${check.score}/100`);
}

// Batch audit
const batch = await batchAudit(
  ['https://site-a.com', 'https://site-b.com'],
  { timeout: 10000 }
);
console.log(batch.summary.averageScore);

Punteggio

Excellent90 – 100
Good70 – 89
Fair50 – 69
Poor0 – 49

Integrazione CI/CD

Aggiungi ax-audit alla tua pipeline per garantire standard di preparazione IA ad ogni deploy.

name: AX Audit
on: [push]

jobs:
  ax-audit:
    runs-on: ubuntu-latest
    steps:
      - name: Run AX Audit
        run: npx ax-audit ${{ secrets.SITE_URL }} --json > report.json

      - name: Check score threshold
        run: |
          SCORE=$(jq .overallScore report.json)
          echo "AX Score: $SCORE/100"
          [ "$SCORE" -ge 70 ] || exit 1

Cosa genera ax-init

llms.txtLLM-readable site description
llms-full.txtExtended inline sections
robots.txtAI crawler rules (47 bots)
agent.jsonA2A Agent Card
mcp.jsonMCP server config
security.txtRFC 9116 security contact
openapi.yamlAPI specification stub
sitemap.xmlXML sitemap with lastmod
JSON-LDStructured data for <head>
Meta TagsAI meta + OpenGraph + Twitter Card
HTTP HeadersNginx / Apache / Vercel config
HSTS preloadTLS / HTTPS hardening

Stack Tecnologico

TypeScript2 runtime depsNode.js 18+198 tests14 weighted checksESLint + PrettierApache 2.0