Executive Summary

Making a website *agent-friendly* means exposing content and functionality in predictable, machine-readable ways. Drawing on UAIX’s framework, we categorize agent capabilities into **Perceive, Navigate, Act, Communica...

Metadata

Field	Value
Source site	aiwikis.org
Source URL	https://aiwikis.org/
Canonical AIWikis URL	https://aiwikis.org/aiwikis/files/raw-uaix-reports-2026-06-21-ai-ready-web-program-making-a-website-agent-65c4dc2a/
Source reference	raw/uaix/reports/2026-06-21-ai-ready-web-program/Making a website agent-friendly.md
File type	md
Content category	memory-file
Last fetched	2026-06-22T01:56:21.9510185Z
Last changed	2026-06-21T14:21:17.8793880Z
Content hash	sha256:65c4dc2a7a6ce702abbf3256eab45f2b39726017715da85f3556e48d51d45c34
Import status	new
Raw source layer	data/sources/aiwikis/raw-uaix-reports-2026-06-21-ai-ready-web-program-making-a-website-agent-friendly-md-65c4dc2a7a6c.md
Normalized source layer	data/normalized/aiwikis/raw-uaix-reports-2026-06-21-ai-ready-web-program-making-a-website-agent-friendly-md-65c4dc2a7a6c.txt

Current File Content

Structure Preview

• Executive Summary
• UAIX Capability Mapping
• HTML/CSS/JS Patterns
• APIs and Technical Rules
• Authentication and Agent-Friendly Auth
• Error Handling, Idempotency, Observability
• Performance, Pagination, Large Data
• Security & Privacy Trade-offs
• Checklist for Developers
• Testing Plan and Metrics

Raw Version

This public page shows a bounded preview of a large source file. The complete source remains in the raw and normalized source layers named in metadata, with the SHA-256 hash above for verification.

• Source characters: 21852
• Preview characters: 11815

# Executive Summary

Making a website *agent-friendly* means exposing content and functionality in predictable, machine-readable ways.  Drawing on UAIX’s framework, we categorize agent capabilities into **Perceive, Navigate, Act, Communicate, Authenticate/Authorize,** and **Observe/State**.  For each, we map best practices:

- **Perceive:** Use **semantic HTML** and ARIA so agents can “read” content.  Provide alternative text (`alt`), clear headings, and explicit structure.  Embed **structured data** (e.g. JSON-LD with [schema.org](https://schema.org/) vocabularies) so agents immediately understand page meaning.
- **Navigate:** Offer explicit links and indexes.  Include `<a>` anchors, a sitemap (`sitemap.xml` or `Link: <.../sitemap.xml>`), and even a UAIX-style `llms.txt` file with agent hints.  Avoid hidden navigation or heavy JavaScript that blocks crawl.
- **Act:** Expose actions through standard web endpoints.  Use HTML `<form>`s or REST/GraphQL APIs instead of obscure scripts.  Follow HTTP conventions (safe GETs, idempotent POST/PUT).  Respond with proper status codes and headers (e.g. `HTTP/429` for rate-limit).  Enable CORS (`Access-Control-Allow-Origin`) so cross-origin clients can call your APIs.
- **Communicate:** Provide agent protocols and endpoints.  For example, publish machine-readable guides or chat interfaces (e.g. WebSockets or SSE for real-time data).  Document expected message formats (JSON schemas, OpenAPI specs).  Support cross-agent messaging (UAIX’s Agent-to-Agent model) by exposing tokenized endpoints or webhooks.
- **Authenticate/Authorize:** Allow non-interactive logins.  Use token-based schemes (OAuth client-credentials, API keys, JWTs) so agents can obtain limited-scope access without a human login.  For instance, the OAuth2 “client credentials” grant lets a service account fetch a bearer token.  Support **delegated tokens** (on-behalf-of flows) for acting as users when needed.  Also offer simpler options (API keys or signed tokens) for trusted bots.
- **Observe/State:** Make site health and state visible.  Provide status and metrics endpoints (`/status`, `/health`, JSON dashboards).  Emit logs or support webhooks/events that agents can consume.  Use standardized formats for error payloads and results so clients can parse them automatically.

Across these dimensions, the key is **openness and predictability**: use well-known HTML attributes (e.g. `<h1>…</h1>`, `<img alt="…">`, ARIA `role`/`aria-*`), standard HTTP headers (CORS, content type, `Link` for pagination), and documented endpoints (REST/GraphQL).  This ensures lower-capability agents (UAIX L0–L2) can at least retrieve basic data, while higher-level agents (L3–L5) can authenticate and perform complex workflows.  We summarize these best practices in the checklist and mapping table below.

## UAIX Capability Mapping

UAIX defines a **capability ladder** (L0–L5) that aligns roughly with our categories. For example: at L0 (URL-only), an agent can only `GET` public URLs; at L1 it parses JSON from simple endpoints; at L2 it reads schemas and uses `POST` JSON; higher levels add auth and state.  Table 1 maps each capability to concrete web features.

| UAIX Capability      | HTML/CSS/JS Patterns & Markup                               | HTTP Headers / Endpoints / Examples                               |
|----------------------|-------------------------------------------------------------|-------------------------------------------------------------------|
| **Perceive**         | Use semantic elements (`<article>`, `<nav>`, `<h1>…<h6>`, `<table>`, etc.) and ARIA roles to expose structure and meaning.  Provide `alt` text on images, labels on forms, transcripts on media.  Embed JSON-LD/Microdata with schema.org vocabularies so agents can extract facts.  Avoid purely canvas/SVG/Flash interfaces. | Support content negotiation (`Accept` header) and language variants (`Accept-Language` → `Vary: Accept-Language`).  Offer static formats (HTML) and also machine-oriented formats (JSON, CSV, XML).  Include a `llms.txt` (UAIX) or `robots.txt` at site root.  Indicate robots policy via `<meta name="robots" content="noindex">` or `X-Robots-Tag` header if needed. |
| **Navigate**         | Use meaningful `<a href="…">` links (not `onclick`), and include navigation landmarks (`<nav>`, `<ul>` for menus).  Include a `<link rel="next">`/`<link rel="prev">` in HTML or `Link` headers for pagination.  Provide a sitemap.xml or index page listing all resources.  Use breadcrumbs and content sections.  Ensure dynamic site navigation degrades gracefully (e.g. initial HTML <noscript> or pre-rendered content). | Expose `sitemap.xml` (with `<url>` entries) and accept range requests for large lists.  Provide HTTP `Link` header for pagination or related resources.  Use standard caching headers (`Cache-Control`, `ETag`, `Last-Modified`) so agents can poll efficiently.  Honor `robots.txt` rules (PUT it at “/robots.txt” in UTF-8 text). |
| **Act**              | Expose forms or APIs for actions.  Use HTML `<form method="POST">` or JavaScript `fetch()` to call REST endpoints.  If using JS, ensure a non-JS fallback (progressive enhancement).  Mark up interactive widgets with ARIA (`role="button"`, `aria-pressed`, etc.) so state changes are visible to assistive crawlers.  Use standard HTTP methods: GET for reads, POST/PUT/PATCH for writes.  Include HTML `<form action>` fields and JSON body schemas in API docs. | Follow HTTP best practices: safe methods (GET) don’t change state; idempotent methods (PUT/DELETE) can be retried; use `POST` only for non-idempotent writes.  Return clear status codes (200 OK, 201 Created, 404 Not Found, etc.) with JSON/XML bodies.  For rate limiting, return `429 Too Many Requests` with a `Retry-After` header.  Handle CORS so agents on other domains can call APIs: e.g. `Access-Control-Allow-Origin: *` or specific domains and support pre-flight `OPTIONS` requests.  Document your API (OpenAPI/GraphQL schema) so agents know how to call it. |
| **Communicate**      | If agents must exchange messages (e.g. chat), provide a machine-readable interface (e.g. WebSocket or JSON over HTTP).  Use Webhooks or publish/subscribe (Pub/Sub) endpoints.  Label message formats (JSON schema, HTML5 `<dialog>`, Atom/RSS feeds) so programs can parse them.  For interoperability, implement OAuth2/OpenID endpoints to allow agent delegation. | Provide network interfaces for push events (Server-Sent Events `/events`, WebSocket URLs, or webhook callbacks).  For custom protocols, use HTTP verbs (e.g. `POST /incoming-message`).  Tag messages with JSON-LD context or XMPP/Jabber schemas if relevant.  Include cross-agent discovery endpoints (UAIX’s “agent access manifest” or `.well-known/uaix-agent-access.json`). |
| **Authenticate/Authorize** | Support loginless auth.  Avoid requiring human-only CAPTCHA or SSO flows.  Provide OAuth2 flows (authorization code for user agents, client credentials for machines).  Allow API keys or JWT-based tokens as alternatives.  Clearly document the auth endpoint (e.g. `/oauth/token`).  Use standardized HTTP headers (e.g. `Authorization: Bearer <token>`) and schemas (RFC 6750 Bearer tokens). | Implement OAuth2 with TLS (RFC 6749) so machines can obtain tokens.  For example, the **Client Credentials** flow lets a service obtain a bearer token by sending `POST /oauth/token` with `Authorization: Basic <client_secret>`.  Support `WWW-Authenticate` challenges or `X-API-Key` headers for simpler keys.  Use secure, short-lived tokens (JWTs or opaque) and scopes to limit access.  Offer a “delegated token” (OIDC / JWT `sub` delegation) for cross-service calls.  If using cookies, ensure agents handle them (e.g. include `Set-Cookie` in JSON workflows).  Provide clear refresh-token or API-key rotation processes. |
| **Observe/State**    | Expose site health and metrics.  Provide a `/health` or `/status` endpoint that returns JSON status (uptime, version, component status).  Include events or logs in a parseable format (e.g. JSON lines, audit logs).  Mark dynamic content updates with ARIA live regions (for screen readers) so agents tracking changes get notifications. | Use a **status endpoint** returning JSON (e.g. `{"status":"ok","services":{"db":"up"}}`).  Support monitoring protocols (Prometheus, OpenAPI health check schemas).  For logging and monitoring, push events to webhooks or use syslog endpoints.  Provide API endpoints for event streams (SSE or WebSocket) with reconnection support.  Return debug info only to authenticated/authorized agents.  Expose **idempotency keys** and deterministic results so agents can retry safely (e.g. use `Idempotency-Key` header for POSTs). |

Table 1: *Mapping of UAIX agent capabilities to concrete web design practices and features.*

## HTML/CSS/JS Patterns

- **Semantic Markup:** Always use meaningful tags. E.g. `<h1>Title</h1>`, `<article>`, `<section>`, `<nav>`, etc. Assistive and search technologies (and agents) leverage these: *“search engines give more importance to keywords inside headings, links, etc.”*.  Use `<label>` with `for=` and `alt` on images, ensure color/text contrast (for OCR), and avoid conveying information by color or image alone.
- **ARIA:** For dynamic widgets (dropdowns, tabs, progress bars), add ARIA roles and states so bots know the semantics. ARIA “improves the accessibility and interoperability of web content”.  E.g. `<button aria-pressed="false">Show</button>`.  These roles make widgets readable via accessibility APIs.
- **Progressive Enhancement:** Build features in plain HTML first, then layer JS. Agents often can’t run JavaScript fully. For example, if using a JS grid, also include a fallback HTML table or a JSON endpoint for the same data.
- **CSS/JS Hints:** Avoid techniques that hide content from text-based agents (e.g. `<meta name="fragment">`, excessive canvas use, or obfuscating scripts). If using a SPA framework, ensure server-side rendering or static snapshots exist.
- **Structured Data:** Embed JSON-LD or Microdata so machines can parse content without in-page heuristics. Google recommends JSON-LD where possible and notes: *“Google uses structured data that it finds on the web to understand the content of the page…”*.  For example:

  ```html
  <script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "Example Title",
    "author": {"@type":"Person","name":"Alice"},
    "image": "https://example.com/image.png",
    "datePublished": "2026-06-21"
  }
  </script>
  ```

  This lets an agent know exactly what the page is about.  Schema.org’s community vocabularies are widely used by Google, Microsoft, etc. to enable rich features.

## APIs and Technical Rules

- **Content Negotiation:** Support `Accept` headers.  If your site can serve HTML **and** JSON, respond with the appropriate `Content-Type` based on `Accept: application/json` or `text/html`.  Include a `Vary: Accept` header.  As HTTP/1.1 says, servers “often have different ways of representing information… [so] HTTP provides mechanisms for content negotiation”.
- **CORS:** If agents call APIs from a different origin (e.g. a browser agent on domain A calling domain B), enable CORS.  Add `Access-Control-Allow-Origin: *` (or specific domains) in responses.  For non-GET methods, support preflight: respond to `OPTIONS` with `Access-Control-Allow-Methods: GET,POST,...` and `Access-Control-Allow-Headers: Content-Type,Authorization`, etc..  Failure to configure this will block cross-domain requests.
- **Rate Limiting:** Protect endpoints, but communicate limits. Use `429 Too Many Requests` (RFC 6585) when a client exceeds a quota. Include `Retry-After: <seconds>` to tell the agent how long to wait. This lets a polite agent back off properly.

Why This File Exists

This is a memory-system evidence file from aiwikis.org. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is memory-system evidence. It records source history, archive transfer, intake disposition, or another piece of provenance that should be retrievable without becoming an unsupported public claim.

Structure

The file is structured around these visible headings: Executive Summary; UAIX Capability Mapping; HTML/CSS/JS Patterns; APIs and Technical Rules; Authentication and Agent-Friendly Auth; Error Handling, Idempotency, Observability; Performance, Pagination, Large Data; Security & Privacy Trade-offs. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

• Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
• LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
• Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
• Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

• Source overview
• Site file index
• Site report index
• UAI system index
• Source provenance
• Site directory
• Organization reports

Provenance And History

• Current observation: 2026-06-22T01:56:21.9510185Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-492 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "Executive Summary",
    "source_site":  "aiwikis.org",
    "source_url":  "https://aiwikis.org/",
    "canonical_url":  "https://aiwikis.org/aiwikis/files/raw-uaix-reports-2026-06-21-ai-ready-web-program-making-a-website-agent-65c4dc2a/",
    "source_reference":  "raw/uaix/reports/2026-06-21-ai-ready-web-program/Making a website agent-friendly.md",
    "file_type":  "md",
    "content_category":  "memory-file",
    "content_hash":  "sha256:65c4dc2a7a6ce702abbf3256eab45f2b39726017715da85f3556e48d51d45c34",
    "last_fetched":  "2026-06-22T01:56:21.9510185Z",
    "last_changed":  "2026-06-21T14:21:17.8793880Z",
    "import_status":  "new",
    "duplicate_group_id":  "sfg-492",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-06-22T01:56:21.9510185Z"
}