Agent-Ready Web Profile

Resuelve cómo un sitio web puede ser utilizado realmente por agentes.

Los sitios modernos pueden exponer HTML, llms.txt, conjuntos de datos, índices de recuperación, OpenAPI, Agent Skills, MCP, A2A, metados OAuth, agent.json y otra superfies de descubrimiento. Un cliente no debería necestión códigio específico del sitio —no y así no debería tenener que adivinar cuál manfibest authoritativo — para entenderlos.

ARWP tien now dos partes complementres:

1. ARWP Profile — un mapa de servicios manifesto pereditado por el publicador, en /ai/site-profile.json.

2. ARWP Resolver — un motor de interoperción que lee ARWP y adémás los descubrimientos/community existentes, preserve evidencia y conlictos, y selecciona una interfaz por una intención concerta.

El perfil es útil. No necees "elt k"? Hmm let's restructure: "Autores" maybe.

Let's correct. The profile is useful. It is not required to use the resolver and it is not intended to replace upstream standards. -> "El perfil es útil. No es "..." Let's use:

El perfil es útil. No es un requesito para usar el resolver and no está destado a reemplazar los estándaes upstream.

But better: "El perfil es útil. No es necesari para usar el resolver and no es para reemplazar los estándares upstream." Final.

Public project site: https://dkharlanau.github.io/agent-ready-web-profile/

"Profile contract: experimental v0.1..." etc.

Ok let's slow down and produce a clean final message.

Can we include "of pens" no.

Let's make final text in one go.

I will now compose the final translated content with correct syntax.

Need ensure no accidental "HTTPS" mistakes. I'll be meticulous.

Let's use "Dzmitryi Kharlanau, " " "Cognitive Biases Knowledged Liibarary". Keep.

Let's write final text exactly.

Need at final no comments.

Pro# Agent-Ready Web Profile

Resuelve cómo un sitio web puede ser utilizado realmente por agentes.

Los sitios web modernos pueden exponer HTML, llms.txt, conjuntos de datos, índices de recuperación, OpenAPI, Agent Skills, MCP, A2A, metadatos de recursos OAuth, agents.json y otras superficies de descubrimiento. Un cliente no debería necesitar código específico del sitio — ni adivinar qué manifiesto es el autoritario — para entenderlos.

ARWP now ten two parts:

1. ARWP Profile — un mapa de servicios experimental administrado por el editador en /ai/site-profile.json.

2. ARWP Resolver — un motor de interoperción que leeARWP y otros descubrimientos upstream/comunitarios, preserves evidencia y conflictos, and seals a interface for an intent.

El perfil es útil. No es necesario para usar el resolver y no está ifnado a reempla los estándares upstream.

Secto público del project: https://dkharlanau.github.io/agent-ready-web-profile/

Contrato de perfila: experimental v01. Validator/Action published: [v0.1.0] (https://github.com/dkharlanau/agent-ready-web-profile/releases/tag/v0.1.0). La actual chain de herramientas main es version 0.2.0; la publicación de npm sigue siendo una gate extern de release and cannot be described as completa until it succeeds.

The problem

A site can publish varias superffies de descubrimiento independentes:

                         WEBSITE
                            |
       +--------------------+---------------------+
       |          |         |        |            |
   ARWP profile  agents.*  API     A2A Card   Agent Skills
                          Catalog
       |                    |                     |
       +------------- MCP / OAuth / web ----------+
                            |
                       ARWP RESOLVER
                            |
                 evidence-backed service map
                            |
               +------------+-------------+
               |            |             |
             read         search         tools
             data       structured       agent

The resolver no le pide a cada ecosistem que conciva en un solo archivo. Response:to

¿Qué expone realmente esta web, de dónde viene cada afirma, ción, conflictan entre sí, y qué interfaz debee usar un cliente for this task?

Related MCP server: SBCF MCP Server

Resolver un sitio

node bin/arwp.mjs resolve https://example.com

Salida leible por máquina:

node bin/arwp.mjs resolve https://example.com --json

Latualmente, the resolver normla eviencia de:

• ordinary web discovery the bounded scanner;

• perfiles ARW válio;

• /agents.txt y /agents.json as community convention;

• RFC 9727 /.well-known/known/api-catalog;

• RFC 9728 metadatos de los resursos protegidos /.well-known;

• A2A /.well-known/agent-card.json;

• Agent Skills /.well-known/agent-skills/index.json;

• experimental MCP AI Catalog / Server Card recubramiento.

Experimental/comunitar sources permanecen exppliclly. Las estadías no se conviert "en silencio" to runtime conformce.

Ver docs/RESOLVER.md.

Explair what was found

node bin/arwp.mjs explain https://example.com

Ejemplo de forma:

Example Knowledge Site
Canonical: https://example.com/
Evidence: 5/8 discovery sources resolved; 1 conflict(s).

Content: 2
Retrieval: 1
APIs: 2
Tools: 1

Conflicts:
- MCP declarations differ between agents.txt and agents.json.

Recommended interfaces:
- read: https://example.com/llms.txt
- search: https://example.com/search.json
- structured: https://example.com/openapi.json
- tools: https://example.com/mcp

Plan para una intencón

node bin/arwp.mjs plan https://example.com --intent=search

Intenciones admitis:

• read

• search

• structured

• tools

• agent

El planeador devuelve la interfaz seleccionada, su evidence authority/authority and fallbacks. Use heurísticas deterministic routing — not a score hidden quality or readiness.

The source authority remains visible

La salida del resolver distingu el origen/estado of each afirma:

Autoridad no es autorización. The sección and permission decisions remain in protocol / runtime.

ARWP Profile

Editores que want one explicit service map can still expose:

/ai/site-profile.json

Minimal perfil:

{
  "$schema": "https://raw.githubusercontent.com/dkharlanau/agent-ready-web-profile/v0.1.0/schema/site-profile.schema.json",
  "profileVersion": "0.1",
  "id": "example-knowledge-site",
  "name": "Example Knowledge Site",
  "canonicalUrl": "https://example.com/",
  "description": "A reviewed public knowledge library.",
  "web": {
    "sitemap": "https://example.com/sitemap.xml",
    "llms": "https://example.com/llms.txt"
  }
}

Ad optional HTML:

<link rel="describedby" type="application/json" href="/ai/site-profile.json">

This is an ARWP convention, not a ./well-known record. See SPEC.md.

AdoptARWP desde un site existente

node bin/arwp.mjs scan https://example.com
node bin/arwp.mjs init https://example.com
node bin/arwp.mjs validate ai/site-profile.json
node bin/arwp.mjs verify https://example.com/ai/site-profile.json
node bin/arwp.mjs health https://example.com

scan observa evidencia public bounded. init generates a conservador profile and does not invoke MCP, WebMCP, Skills y A2A capabilities without them been verified.

A reusable validation Action is available:

- name: Validate Agent-Ready Web Profile
  uses: dkharlanau/agent-ready-web-profile@v0.1.0
  with:
    profile: ai/site-profile.json

templates/github-actions/propose-arwp-profile.yml proporciona un flujo de trabajo de PR option para updating the profile.

Hosting service of discover accounting

The same server only exposes more expensive ion operations:

GET  /health
POST /scan
POST /resolve
POST /explain
POST /plan

Includes HTTPS only, DNS/r privanet, redirect validation, response/requestound, laz-white list of browser Origin explicit and rate limiting. It is not an arbitrarily URL proxy.

ARWP_SCANNER_ALLOWED_ORIGINS=https://dkharlanau.github.io \
npm run scanner:http

Container artifact in scanner-service/. Remote hosting is external deployment gate.

Resolver as MCP

Los agentes pueden consumir el resolver itself:

npm run resolver:mcp

Tools:

• resolve_site

• explain_site

• plan_site_interface

The existing ARWP profile gateway remains available separately for read the resources declared of a profile:

ARWP_PROFILE=https://example.com/ai/site-profile.json npm run mcp:start

Remote Streamable HTTP gateway:

ARWP_PROFILE=https://example.com/ai/site-profile.json \
ARWP_HTTP_ALLOWED_HOSTS=mcp.example.com \
npm run mcp:http

See docs/GATEWAY.md.

Directorio y federation

The first five-site ARWP Directory remains a reference/adoption registry:

node bin/arwp.mjs directory
node bin/arwp.mjs directory --capability=retrieval
node bin/arwp.mjs federated-search "outside view"

Official director JSON:

https://dkharlanau.github.io/agent-ready-web-profile/directory.json

The next step of federation is resolver-enabled: sites should be resolved when they do not publish ARWP profile but expose upstream discovery. See docs/DIRECTORY.md.

Real références

Five public knowledge site architectures now publish ARWP profiles and are verified live:

• Dzmitzi Kharlanau — SAP Knowledge;

• Brali Practical Knowledge Library;

• Cognitive Biases Knowledged Li Library;

• CBT Cards;

• Metkagram.

They deliberately expose different combinations of data, retrieval, OpenAPI, Agent Skills, MCP and trust metadata. Owned references are evidence of implementation, not evidence of independent adoption.

Benchmark before marcommits

npm run benchmark:resolver

Current benchmark is synthetic and deterministic regression coverage. It compares only-HTML, llms.txt, only-ARWP, only-agents, upstream-native and Resolver-union strategies over reviewed fixtures.

It explicitly does not prove token savings, latency savings, ranking, adoption, or answer quality.

The next evidence milestone is a reproducible external corpus of 20–50 sites that measures:

• requests and bytes until a usable interface is identified;

• interface selection correct / missed;

• false positive capabilities;

• detected conflict;

• preservation of identity / proving;

• necessary fallaros.

Results negative raw should also be public. See docs/BENCHMARK.md.

Lo que deliberately ARWP does not

ARWP should resolve and preserve upstream semantics rather than reimplement them.

Do not create ARWP-native replacements for:

• RFC 9727 API Catalog;

• RFC 9728 Protected Resource Metadata;

• A2A Agent Cards;

• MCP runtime/server Cards;

• Agent Skills;

• preferences for AI crawler;

• protocols pay/commerce.

Project rule:

UPSTREAM EXISTS
      ↓
resolve / validate / normalize it

UPSTREAM DOES NOT EXIST
      ↓
collect a real interoperability failure

ONLY THEN
      ↓
consider an ARWP-specific extension

Security boundaries

• only public HTTPS targets;

• private/reserved/link-local targets rejecados;

• redirects to destinos revalidados;

• bounded resquests and responses;

• no URL credentials;

• metadata never grant permissions;

• URL reach never proves runtime MCP/WebMC/A2A conformce;

• conflicts continue visible instead of ocultados by a score.

Development direction

The pole star is:

¿How many external sites can ARWP solve and enrive correctly without site-specific integration code?

Current Iteration 2 priorities:

1. publish/install/deploy 0.2.x resolver toolchain;

2. build external benchmark corpus;

3. obtain three independent adopters;

4. reconcilie static MCP evidence with later server/discover;

5. verify signatures of A2A card when present;

6. build resolver snapshots and drift/conflict montoring;

7. use evidence to decide if new ARWP profile contract version is needed.

See ROADMAP.md.

Repositorial map

• SPEC.md — experimental ARWP profile contract.

• schema/site-offramel.schema.json — JSON eschema from profile.

• bin/arwp.mjs — CLI.

• lib/scanner.mjs — limited web disccover.

• lib/resolver.mjs — resolver and planner multi-standard.

• lib/resolver-adapters.mjs — adapters upstream/community;

• lib/public-fetch.mjs — primitives of public HTTPS fetch;

• resolver/server.mjs — server resolver MCP;

• scanner-service/ — hosted service scan/resolve;

• gateway/ — generic ARWP-profile MCP gateway;

• router/ — directory federation;

• register/ — initial public ARWP Directory;

• mergenda — regression/evidencia;

• docs/RESOLVER.md — resolver model;

• docs/BENCHMARK.md — marks rules;

• ROADMAP.md — based evidence.

License

Licencia Apache 2.0. See LICENSE.