Skip to main content

ByLast reviewed

Agent Attributes

The data-agent-* namespace for helping AI agents understand your pages

While semantic HTML, ARIA, and structured data provide the foundation for BiModal Design, the data-agent-* attribute namespace lets you be explicit about page context, components, content fields, and available actions — giving agents a reliable, consistent signal layer on top of the underlying semantics.

Think of these attributes as a machine-readable manifest. They tell agents what framework is in use, what each section of the page is for, and what actions are available — without requiring any JavaScript execution.

The data-agent-* Namespace

Page-Level Attributes

  • data-agent-framework
  • data-agent-version
  • data-agent-context
  • data-agent-mode

Page Content Attributes

  • data-agent-page
  • data-agent-intent
  • data-agent-content-type

Component Attributes

  • data-agent-component

Content & Action Attributes

  • data-agent-content
  • data-agent-action
  • data-agent-mitigation

Core Attribute Patterns

Page-Level Attributes

Added to the <html> or <body> element to provide global context about the page and framework environment.

Attributes:

data-agent-framework — the rendering framework (e.g., "nextjs", "astro", "nuxt")
data-agent-version — framework or BiModal spec version
data-agent-context — page context (e.g., "product", "article", "home")
data-agent-mode — rendering mode (e.g., "ssr", "ssg", "csr")
<html
  lang="en"
  data-agent-framework="nextjs"
  data-agent-version="1.0"
  data-agent-context="product"
  data-agent-mode="ssr"
>
  <!-- page content -->
</html>

Page Content Attributes

Applied to the <main> or top-level content container to describe what the page is about and what the user is trying to accomplish.

Attributes:

data-agent-page — machine-readable page identifier (e.g., "product-detail", "checkout")
data-agent-intent — user goal for this page (e.g., "purchase", "browse", "contact")
data-agent-content-type — type of primary content (e.g., "product", "article", "listing")
<main
  data-agent-page="product-detail"
  data-agent-intent="purchase"
  data-agent-content-type="product"
>
  <!-- product content -->
</main>

data-agent-component

Identifies a named UI component so agents know what section of the page they are looking at — useful for disambiguation when multiple similar regions exist.

Common Values:

navigationhero-bannerproduct-listproduct-cardmain-contentsidebarfootersearch-barbreadcrumb
<!-- Navigation -->
<nav
  aria-label="Main navigation"
  data-agent-component="navigation"
>
  <!-- nav items -->
</nav>

<!-- Hero section -->
<section
  data-agent-component="hero-banner"
  aria-label="Product hero"
>
  <!-- hero content -->
</section>

<!-- Product card -->
<article
  data-agent-component="product-card"
  data-agent-content-type="product"
>
  <!-- product details -->
</article>

data-agent-content

Marks specific content fields so agents can reliably extract values. Used inside components to label individual data points.

Common Values:

page-titlepage-descriptionproduct-nameproduct-descriptionproduct-pricesection-titlefallback-content
<article
  data-agent-component="product-card"
  data-agent-content-type="product"
>
  <h1 data-agent-content="product-name">
    Premium Wireless Headphones
  </h1>

  <p data-agent-content="product-description">
    Noise-canceling wireless headphones with 30-hour battery life
  </p>

  <span data-agent-content="product-price">$299.99</span>
</article>

Pro tip: Use data-agent-content alongside Schema.org structured data. Schema.org provides formal semantics; data-agent-contentmakes individual field extraction deterministic for agents that parse the DOM.

data-agent-action

Identifies the action performed by an interactive element (button, link, form). Helps agents understand exactly what clicking or submitting will do.

Common Values:

add-to-cartview-product-detailsgo-homebrowse-homeview-productsskip-to-contentget-support
<!-- Add to cart form -->
<form
  action="/cart/add"
  method="POST"
  data-agent-action="add-to-cart"
  data-agent-intent="purchase"
>
  <input type="hidden" name="product-id" value="headphones-001">
  <button type="submit">Add to Cart</button>
</form>

<!-- Navigation links -->
<a href="/" data-agent-action="go-home">Home</a>
<a href="/products" data-agent-action="view-products">Products</a>

<!-- Skip link -->
<a href="#main" data-agent-action="skip-to-content">
  Skip to main content
</a>

data-agent-mitigation

Marks elements that are mitigation strategies for client-side rendering limitations. Lets agents distinguish fallback/skeleton content from real content.

Common Values:

skeletonnoscript
<!-- Skeleton placeholder (shown while JS hydrates) -->
<div
  data-agent-mitigation="skeleton"
  aria-hidden="true"
>
  <!-- placeholder UI -->
</div>

<!-- Static fallback for no-JS environments -->
<noscript data-agent-mitigation="noscript">
  <div data-agent-component="product-card">
    <h1 data-agent-content="product-name">
      Premium Wireless Headphones
    </h1>
    <span data-agent-content="product-price">$299.99</span>
  </div>
</noscript>

Complete Product Page Example

<!DOCTYPE html>
<html
  lang="en"
  data-agent-framework="nextjs"
  data-agent-version="1.0"
  data-agent-context="product"
  data-agent-mode="ssr"
>
<head>
  <title>Premium Wireless Headphones - AudioTech</title>
</head>
<body>
  <a
    href="#main"
    data-agent-action="skip-to-content"
  >
    Skip to main content
  </a>

  <header>
    <nav
      aria-label="Main navigation"
      data-agent-component="navigation"
    >
      <a href="/" data-agent-action="go-home">Home</a>
      <a href="/products" data-agent-action="view-products">Products</a>
    </nav>
  </header>

  <main
    id="main"
    data-agent-page="product-detail"
    data-agent-intent="purchase"
    data-agent-content-type="product"
  >
    <article data-agent-component="product-card">
      <h1 data-agent-content="product-name">
        Premium Wireless Headphones
      </h1>

      <p data-agent-content="product-description">
        Experience studio-quality audio with active noise cancellation
        and 30-hour battery life.
      </p>

      <span data-agent-content="product-price">$299.99</span>

      <form
        action="/cart/add"
        method="POST"
        data-agent-action="add-to-cart"
        data-agent-intent="purchase"
      >
        <input type="hidden" name="product-id" value="headphones-001">
        <label for="quantity">Quantity</label>
        <input
          type="number"
          id="quantity"
          name="quantity"
          min="1"
          max="10"
          value="1"
          aria-required="true"
        >
        <button type="submit">Add to Cart</button>
      </form>
    </article>
  </main>

  <footer data-agent-component="footer">
    <p>&copy; 2025 AudioTech. All rights reserved.</p>
  </footer>
</body>
</html>

Testing Agent Attributes

1. The Curl Test

Verify that your data attributes appear in the HTML source:

curl -s https://yoursite.com/product | grep "data-agent"

2. JavaScript Extraction Test

Test programmatic extraction from the browser console:

// Find all product cards
const cards = document.querySelectorAll('[data-agent-component="product-card"]');

cards.forEach(card => {
  const name = card.querySelector('[data-agent-content="product-name"]')?.textContent;
  const price = card.querySelector('[data-agent-content="product-price"]')?.textContent;
  console.log({ name, price });
});

// Find all available actions
const actions = document.querySelectorAll('[data-agent-action]');
actions.forEach(el => {
  console.log(el.dataset.agentAction, el.textContent.trim());
});

3. Repo Validator Tools

Use the validator scripts included in the repository:

node tools/validators/fr1-checker.js https://yoursite.com --verbose
node tools/validators/fr1-validator.js https://yoursite.com

4. Agent Simulation

Ask an AI agent (like Claude or GPT-4) to browse your site and complete a task. See if it can find and use the marked-up actions correctly.

Best Practices

DO

  • • Use the data-agent-* namespace exclusively — do not invent custom sub-namespaces
  • • Keep attribute values consistent across your site
  • • Combine agent attributes with semantic HTML and ARIA
  • • Mark all transactional actions clearly with data-agent-action and data-agent-intent
  • • Use data-agent-content to make field extraction deterministic
  • • Test with actual agent simulators, not just human review

DON'T

  • • Use agent attributes as a substitute for semantic HTML — they are supplementary
  • • Mix in non-namespaced attributes like data-agent-action or data-agent-field
  • • Include implementation details in attribute values (e.g., data-agent-action="POST-to-api")
  • • Change attribute conventions frequently — consistency is critical
  • • Assume agents will infer meaning without explicit markup

Agent Attribute Quick Reference

Page-Level

  • data-agent-framework
  • data-agent-version
  • data-agent-context
  • data-agent-mode

Page Content

  • data-agent-page
  • data-agent-intent
  • data-agent-content-type

Components & Content

  • data-agent-component
  • data-agent-content

Actions & Mitigations

  • data-agent-action
  • data-agent-mitigation
← Structured DataProgressive Enhancement →