Skip to content
Volver al blog
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

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 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

Artículos relacionados

Como los agentes IA descubren tiendas: NLWeb, llms.txt y descubrimiento legible por maquinas | Building Agentic Commerce | Trusteed