BridgeToAgent
Get the kit — $49
All posts
Audit13 min read

Lighthouse Agentic Browsing — every audit, every fix

A canonical per-audit reference for Chrome's Lighthouse Agentic Browsing category. Each of the nine audits, with what fails, why it fails, and the specific fix path — code snippet, file edit, or CMS toggle. Optimized for the dev or PM staring at a red audit report and needing a known-working remediation.

BridgeToAgentEditorial team

Lighthouse Agentic Browsing — every audit, every fix

Chrome's Lighthouse Agentic Browsing category scores nine audits. If you ran it and saw a row of red failures, you're in the audience this post is written for: the developer or PM with a failing audit report open in one tab and a fix to find in the next.

This is a lookup reference, not an essay. Each audit gets the same three-part treatment — what actually fails when Lighthouse marks the audit red, the underlying reason it fails (because the fix path follows the cause), and the concrete fix recipe. Where the fix is one line of code, the line is in here. Where it's a CMS toggle, the platform-specific toggle path is in here. Where it depends on what kind of site you run, the branching is in here.

A few notes before the audit list. Lighthouse Agentic Browsing is still marked experimental — audit names and weightings may shift through 2026. The category page at developer.chrome.com/docs/lighthouse/agentic-browsing/scoring is the authoritative spec; this post tracks its state as of mid-May 2026 and will be revised when the spec moves. The nine audits divide naturally into four file audits, one HTML audit, two discovery audits, one content-structure audit, and one emerging-spec audit. The triage map at the end shows which audits to fix in what order if you can't ship everything at once.

Quick jump to a failing audit

  1. llms-txt-present
  2. llms-txt-well-formed
  3. agents-json-present
  4. agents-json-actions-typed
  5. agent-runbook-present
  6. auto-discovery-links
  7. sitemap-discoverable
  8. schema-org-density
  9. webmcp-annotations

Audit 1 — llms-txt-present

What fails. Lighthouse marks the audit red when a GET to /llms.txt returns anything other than a 200 with a text/plain content type. Common failure modes: file doesn't exist (404), file exists at the wrong path (/llms or /.well-known/llms.txt), file returns as application/octet-stream because the server doesn't know what extension .txt means, or the file returns as HTML because your CMS routes unknown paths to a soft-404 page.

Why it fails. Most CMSs don't ship /llms.txt by default — it's a 2024-vintage spec (llmstxt.org) that predates platform support. The spec requires the file at the domain root with a text/plain MIME type. The content-type mismatch is the second most common failure after outright absence — file managers and FTP uploads sometimes infer the type from extension, and some platforms (Squarespace, Wix) don't honor the file-extension MIME hint at all.

The fix. Create a plain-text file at your domain root, populate it per the llmstxt.org spec — H1 with your site name, blockquote with a one-sentence description, then sections of canonical URLs with one-line summaries. The minimum viable file is about 20 lines. Upload to your domain root via your platform's standard file-upload path:

  • WordPress: WP File Manager plugin, drop llms.txt into the public root (same directory as wp-config.php). The WordPress install guide walks the upload step.
  • Shopify: Settings → Files → upload, then a 301 redirect from /llms.txt to the Files CDN URL (Shopify won't serve arbitrary files from the root). See the Shopify install guide for the redirect.
  • Webflow: Project Settings → Custom Code → upload as asset, then a redirect rule. The Webflow guide covers it.
  • Next.js: Drop llms.txt into /public/llms.txt. Next.js serves it as text/plain automatically.
  • Other platforms: The install matrix lists the upload pattern for all 13 supported CMSs.

After upload, verify with curl -I https://yourdomain.com/llms.txt — you want a 200 OK and Content-Type: text/plain. If the content type comes back wrong, see Audit 2's fix path for the MIME-override workaround.

The kit's /docs/llms-txt reference covers the file's structure if you're writing it by hand.

Audit 2 — llms-txt-well-formed

What fails. A stricter check than presence — Lighthouse runs the file through the llmstxt.org reference parser and marks it red if the parser rejects it. The common rejection causes: missing or malformed H1, broken Markdown link syntax ([text](url without the closing paren), section headers that don't follow the spec's ## Section Name pattern, mixed line endings (CRLF vs LF — the parser is strict about LF only), and link URLs that don't resolve when probed.

Why it fails. Hand-written files fail on small syntactic slips. Tool-generated files from free generators fail on link-rot — the URLs in the file pointed at real pages at generation time but 404 now because the generator never re-validates. Both failure classes look identical in the parser output: "parse failed at line N" with no further context.

The fix. Run your file through the reference parser — paste in the contents, fix anything flagged. Watch for the three most-missed validation rules: every section must start with ## , every link must be [text](https://full-url) (the parser rejects relative URLs), and the file must end with a final newline. If you used a free generator, also probe every URL in the file with curl -I to catch link-rot — generators don't re-validate.

If your CMS is serving the file as the wrong content type (Audit 1's failure mode), the fix differs by platform:

  • Apache / cPanel: add AddType text/plain .txt to the .htaccess in your domain root.
  • Nginx: in your server block, location = /llms.txt { default_type text/plain; }.
  • Cloudflare in front of any origin: a Page Rule or Worker to set the response Content-Type header to text/plain for /llms.txt.
  • Vercel / Netlify: serve the file from /public/llms.txt and the platform sets the content type correctly by default. If you're routing via a function, set the response header explicitly.

The kit's pipeline gates well-formedness at build time — a generated file that doesn't parse is blocked before delivery. If you're not using the kit, validate after every meaningful edit; the file is small enough that re-validation takes seconds.

Common-mistakes deep-dive on hand-written llms.txt files lives in llms-txt skepticism — what the critics get half-right. For the failure modes specifically produced by free generators (link rot, hallucinated URLs, placeholder summaries, malformed Markdown syntax), What free llms.txt generators don't tell you walks each one with a 30-second spot-check.

Audit 3 — agents-json-present

What fails. GET /agents.json returns anything other than 200 OK with valid JSON. Failure modes: file absent (most common), file present but malformed (trailing comma, unquoted keys, single quotes instead of double), file served with wrong content type (text/html instead of application/json), or file present but routes 404 because the CMS doesn't know to serve .json files from the root.

Why it fails. agents.json is newer than llms.txt — the spec lives at github.com/wild-card-ai/agents-json and no major CMS ships it by default. Hand-writing valid JSON for an action manifest is also harder than it looks: the spec requires a specific top-level shape (actions array, each action with name, description, url, method, parameters), and most hand-written drafts get one of the field names slightly wrong (endpoint instead of url, params instead of parameters).

The fix. Create a valid agents.json at your domain root. The minimum viable file lists 3–5 actions a user can perform on your site — search, browse products, contact, subscribe, view a policy. Each action needs the five fields above. Validate with jq . agents.json before upload (jq exits non-zero if the JSON is malformed).

Upload paths mirror Audit 1's — domain root via WP File Manager for WordPress, Files CDN + redirect for Shopify, asset + redirect for Webflow, /public/agents.json for Next.js. The install matrix covers all 13 platforms with the per-platform path.

After upload, verify with curl -sL https://yourdomain.com/agents.json | jq . — you want valid JSON output, not a JSON parse error. If the content type comes back as text/html, your CMS is routing the file through a soft-404 handler; check the same MIME-override paths from Audit 2.

The kit's /docs/agents-json reference shows the file's structure with examples.

Audit 4 — agents-json-actions-typed

What fails. Every action in agents.json must have a typed parameter schema. Lighthouse marks the audit red if any action has parameters: null, parameters: {} with no type declarations, parameters whose type field is missing, parameters with type: null, or parameters with a type value that isn't one of the spec's accepted types (string, number, boolean, array, object).

This is the hardest of the four file-correctness audits because passing it requires more than uploading a file — it requires modeling your site's actions correctly. Most hand-written agents.json files fail this audit even when they pass agents-json-present.

Why it fails. Typing actions is the load-bearing detail that lets an agent call them. An action that says "search this site" with parameters: null is unusable — the agent doesn't know whether to send a query string, what field name to use, what shape the response will be, or what types the response fields hold. So the spec requires explicit typing, and most hand-written drafts either skip typing entirely (because the writer doesn't know the spec requires it) or get the type names wrong (writing text instead of string, or omitting the type field on optional parameters thinking optionality implies type-free).

The fix. For every action in your file, the parameters block must be a proper JSON Schema object — each parameter as a key with a type declaration and any constraints. Search example:

{
  "name": "search",
  "description": "Search the site catalog by free-text query",
  "url": "https://yourdomain.com/search",
  "method": "GET",
  "parameters": {
    "type": "object",
    "properties": {
      "q": {
        "type": "string",
        "description": "Free-text search query"
      },
      "limit": {
        "type": "number",
        "description": "Max results to return"
      }
    },
    "required": ["q"]
  }
}

The pattern for every action: parameters is an object with type: "object", a properties map of field names to typed schemas, and a required array listing the mandatory fields. Optional fields go in properties but not in required.

Type-inference shortcuts when you're auditing an existing site:

  • <input type="email"> on a contact form → string with format: "email"
  • <input type="number"> → number
  • <input type="tel"> → string (not number — tel can have spaces, dashes, parens)
  • <select> with N options → string with enum: ["opt1", "opt2", ...]
  • <input type="checkbox"> → boolean
  • <input type="date"> → string with format: "date"

If you have an action with truly typeless parameters (rare — usually means the endpoint accepts arbitrary form data), the workaround is to declare it as type: "object" with additionalProperties: true rather than leaving the schema null. That passes the audit and signals the agent that the endpoint is permissive.

Deep dive on the four most-common typing mistakes is queued for a sidecar post — for now, the kit's agents-json reference has a worked example of each type. The kit's generation pipeline enforces typing at build time and refuses to emit a file with untyped parameters; if you're hand-writing, validate by spot-checking every action's parameters against the agents.json reference schema.

Audit 5 — agent-runbook-present

What fails. GET /agent-instructions.md returns anything other than 200 OK with a Markdown content type (text/markdown or text/plain both pass). Common failures: file doesn't exist (it's the newest of the three kit files and the least likely to be present by default), file at the wrong path (/agent-runbook.md or /.well-known/agent-instructions.md both fail — the spec is strict about the canonical path), file served as text/html by a CMS soft-404 handler.

Why it fails. Of the three kit files, agent-instructions.md is the most recently specified and the least likely to exist on a site that hasn't deliberately added it. The format is also less well-known than llms.txt or agents.json — writers sometimes default to a different filename out of habit, and agent-runbook.md is a tempting alternative that doesn't pass the audit because the spec names the file agent-instructions.md.

The fix. Create a Markdown file at your domain root named exactly agent-instructions.md. The spec defines three sections:

  1. Navigation guide — for which kinds of questions, which URLs to read. Example: "For pricing questions, read /pricing. For refund policy, read /policies/refund. For technical specs, read the product detail page."
  2. Behavioral rules — what the agent should and shouldn't do when handling user requests on your site. Examples: "Don't quote prices excluding VAT. Refund policy at /policies/refund is canonical — supersedes anything in product descriptions. Don't promise delivery dates outside business hours."
  3. Escalation path — how to reach a human when the agent gets stuck. Usually a contact form URL, a support email, or a phone number.

The minimum viable file is about 30 lines of Markdown. Upload to your domain root via the same paths as Audit 1. Verify with curl https://yourdomain.com/agent-instructions.md.

The kit's /docs/agent-instructions-md reference covers the three sections with examples drawn from real customer kits.

Audit 6 — auto-discovery-links

What fails. Lighthouse parses your homepage <head> and checks for three specific <link rel="alternate"> tags pointing at the three kit files. The audit marks red if any of the three is missing, if the type attribute doesn't match the file's actual content type, or if the href is a relative path that doesn't resolve from the homepage URL.

Why it fails. Most sites don't have these tags by default — they're a 2024–2025-vintage convention that grew up alongside the kit files themselves. Agents that don't probe /llms.txt paths blindly use the <head> for discovery hints, so the tags are the spec-aligned way to surface the kit files. Without them, an agent that visits the homepage has no signal that the kit files exist.

The fix. Add these three lines to your homepage <head>:

<link rel="alternate" type="application/json" title="Agent Action Map" href="/agents.json">
<link rel="alternate" type="text/plain" title="LLM Context" href="/llms.txt">
<link rel="alternate" type="text/markdown" title="Agent Runbook" href="/agent-instructions.md">

The href paths must be absolute paths starting with / so they resolve from the domain root regardless of which page the agent visits. The type attribute must match the file's served content type — if your llms.txt is being served as something other than text/plain, fix that first (see Audit 2's MIME-override paths) rather than adjusting the tag.

Platform-specific paste locations:

  • Shopify: layout/theme.liquid inside the <head> block. Save, no further build step.
  • WordPress: header.php (theme-specific path), or use the "Insert Headers and Footers" plugin to avoid editing theme files.
  • Webflow: Project Settings → Custom Code → Head Code.
  • Squarespace: Settings → Advanced → Code Injection → Header.
  • Wix: Settings → Advanced → Custom Code → Add Custom Code (Head, load on all pages).
  • Next.js (App Router): extend metadata.alternates.types in app/layout.tsx. Next.js emits the link tags from metadata automatically.
  • Static HTML: paste into <head> and redeploy.

After paste, view-source on your homepage and grep for rel="alternate" — you should see all three tags. Lighthouse can be picky about exact attribute spelling; copy the snippet above verbatim rather than rewriting from memory.

The kit ships this snippet in the ZIP with the platform-specific paste-location notes for every supported CMS.

Audit 7 — sitemap-discoverable

What fails. Two conditions both must hold. First: GET /sitemap.xml returns valid XML conforming to the sitemaps.org spec. Second: GET /robots.txt includes a Sitemap: directive pointing at the sitemap URL. The audit marks red if either condition fails — sitemap exists but robots.txt doesn't reference it (most common), or sitemap doesn't exist at all (rare on modern CMSs), or sitemap exists but is malformed (intermittent, usually a stale cache).

Why it fails. Most CMSs emit sitemap.xml by default (Shopify, WordPress with Yoast/RankMath, Webflow, Squarespace, Wix, Ghost, Next.js with next-sitemap). The robots.txt reference is the part that breaks — many CMSs ship a default robots.txt that doesn't include the Sitemap: directive, and adding it requires editing the robots.txt template (where the CMS has one) or overriding it entirely.

The fix. Locate where your CMS controls robots.txt:

  • WordPress: Yoast SEO → Tools → File editor → robots.txt, or RankMath → General Settings → Edit robots.txt. Add Sitemap: https://yourdomain.com/sitemap.xml as the last line.
  • Shopify: Shopify generates robots.txt automatically and includes the sitemap reference by default. If yours doesn't, edit templates/robots.txt.liquid in your theme to add the Sitemap: directive — Shopify allows custom overrides as of 2021.
  • Webflow: Project Settings → SEO → robots.txt. Webflow auto-includes the sitemap reference for paid plans; on free plans you may need to upgrade or add the reference manually.
  • Squarespace / Wix: Both auto-generate robots.txt with sitemap references on paid plans. On free plans, this audit may be unfixable without upgrading.
  • Next.js: app/robots.ts or app/robots.txt with a Sitemap field. If you're using next-sitemap, the package handles both automatically.
  • Custom server: edit the static robots.txt file, add Sitemap: https://yourdomain.com/sitemap.xml.

The sitemap URL must be the absolute URL including protocol and domain — Sitemap: /sitemap.xml is invalid per spec.

After edit, verify with curl https://yourdomain.com/robots.txt | grep Sitemap. You want a line that starts with Sitemap: and contains the full sitemap URL. Re-run Lighthouse; the audit should flip green within a recrawl cycle (Lighthouse runs at request time, not on a schedule, so the re-run is immediate).

The relationship between robots.txt and the kit files is covered in llms.txt vs robots.txt — the two have different jobs and need to coexist.

Audit 8 — schema-org-density

What fails. Lighthouse parses the JSON-LD blocks on your homepage and a sample of your inner pages, scores them on density (count of Schema.org types declared) and relevance (do the declared types match the page's actual purpose), and marks the audit red if either dimension comes in below threshold. Failure modes: no JSON-LD blocks at all (most common on small-business sites), JSON-LD blocks present but only declare WebSite (no per-page type), JSON-LD blocks present but the types mismatch the page purpose (an Organization block on a product page that's missing Product).

Why it fails. Schema density is theme-side, not file-side. The kit can't fix it by uploading three files to your root — Schema lives in the page templates that emit your HTML. The fix path always goes through your theme or a Schema plugin. The audit's threshold is also dependent on your business model: e-commerce stores need Product Schema on product pages; SaaS sites need SoftwareApplication; service businesses need LocalBusiness; blogs need Article; FAQ pages need FAQPage. There's no universal answer.

The fix. Find out what Schema your theme emits today by viewing source on each major page type and grepping for application/ld+json. You're looking for JSON-LD blocks per the Schema.org JSON-LD primer. Map what you find against what each page type should have:

  • Homepage: Organization block (legal name, URL, logo, sameAs links to your social profiles) + WebSite block (with SearchAction if your site has search) + BreadcrumbList if your nav has breadcrumbs.
  • Product pages (e-commerce): Product block per item with name, image, description, sku, brand, offers (price, currency, availability), aggregateRating if you have reviews.
  • Blog post pages: Article (or BlogPosting) block with headline, author, datePublished, dateModified, image, articleBody.
  • FAQ pages: FAQPage block with a mainEntity array of Question items.
  • Service-business pages: LocalBusiness block with NAP (name, address, phone), opening hours, geo coordinates.
  • About / contact pages: Organization reinforced with ContactPoint and PostalAddress.

Platform-specific fix paths:

  • Shopify: modern Dawn-derived themes ship Product, Organization, and WebSite Schema natively. Older themes may need a third-party app (JSON-LD for SEO, Schema Plus). The Shopify checklist covers Schema density per page type.
  • WordPress: Yoast SEO, RankMath, or SEOPress all emit baseline Schema. Yoast Premium and RankMath Pro add per-page-type Schema with the depth Lighthouse expects. Schema Pro and All-in-One Schema Rich Snippets are alternatives. The WordPress checklist walks the setup.
  • Webflow: Webflow's CMS Collections auto-emit Schema for common types. For non-Collection pages, paste JSON-LD into Page Settings → Custom Code → Head. The Webflow checklist covers density audits and CMS-Collection setup.
  • Squarespace 7.1: structured-data fields on commerce items emit Product Schema. Per-page type beyond products requires Code Injection — paid plans only. The Squarespace+Wix checklist walks the Code Injection paste path.
  • Wix: Velo (Wix's dev platform) can emit Schema via Page Code. Without Velo, you're limited to whatever the template ships, which on modern templates is Organization + Product + Article.
  • Custom Next.js / React: emit JSON-LD via a <Script type="application/ld+json"> block in your layout or page component. Use the Schema.org generators to validate the JSON-LD shape before deploy.

Validate the result with Google's Rich Results Test — paste in a page URL and the tool reports every Schema type detected and any errors. Re-run Lighthouse after fix.

This audit is the one most sites get wrong and the one that takes the most work to make right. The honest answer is that closing it well is a content-and-template project, not a $49 fix. The kit reports schema-org-density failures per-page and points at the platform-specific path — closing the audit itself sits in your CMS.

Audit 9 — webmcp-annotations

What fails. Lighthouse parses interactive elements on the page — <button>, <form>, <input>, <a> with action semantics — and checks for WebMCP per-element annotations declaring them as agent-callable actions. The audit marks red if interactive elements lack the annotations.

Why it fails. WebMCP went live in Chrome 146 (Feb 2026) and Edge 147 (Mar 2026) — combined browser coverage is around 76% of desktop users as of mid-May 2026. The annotation conventions are spec'd but not yet shipped by any major CMS, theme, framework, or component library. So virtually no site in 2026 passes this audit, and Lighthouse weights it accordingly low inside the category — the audit is informational more than load-bearing.

The fix. The honest fix for most sites in 2026 is "wait." Hand-annotating a theme today is work that doesn't compound — the conventions will shift before they stabilize, and re-annotating after a spec change is approximately as much work as annotating from scratch. The audit's low weight means it doesn't materially drag your overall Lighthouse Agentic Browsing score even when failing.

If you want to ship annotations anyway, the current spec defines data-mcp-action, data-mcp-description, and data-mcp-params attributes on the interactive element. Example for a search form:

<form
  data-mcp-action="search"
  data-mcp-description="Search the catalog by free-text query"
  action="/search"
  method="GET"
>
  <input
    name="q"
    type="text"
    data-mcp-param="q"
    data-mcp-type="string"
    data-mcp-description="Free-text query"
  >
  <button type="submit">Search</button>
</form>

The annotations layer alongside your existing form semantics — they don't replace <form> and <input> — and the agent can either call the action via the WebMCP protocol (if the browser exposes it) or fall back to filling the form via standard automation.

The WebMCP background and current state is covered in WebMCP in Chrome 146, with the May 2026 promotion to a formal W3C-track Origin Trial covered in WebMCP Origin Trial — what Chrome 149 changes from the Chrome 146 preview. For most sites the right answer is to monitor the spec, ship the first six audits this quarter, and revisit WebMCP when annotation conventions stabilize.

The triage map

If you can't ship every audit this week, here's the order of return-on-effort:

  1. Audits 1, 3, 5 (-present checks) — three file uploads, ~10 minutes of work total, immediate pass on three audits.
  2. Audit 2 (well-formed) — paste your llms.txt into the reference parser, fix flagged issues. ~15 minutes.
  3. Audit 4 (actions-typed) — adds typing to every action in agents.json. ~30–60 minutes for a 5–10-action manifest, longer if you hand-write from scratch.
  4. Audit 6 (auto-discovery-links) — three lines in <head>. ~5 minutes.
  5. Audit 7 (sitemap-discoverable) — one line in robots.txt. ~5 minutes.
  6. Audit 8 (schema-org-density) — theme work or Schema plugin install, plus content audit. Hours to days depending on depth. The audit that takes the longest to close well.
  7. Audit 9 (webmcp-annotations) — wait for the spec to settle. Re-evaluate in Q4 2026.

Six of nine in roughly an afternoon if the kit files are hand-written. The kit generates the first six in two minutes from a real crawl of your site, validates them at build time, and ships with platform-specific install instructions — that's the speed-up, not a different scope.

For the audit-by-audit map of what the kit closes versus what's CMS-side and theme-side, see How the BridgeToAgent kit maps to every Lighthouse Agentic Browsing audit.

Related

Keep reading

All posts →