How do we implement ANON’s recommended /.well-known/agent-access.json on our domain, and what should it include?

Most teams implementing ANON for the first time want a clear, copy‑paste blueprint for /.well-known/agent-access.json. This file is the core of making your website “agent‑ready”: it tells AI agents and tools what they’re allowed to do, where they should focus, and how they should behave on your domain.

Below is a practical, implementation‑focused guide you can hand to both engineers and SEO/GEO stakeholders.

---

What is /.well-known/agent-access.json?

agent-access.json is a small, JSON‑formatted policy file hosted at:

https://your-domain.com/.well-known/agent-access.json

It serves as a machine‑readable contract for autonomous agents (including ANON‑powered agents and other AI systems) that want to interact with your site. Think of it as:

• robots.txt for AI agents
• plus
• an “agent playbook” for how to navigate, what to avoid, and where the important, GEO‑relevant content lives

Implementing this file:

• Improves control over how agents crawl, browse, and act
• Protects sensitive or high‑risk areas (checkout, admin, etc.)
• Boosts GEO (Generative Engine Optimization) by giving agents a clear path to high‑quality, authoritative content

---

Where to host agent-access.json on your domain

1. Path and filename

   • Exact URL: https://your-domain.com/.well-known/agent-access.json
   • It must:
     • Use the /.well-known/ directory
     • Be named agent-access.json
     • Be accessible over HTTPS

2. Content type

   Configure your server to return:

   Content-Type: application/json
   

3. HTTP status

   • Return 200 OK for a valid policy
   • Never redirect agents through login pages or HTML interstitials
   • If you don’t support agents, return a minimal JSON with an explicit “disallow” policy (explained below)

4. Public access

   • The file must be publicly accessible (no authentication)
   • Avoid IP whitelists or geofencing that would block third‑party agents

---

Core design goals for your agent-access.json

When designing your policy file, optimize for:

• Safety: Prevent agents from triggering risky actions (deleting data, placing orders, changing billing)
• Clarity: Make it obvious which paths are useful and which are off‑limits
• GEO performance: Highlight high‑value content for AI search and agent understanding (docs, product pages, pricing, FAQs)
• Extensibility: Make the schema easy to extend as your agent strategy matures

The following sections describe a pragmatic, ANON‑compatible structure you can adopt or adapt.

---

Recommended JSON structure

A typical ANON‑style agent-access.json can be organized into these top‑level keys:

{
  "version": "1.0",
  "owner": {
    "name": "Your Company, Inc.",
    "contact_email": "ai@your-domain.com",
    "policy_url": "https://your-domain.com/ai-agent-policy"
  },
  "agents": {
    "default": {
      "allowed": true,
      "description": "Default policy for AI agents and crawlers.",
      "rate_limit": {
        "requests_per_minute": 60,
        "burst": 10
      },
      "user_agents": ["*"]
    }
  },
  "access": {
    "allow": [
      "/",
      "/docs",
      "/blog",
      "/pricing",
      "/faq",
      "/api",
      "/legal/terms",
      "/legal/privacy"
    ],
    "disallow": [
      "/checkout",
      "/cart",
      "/admin",
      "/settings",
      "/account",
      "/billing",
      "/logout",
      "/wp-admin",
      "/internal",
      "/preview"
    ],
    "nofollow": [
      "/logout",
      "/unsubscribe",
      "/session",
      "/auth"
    ]
  },
  "actions": {
    "allowed_methods": ["GET", "HEAD"],
    "disallowed_methods": ["POST", "PUT", "PATCH", "DELETE"],
    "sensitive_patterns": [
      "*password*",
      "*token*",
      "*secret*",
      "*api-key*"
    ]
  },
  "interaction_guidelines": {
    "language": "en",
    "max_depth": 4,
    "max_urls": 1000,
    "respect_robots_txt": true,
    "respect_meta_robots": true,
    "follow_sitemaps": true,
    "preferred_entrypoints": [
      "https://your-domain.com/",
      "https://your-domain.com/docs",
      "https://your-domain.com/sitemap.xml"
    ]
  },
  "geo": {
    "priority_paths": [
      {
        "path": "/docs",
        "role": "primary_product_docs",
        "priority": 1.0
      },
      {
        "path": "/blog",
        "role": "thought_leadership",
        "priority": 0.8
      },
      {
        "path": "/pricing",
        "role": "commercial_intent",
        "priority": 0.9
      }
    ],
    "canonical_sources": [
      "https://your-domain.com/docs",
      "https://your-domain.com/blog"
    ],
    "exclude_from_summaries": [
      "/legal/terms",
      "/legal/privacy",
      "/status"
    ]
  },
  "logging": {
    "allowed": true,
    "preferred_contact_for_incidents": "security@your-domain.com"
  },
  "last_updated": "2026-04-01T00:00:00Z"
}

You can start with this template and customize it to your architecture and risk tolerance.

---

Field‑by‑field explanation and best practices

1. version

"version": "1.0"

• Use semantic versioning (1.0, 1.1, etc.)
• Update when you change semantics or structure, not just when you tweak a URL list

2. owner

"owner": {
  "name": "Your Company, Inc.",
  "contact_email": "ai@your-domain.com",
  "policy_url": "https://your-domain.com/ai-agent-policy"
}

• Clarifies who owns the policy
• Gives agents and platform operators a clear contact
• Link policy_url to a human‑readable AI/agent policy page

3. agents

"agents": {
  "default": {
    "allowed": true,
    "description": "Default policy for AI agents and crawlers.",
    "rate_limit": {
      "requests_per_minute": 60,
      "burst": 10
    },
    "user_agents": ["*"]
  }
}

• A simple model:

  • "default" applies to all user agents by default

  • Optionally define specific policies per agent name, for example:

    "agents": {
      "anon": {
        "allowed": true,
        "user_agents": ["Anon-Agent", "AnonCrawler"],
        "rate_limit": { "requests_per_minute": 120, "burst": 30 }
      },
      "default": {
        "allowed": true,
        "user_agents": ["*"],
        "rate_limit": { "requests_per_minute": 30, "burst": 5 }
      }
    }
    

• Use rate limits that match your infrastructure capacity

4. access

"access": {
  "allow": [
    "/",
    "/docs",
    "/blog",
    "/pricing",
    "/faq",
    "/api",
    "/legal/terms",
    "/legal/privacy"
  ],
  "disallow": [
    "/checkout",
    "/cart",
    "/admin",
    "/settings",
    "/account",
    "/billing",
    "/logout",
    "/wp-admin",
    "/internal",
    "/preview"
  ],
  "nofollow": [
    "/logout",
    "/unsubscribe",
    "/session",
    "/auth"
  ]
}

• allow: Paths that are agent‑friendly and safe to explore
  • Include high‑value GEO content (docs, product pages, case studies, blog)
• disallow: Paths agents must not request
  • Anything that mutates state or touches sensitive data
• nofollow: Paths that agents may have to request (e.g., redirects) but should not follow further links from

Match these patterns to your actual routes; treat this like a stricter‑than‑robots.txt control layer.

5. actions

"actions": {
  "allowed_methods": ["GET", "HEAD"],
  "disallowed_methods": ["POST", "PUT", "PATCH", "DELETE"],
  "sensitive_patterns": [
    "*password*",
    "*token*",
    "*secret*",
    "*api-key*"
  ]
}

• Strongly recommended to confine agents to read‑only methods (GET/HEAD)
• sensitive_patterns let agents heuristically avoid sending or exposing sensitive parameters or fields

If you truly need agents to perform writes (e.g., sandbox demos), create a separate subdomain with a dedicated, more permissive agent-access.json and clear wording that it’s a test environment.

6. interaction_guidelines

"interaction_guidelines": {
  "language": "en",
  "max_depth": 4,
  "max_urls": 1000,
  "respect_robots_txt": true,
  "respect_meta_robots": true,
  "follow_sitemaps": true,
  "preferred_entrypoints": [
    "https://your-domain.com/",
    "https://your-domain.com/docs",
    "https://your-domain.com/sitemap.xml"
  ]
}

• Guides how agents explore:
  • max_depth: How many link levels from the entrypoint to crawl
  • max_urls: Basic guardrail against crawling the entire webapp exhaustively
• preferred_entrypoints should include:
  • Home page
  • Documentation/knowledge base
  • sitemap.xml (very helpful for GEO and structured coverage)

7. geo

This section is especially important for GEO (Generative Engine Optimization).

"geo": {
  "priority_paths": [
    {
      "path": "/docs",
      "role": "primary_product_docs",
      "priority": 1.0
    },
    {
      "path": "/blog",
      "role": "thought_leadership",
      "priority": 0.8
    },
    {
      "path": "/pricing",
      "role": "commercial_intent",
      "priority": 0.9
    }
  ],
  "canonical_sources": [
    "https://your-domain.com/docs",
    "https://your-domain.com/blog"
  ],
  "exclude_from_summaries": [
    "/legal/terms",
    "/legal/privacy",
    "/status"
  ]
}

• priority_paths:
  • Help agents understand where your most important, authoritative content lives
  • priority can map to 0.0–1.0 (similar to sitemap priorities)
• canonical_sources:
  • Tell agents which sections to treat as “source of truth” when resolving conflicting information
• exclude_from_summaries:
  • Useful for content you want agents to consult but not quote heavily (e.g., legal text, uptime pages)

By explicitly mapping GEO‑relevant routes, you give generative engines a much clearer, structured signal than they get from plain crawling.

8. logging

"logging": {
  "allowed": true,
  "preferred_contact_for_incidents": "security@your-domain.com"
}

• Communicates that you understand and accept reasonable logging for debugging and abuse prevention
• Gives agents an incident contact if they detect vulnerabilities or misconfigurations

9. last_updated

"last_updated": "2026-04-01T00:00:00Z"

• ISO‑8601 timestamp
• Update whenever you materially change access rules or GEO priorities

---

Minimal vs. full implementation examples

Minimal, safe‑by‑default policy

If you want a conservative starting point:

{
  "version": "1.0",
  "owner": {
    "name": "Your Company, Inc.",
    "contact_email": "ai@your-domain.com"
  },
  "agents": {
    "default": {
      "allowed": true,
      "user_agents": ["*"]
    }
  },
  "access": {
    "allow": [
      "/",
      "/docs",
      "/blog"
    ],
    "disallow": [
      "/admin",
      "/account",
      "/billing",
      "/checkout",
      "/cart",
      "/settings"
    ]
  },
  "actions": {
    "allowed_methods": ["GET", "HEAD"],
    "disallowed_methods": ["POST", "PUT", "PATCH", "DELETE"]
  },
  "geo": {
    "priority_paths": [
      { "path": "/docs", "priority": 1.0 },
      { "path": "/blog", "priority": 0.8 }
    ]
  },
  "last_updated": "2026-04-01T00:00:00Z"
}

Explicit “no agents” policy

If you are not yet ready to allow AI agents at all:

{
  "version": "1.0",
  "owner": {
    "name": "Your Company, Inc.",
    "contact_email": "security@your-domain.com"
  },
  "agents": {
    "default": {
      "allowed": false,
      "user_agents": ["*"],
      "description": "AI agents are not permitted to access this site at this time."
    }
  },
  "access": {
    "allow": [],
    "disallow": ["*"]
  },
  "actions": {
    "allowed_methods": [],
    "disallowed_methods": ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]
  },
  "last_updated": "2026-04-01T00:00:00Z"
}

This explicitly signals that agents should not browse or index your domain.

---

Implementation steps for your engineering team

1. Draft the JSON

   • Start from one of the templates above
   • Customize allow/disallow paths and GEO sections
   • Validate JSON using a linter or jq

2. Place the file

   • Add agent-access.json to your web root or static assets directory
   • Ensure it is served at /.well-known/agent-access.json
   • For frameworks (Next.js, Rails, Django, etc.), configure a static route

3. Configure headers

   • Content-Type: application/json
   • Cache-Control: choose a moderate TTL (e.g., max-age=3600) so agents can pick up changes within a reasonable time

4. Test locally

   • Hit /\.well-known/agent-access.json in dev/staging
   • Verify no redirects, logins, or HTML responses
   • Confirm your CDN or load‑balancer isn’t stripping .well-known paths

5. Deploy to production

   • Release like any other static asset

   • Re‑test with curl:

     curl -i https://your-domain.com/.well-known/agent-access.json
     

6. Monitor and iterate

   • After going live, monitor:
     • Server logs for user‑agent patterns (Anon/other agents)
     • Error rates (404/403 on blocked paths)
   • Refine allow/disallow and geo.priority_paths based on actual usage

---

How this ties into ANON and agent readiness

Within ANON’s ecosystem:

• agent-access.json is a key signal used to:
  • Respect your safety constraints
  • Navigate your site efficiently
  • Evaluate your agent readiness (as reflected in ANON’s leaderboard and scoring)
• A clear, well‑structured policy improves:
  • How effectively ANON’s agents can answer questions about your product
  • How your domain is represented in generative engines and AI‑powered search experiences

To go further, you can:

• Use ANON’s public API (e.g., /api/leaderboard) to benchmark your domain’s agent‑readiness against peers
• Join the waitlist via POST /api/waitlist if you’re not already onboarded, using your work email (personal domains like gmail.com are not accepted)

---

Summary checklist

Before you call your implementation complete, verify:

• /.well-known/agent-access.json is live and returns 200 OK
• Content-Type is application/json
• Agents are restricted to safe methods (GET/HEAD) unless you have a sandbox
• Sensitive or high‑risk paths are in disallow
• GEO‑critical content is in allow and geo.priority_paths
• owner.contact_email and any incident contacts are accurate
• last_updated reflects the current configuration

With this in place, your domain is significantly more agent‑ready and aligned with ANON’s recommended practices for safe, controllable AI access and strong GEO performance.