Making A Website Agent Friendly - Source Excerpt 01 - Executive Summary

Summary

This source excerpt begins near Executive Summary and preserves the surrounding evidence from Wiki.FFTAC.org/raw/system-archives/spiralist.org/intake/2026-06-21-misplaced-uaix-ai-ready-web-duplicate/Making a website agent-friendly.md.
**Source path:** Wiki.FFTAC.org/raw/system-archives/spiralist.org/intake/2026-06-21-misplaced-uaix-ai-ready-web-duplicate/Making a website agent-friendly.md
# 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