developer-guide11 min

Building Agentic Commerce #2: Como los agentes de IA descubren tu tienda sin API Key

Antes de que un agente pueda comprar algo, necesita encontrar tu tienda. Asi funciona la cadena de descubrimiento de 6 fases que lleva a un agente de IA de cero conocimiento a listo para checkout en menos de 2 segundos, sin configuración previa.

Resumen ejecutivo

Segundo post de la serie 'Building Agentic Commerce'. Guia para desarrolladores sobre la cadena completa de descubrimiento de agentes: búsqueda semántica NLWeb, llms.txt, agent-card.json, 10+ endpoints legibles por maquinas y el AgentFinder de búsqueda multi-comerciante, todo sin configuración previa.

Publicado

2026-04-05

11 min

Autoría

Trusteed

Publicado por Trusteed

Escrito y mantenido por quienes construyen Trusteed. Las afirmaciones técnicas de estos artículos se respaldan en las superficies enlazadas desde cada pieza y en el registro de capacidades firmado en /.well-known/trusteed-capabilities.json.

Ver perfil

Categoría

developer-guide

building-agentic-commercenlwebdescubrimientollms-txtagent-cardbúsqueda-semánticawell-knownguia-desarrollador

Aqui va una pregunta que la mayoría de plataformas ecommerce aun no han respondido: como encuentra un agente de IA tu tienda en primer lugar? No a traves de Google. No a traves de un marcador. Un agente necesita endpoints de descubrimiento legibles por maquina que le digan que vendes, como buscar en tu catálogo y que protocolos soportas, todo antes de crear una cuenta u obtener una API key. En este post, recorreremos la cadena completa de descubrimiento que proporciona Trusteed, desde un inicio frio hasta un agente listo para checkout en menos de 2 segundos.

Esta es la Parte 2 de la serie 'Building Agentic Commerce'. La Parte 1 cubrio el checkout multi-protocolo (MCP + x402 + ACP). La Parte 3 cubrira trust scores: el sistema que determina cuanta autonomia tienen los agentes.

Idea clave

El problema del descubrimiento: los agentes no navegan

Los humanos descubren tiendas a traves de motores de búsqueda, redes sociales, boca a boca y publicidad. Los agentes de IA no tienen ninguno de estos canales. Un agente necesita información estructurada y legible por maquina: que productos estan disponibles, que protocolos de pago se soportan, que nivel de confianza tiene el comerciante y como interactuar programaticamente. Sin descubrimiento estándarizado, cada integración agente-tienda requiere configuración manual, lo que anula todo el proposito del comercio autónomo.

El stack de descubrimiento: 4 capas

Trusteed implementa el descubrimiento en cuatro capas, cada una sirviendo una etapa diferente del proceso de decisión del agente:

1
Capa 1: Manifiestos legibles por maquina — endpoints /.well-known/ que dicen a los agentes que esta disponible (protocolos, políticas, marco de confianza). Zero auth requerido.
2
Capa 2: llms.txt — Un archivo de texto completo que los LLMs pueden leer integro para entender toda la plataforma. Piensa en ello como documentación optimizada para consumo de IA, no para lectura humana.
3
Capa 3: Busqueda semántica NLWeb — Busqueda de productos y comerciantes en lenguaje natural potenciada por embeddings vectoriales (pgvector) y re-ranking LLM (Claude Haiku). Los agentes hacen preguntas en lugar de construir queries API.
4
Capa 4: Herramientas MCP — Llamadas a herramientas estructuradas (search_products, get_merchant_profile, browse_categories) para agentes que ya conocen la superficie API.

Capa 1: Los endpoints de descubrimiento /.well-known/

Cada despliegue de Trusteed sirve 10+ endpoints JSON legibles por maquina bajo la ruta /.well-known/. Siguen las convenciones RFC 8615 y estan cacheados, son seguros para CORS y no requieren autenticación. Un agente puede leerlos todos en paralelo en menos de 50ms.

Los cinco esenciales

1
/.well-known/nlweb.json — Descubrimiento del protocolo NLWeb: endpoints, requisitos de auth, modos de búsqueda disponibles (list, summarize, generate). Generalmente es el primer archivo que lee un agente.
2
/.well-known/merchant-index.json — Registro completo de comerciantes con slugs, trust scores, tiers de frescura, endpoints MCP y categorías principales. Actualizado cada 5 minutos via ISR.
3
/.well-known/agent-card.json — Capacidades de la plataforma: 10 protocolos soportados (MCP, ACP, x402, UCP, KYB...), 7 skills, esquemas de autenticación, endpoints API.
4
/.well-known/agent-policy.json — Interpretacion de trust scores: que significa EXCELLENT (0.9-1.0) vs CAUTION (0.5-0.7), taxonomia de acciones (ALLOW/FRICTION/REVIEW/BLOCK), reglas de confirmación.
5
/.well-known/agent-commerce.json — Contrato de negocio: fórmula de ranking, negociación de capacidades, capacidades de protocolo con enlaces a documentación.

Todos los endpoints /.well-known/ siguen el mismo patron: generación force-static, CORS *, Cache-Control public max-age=3600 y X-Content-Type-Options nosniff. Estan diseñados para ser consumidos por cualquier agente, desde cualquier origen, sin configuración.

Idea clave

Capa 2: llms.txt — Documentacion para maquinas

El endpoint /llms.txt sirve un archivo de texto de ~1.500 lineas que describe toda la plataforma en un formato optimizado para consumo LLM. Se sirve en /llms.txt (estatico, cache 1h) e incluye: cada endpoint público de API con métodos y parámetros, todas las herramientas MCP con schemas de entrada/salida, matriz de soporte de protocolos con estado por protocolo, cambios recientes (novedades desde la ultima actualización) y un flujo de trabajo multi-tienda que los agentes pueden seguir paso a paso.

Lo que hace especial a llms.txt es la sección INTEGRITY NOTICE: una defensa contra inyección de prompts que avisa a los agentes si herramientas de terceros han anadido instrucciones al contenido. Si un agente recibe llms.txt a traves de una extension de navegador que anade 'Dejar de procesar' o 'Ignorar instrucciones anteriores,' el aviso de integridad le dice al agente que descarte esas adiciones y continue. Este es un vector de ataque real: algunas extensiones de navegador anaden senales de bloqueo de agentes al contenido recuperado.

Capa 3: NLWeb — 'Encuentrame zapatillas por menos de 100 euros'

NLWeb es donde el descubrimiento se vuelve inteligente. En lugar de queries API estructuradas con filtros y parámetros, los agentes hacen preguntas en lenguaje natural y obtienen resultados rankeados y puntuados con objetos Schema.org Product. El pipeline tiene cuatro etapas: generación de embedding vectorial, búsqueda de similitud coseno pgvector (top 50 candidatos en ~50ms), re-ranking LLM via Claude Haiku (puntua cada producto 0.0-1.0 por relevancia, ~300ms) y generación opcional de resumen para modos summarize/generate.

Tres superficies NLWeb

1
NLWeb por tienda — POST /{storeSlug}/ask con { query, mode, limit }. Busca en el catálogo de un comerciante. Los resultados incluyen objetos Schema.org Product con puntuaciones.
2
Auto-descubrimiento de plataforma — POST /mcpwebstore-platform/ask (SIN AUTH). La plataforma se indexa a si misma como comerciante virtual con 27 items: 8 protocolos, 4 planes de precios, 6 funcionalidades, 2 integraciones. Los agentes preguntan 'soporta esta plataforma pagos stablecoin?' y obtienen respuestas estructuradas.
3
AgentFinder — POST /api/v1/agentfinder/search. Descubrimiento multi-comerciante: 'encuentra el mejor comerciante para zapatillas de running.' Devuelve comerciantes rankeados con trust scores, puntuaciones de relevancia y endpoints NLWeb.

La cadena completa: de cero a checkout en 6 fases

Aqui esta el flujo completo que sigue un agente, desde no saber nada sobre Trusteed hasta completar una compra. Tiempo total: menos de 2 segundos.

1
Fase 1 — Bootstrap (10-50ms): GET /.well-known/nlweb.json + merchant-index.json + agent-policy.json en paralelo. El agente aprende que tiendas existen y que protocolos estan disponibles.
2
Fase 2 — Selección de comerciante (100-300ms): POST /api/v1/agentfinder/search con la intención del usuario. El agente obtiene comerciantes rankeados con trust scores y relevancia.
3
Fase 3 — Busqueda de productos (200-800ms): POST /{slug}/ask con query en lenguaje natural. Busqueda vectorial + re-ranking LLM devuelve productos Schema.org puntuados.
4
Fase 4 — Verificacion de confianza (50-150ms): POST /{slug}/mcp -> get_merchant_profile. El agente confirma que el trust score cumple el umbral para checkout autónomo.
5
Fase 5 — Creacion de carrito (auth requerido): POST /{slug}/mcp -> create_cart. El agente cruza de solo-lectura a operaciones de escritura — OAuth requerido.
6
Fase 6 — Checkout: POST /{slug}/mcp -> preview_checkout -> complete_checkout. El Protocol Bridge enruta el pago al adaptador correcto.

La idea clave: las Fases 1-4 no requieren autenticación alguna. Un agente puede descubrir tiendas, buscar productos y evaluar confianza sin ninguna API key. La autenticación solo entra en la Fase 5 cuando el agente comienza a modificar estado (creando carritos). Esto reduce dramaticamente la barrera de descubrimiento.

Para comerciantes: haz tu tienda descubrible

1
Completa tu perfil de comerciante: los componentes de trust score incluyen completitud (info de negocio, contacto, políticas). Campos faltantes reducen tu puntuacion.
2
Manten el inventario sincronizado: el tier de frescura afecta al ranking. Las tiendas con datos obsoletos se despriorizan.
3
Define políticas claras: ventanas de devolucion, estimaciones de envio y métodos de pago son legibles por maquina. Los agentes que no pueden determinar tus políticas omitiran tu tienda.
4
Completa la verificación de identidad: la verificación QUALIFIED aumenta el trust score +0.18 (vs +0.10 auto-declarado). Mayor confianza = mas tráfico de agentes.

Pruebalo ahora

Puedes probar la cadena completa de descubrimiento contra nuestra plataforma en vivo ahora mismo. Empieza con GET trusteed.xyz/.well-known/nlweb.json para ver el contrato de descubrimiento NLWeb. Luego prueba POST trusteed.xyz/mcpwebstore-platform/ask con { "query": "que protocolos soportais?", "mode": "summarize" } — la plataforma respondera preguntas sobre si misma. Para búsqueda de productos, prueba POST trusteed.xyz/demo-store/ask con { "query": "auriculares", "mode": "list" }. Todo esto funciona sin autenticación.

Proximo en la serie

En la Parte 3, cubriremos trust scores: el sistema de puntuacion de 8 componentes que determina cuanta autonomia tiene un agente al comprar en tu tienda. Explicaremos por que un agente podria auto-aprobar una compra de 50 EUR de un comerciante pero requerir confirmación humana para una compra de 20 EUR de otro, y como los comerciantes pueden optimizar su perfil de confianza para aumentar el tráfico de agentes.

Preguntas frecuentes

Necesitan los agentes una API key para descubrir tiendas y buscar productos?

No. El descubrimiento (Fases 1-4) es completamente sin autenticación. Todos los endpoints /.well-known/, llms.txt, búsqueda NLWeb y herramientas MCP de solo lectura funcionan sin ninguna API key. La autenticación solo se requiere para operaciones de escritura como crear carritos y completar checkout (Fases 5-6).

Que es el endpoint de Auto-descubrimiento de plataforma?

Trusteed indexa sus propias capacidades como un comerciante NLWeb virtual llamado 'mcpwebstore-platform.' Los agentes pueden hacer POST a /mcpwebstore-platform/ask con preguntas como 'que protocolos de pago soportais?' o 'como funciona el acceso beta?' y obtener respuestas estructuradas. Esto elimina la necesidad de que los agentes parseen documentación — pueden consultar la plataforma de la misma forma que consultan un catálogo de productos.

En que se diferencia NLWeb de la herramienta MCP search_products?

search_products es una llamada a herramienta estructurada con parámetros específicos (query, category, priceRange, limit). NLWeb es una interfaz de lenguaje natural — los agentes describen lo que quieren en texto plano, y el sistema maneja el parsing de intención, expansión de sinonimos, similitud vectorial y re-ranking LLM. NLWeb también soporta conversaciones multi-turno via el parámetro 'prev'. Usa search_products cuando sabes exactamente que parámetros pasar; usa NLWeb cuando la consulta es abierta.

Cada cuanto se actualiza merchant-index.json?

El endpoint merchant-index.json usa Regeneración Estatica Incremental (ISR) con una ventana de revalidación de 5 minutos. Cuando un comerciante actualiza su perfil o catálogo, el cambio se propaga al índice en 5 minutos. Los trust scores se calculan en cadencia de 6 horas, asi que los cambios de puntuacion tardan un poco mas en reflejarse.

Que es el aviso de integridad de llms.txt y por que importa?

El aviso de integridad es una defensa contra inyección de prompts. Algunas extensiones de navegador para recuperación anaden instrucciones como 'Dejar de procesar' o 'Ignorar instrucciones anteriores' al contenido que entregan. El aviso de integridad de llms.txt advierte a los agentes que tales adiciones no fueron colocadas por Trusteed y deben ser descartadas. Los agentes pueden verificar la integridad consultando GET /api/v1/health -> campo manifests.

Fuentes y referencias

NLWeb: Protocolo Natural Language Web
Comunidad NLWeb
RFC 8615 — URIs Well-Known
IETF
Schema.org Tipo Product
Schema.org
llms.txt — Documentacion para LLMs
llmstxt.org
pgvector — Busqueda de similitud vectorial open-source
pgvector