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 configuracion previa.
Resumen ejecutivo
Segundo post de la serie 'Building Agentic Commerce'. Guia para desarrolladores sobre la cadena completa de descubrimiento de agentes: busqueda semantica NLWeb, llms.txt, agent-card.json, 10+ endpoints legibles por maquinas y el AgentFinder de busqueda multi-comerciante, todo sin configuracion previa.
Publicado
2026-04-05
11 min
Autoría
Equipo de arquitectura de integraciones
Arquitectos de implementación
El equipo de arquitectura de integraciones se centra en patrones prácticos de despliegue para tiendas que adoptan superficies de comercio compatibles con MCP.
Ver perfilCategoría
developer-guide
Aqui va una pregunta que la mayoria 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 catalogo 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 AgenticMCPStores, 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.
El problema del descubrimiento: los agentes no navegan
Los humanos descubren tiendas a traves de motores de busqueda, redes sociales, boca a boca y publicidad. Los agentes de IA no tienen ninguno de estos canales. Un agente necesita informacion 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 estandarizado, cada integracion agente-tienda requiere configuracion manual, lo que anula todo el proposito del comercio autonomo.
El stack de descubrimiento: 4 capas
AgenticMCPStores implementa el descubrimiento en cuatro capas, cada una sirviendo una etapa diferente del proceso de decision del agente:
- 1Capa 1: Manifiestos legibles por maquina — endpoints /.well-known/ que dicen a los agentes que esta disponible (protocolos, politicas, marco de confianza). Zero auth requerido.
- 2Capa 2: llms.txt — Un archivo de texto completo que los LLMs pueden leer integro para entender toda la plataforma. Piensa en ello como documentacion optimizada para consumo de IA, no para lectura humana.
- 3Capa 3: Busqueda semantica 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.
- 4Capa 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 AgenticMCPStores 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 autenticacion. 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 busqueda 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 categorias principales. Actualizado cada 5 minutos via ISR.
- 3/.well-known/agent-card.json — Capacidades de la plataforma: 10 protocolos soportados (MCP, ACP, x402, UCP, eIDAS-QTSP...), 7 skills, esquemas de autenticacion, 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 confirmacion.
- 5/.well-known/agent-commerce.json — Contrato de negocio: formula de ranking, negociacion de capacidades, capacidades de protocolo con enlaces a documentacion.
Todos los endpoints /.well-known/ siguen el mismo patron: generacion force-static, CORS *, Cache-Control public max-age=3600 y X-Content-Type-Options nosniff. Estan disenados para ser consumidos por cualquier agente, desde cualquier origen, sin configuracion.
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 publico de API con metodos y parametros, todas las herramientas MCP con schemas de entrada/salida, matriz de soporte de protocolos con estado por protocolo, cambios recientes (novedades desde la ultima actualizacion) y un flujo de trabajo multi-tienda que los agentes pueden seguir paso a paso.
Lo que hace especial a llms.txt es la seccion INTEGRITY NOTICE: una defensa contra inyeccion 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 parametros, los agentes hacen preguntas en lenguaje natural y obtienen resultados rankeados y puntuados con objetos Schema.org Product. El pipeline tiene cuatro etapas: generacion de embedding vectorial, busqueda 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 generacion opcional de resumen para modos summarize/generate.
Tres superficies NLWeb
- 1NLWeb por tienda — POST /{storeSlug}/ask con { query, mode, limit }. Busca en el catalogo de un comerciante. Los resultados incluyen objetos Schema.org Product con puntuaciones.
- 2Auto-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.
- 3AgentFinder — 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 AgenticMCPStores hasta completar una compra. Tiempo total: menos de 2 segundos.
- 1Fase 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.
- 2Fase 2 — Seleccion de comerciante (100-300ms): POST /api/v1/agentfinder/search con la intencion del usuario. El agente obtiene comerciantes rankeados con trust scores y relevancia.
- 3Fase 3 — Busqueda de productos (200-800ms): POST /{slug}/ask con query en lenguaje natural. Busqueda vectorial + re-ranking LLM devuelve productos Schema.org puntuados.
- 4Fase 4 — Verificacion de confianza (50-150ms): POST /{slug}/mcp -> get_merchant_profile. El agente confirma que el trust score cumple el umbral para checkout autonomo.
- 5Fase 5 — Creacion de carrito (auth requerido): POST /{slug}/mcp -> create_cart. El agente cruza de solo-lectura a operaciones de escritura — OAuth requerido.
- 6Fase 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 autenticacion alguna. Un agente puede descubrir tiendas, buscar productos y evaluar confianza sin ninguna API key. La autenticacion 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
- 1Completa tu perfil de comerciante: los componentes de trust score incluyen completitud (info de negocio, contacto, politicas). Campos faltantes reducen tu puntuacion.
- 2Manten el inventario sincronizado: el tier de frescura afecta al ranking. Las tiendas con datos obsoletos se despriorizan.
- 3Define politicas claras: ventanas de devolucion, estimaciones de envio y metodos de pago son legibles por maquina. Los agentes que no pueden determinar tus politicas omitiran tu tienda.
- 4Obten verificacion QTSP: la verificacion eIDAS QUALIFIED aumenta el trust score +0.18 (vs +0.10 auto-declarado). Mayor confianza = mas trafico de agentes.
Pruebalo ahora
Puedes probar la cadena completa de descubrimiento contra nuestra plataforma en vivo ahora mismo. Empieza con GET agenticmcpstores.com/.well-known/nlweb.json para ver el contrato de descubrimiento NLWeb. Luego prueba POST agenticmcpstores.com/mcpwebstore-platform/ask con { "query": "que protocolos soportais?", "mode": "summarize" } — la plataforma respondera preguntas sobre si misma. Para busqueda de productos, prueba POST agenticmcpstores.com/demo-store/ask con { "query": "auriculares", "mode": "list" }. Todo esto funciona sin autenticacion.
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 confirmacion humana para una compra de 20 EUR de otro, y como los comerciantes pueden optimizar su perfil de confianza para aumentar el trafico 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 autenticacion. Todos los endpoints /.well-known/, llms.txt, busqueda NLWeb y herramientas MCP de solo lectura funcionan sin ninguna API key. La autenticacion 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?
AgenticMCPStores 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 'cuanto cuesta el plan Growth?' y obtener respuestas estructuradas. Esto elimina la necesidad de que los agentes parseen documentacion — pueden consultar la plataforma de la misma forma que consultan un catalogo de productos.
En que se diferencia NLWeb de la herramienta MCP search_products?
search_products es una llamada a herramienta estructurada con parametros especificos (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 intencion, expansion de sinonimos, similitud vectorial y re-ranking LLM. NLWeb tambien soporta conversaciones multi-turno via el parametro 'prev'. Usa search_products cuando sabes exactamente que parametros pasar; usa NLWeb cuando la consulta es abierta.
Cada cuanto se actualiza merchant-index.json?
El endpoint merchant-index.json usa Regeneracion Estatica Incremental (ISR) con una ventana de revalidacion de 5 minutos. Cuando un comerciante actualiza su perfil o catalogo, el cambio se propaga al indice 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 inyeccion de prompts. Algunas extensiones de navegador para recuperacion 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 AgenticMCPStores 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
Artículos relacionados
developer-guide
Building Agentic Commerce #1: Checkout Multi-Protocolo — MCP + x402 + ACP en un solo flujo
Un agente, tres protocolos, un checkout. Asi es como MCP, pagos stablecoin x402 y ACP trabajan juntos para que los agentes de IA compren productos, con ejemplos de codigo que puedes ejecutar hoy.
developer-guide
Building Agentic Commerce #3: Trust Scores — Cómo los Agentes Deciden a Quién Comprarle
Cuando un agente IA evalúa merchants, no lee reseñas ni reconoce logos. Lee trust scores — 12 señales verificables por máquina que determinan ranking de búsqueda, elegibilidad de checkout y fricción de pago. Así funciona el sistema.
trust-compliance
Por que la identidad de comerciante verificada con eIDAS lo cambia todo para el comercio con IA
Los agentes de IA necesitan mas que datos de productos para comprar: necesitan prueba criptografica de que los comerciantes son quienes dicen ser. Asi es como la verificacion eIDAS QTSP resuelve la brecha de confianza en el comercio agentico.