Saltar al contenido
TrusteedControl y pruebas para operaciones delegadas
ESEN
Solicitar un piloto
Volver al blog
Guías para desarrolladores11 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. Así 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'. Guía para desarrolladores sobre la cadena completa de descubrimiento de agentes: búsqueda semántica NLWeb, llms.txt, agent-card.json, 10+ endpoints legibles por máquinas y el AgentFinder de búsqueda multi-comerciante, todo sin configuración previa.

Publicado

2026-04-05

Actualizado: 2026-09-13

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, que es el árbitro cuando un artículo y una superficie de estado se contradicen.

Sobre Trusteed

Categoría

Guías para desarrolladores

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

Hay una pregunta que la mayoría de plataformas ecommerce aún no ha respondido: ¿cómo encuentra un agente de IA tu tienda? No a través de Google ni de un marcador. Un agente necesita endpoints de descubrimiento legibles por máquina que le digan qué vendes, cómo buscar en tu catálogo y qué protocolos soportas, todo antes de crear una cuenta u obtener una API key. Este artículo recorre la cadena de descubrimiento de Trusteed, desde un inicio en frío 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 cubrió el checkout multi-protocolo (MCP + x402 + ACP). La Parte 3 cubrirá trust scores: el sistema que determina cuanta autonomía tienen los agentes.

Idea clave

El problema del descubrimiento: los agentes no navegan

Los humanos descubren tiendas a través 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 máquina: que productos están disponibles, que protocolos de pago se soportan, que nivel de confianza tiene el comerciante y como interactuar programaticamente. Sin descubrimiento estandarizado, 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 máquina. Endpoints /.well-known/ que dicen a los agentes qué está 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: búsqueda semántica NLWeb. Búsqueda 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 máquina bajo la ruta /.well-known/. Siguen las convenciones RFC 8615 y están 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: Interpretación de trust scores: que significa EXCELLENT (0.9-1.0) vs CAUTION (0.5-0.7), taxonomía 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. Están diseñados para ser consumidos por cualquier agente, desde cualquier origen, sin configuración.

Idea clave

Capa 2: llms.txt, documentación para máquinas

El endpoint /llms.txt sirve un archivo de texto de ~1.500 líneas que describe toda la plataforma en un formato optimizado para consumo LLM. Se sirve en /llms.txt (estático, 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 través de una extensión de navegador que añade '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 señales de bloqueo de agentes al contenido recuperado.

Capa 3: NLWeb. 'Encuéntrame 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

Aquí 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 qué tiendas existen y qué protocolos están 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 (búsqueda de productos, 200-800ms): POST /{slug}/ask con query en lenguaje natural. Búsqueda vectorial + re-ranking LLM devuelve productos Schema.org puntuados.
  • 4
    Fase 4 (verificación 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 (creación 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.

Las fases 1 a 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 mucho 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 puntuación.
  • 2
    Mantén el inventario sincronizado: el tier de frescura afecta al ranking. Las tiendas con datos obsoletos se despriorizan.
  • 3
    Define políticas claras: ventanas de devolución, estimaciones de envío y métodos de pago son legibles por máquina. Los agentes que no pueden determinar tus políticas omitirán tu tienda.
  • 4
    Trust Score v4.1 combina tres dimensiones ponderadas, un bonus opcional de aseguramiento externo y topes según confianza. Cada respuesta identifica el motor utilizado; algunas recurren a v2. El desglose legacy por componentes no explica una puntuación global producida por v4.1.

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

Trust Score v4.1 combina tres dimensiones ponderadas, un bonus opcional de aseguramiento externo y topes según confianza. Cada respuesta identifica el motor utilizado; algunas recurren a v2. El desglose legacy por componentes no explica una puntuación global producida por v4.1.

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, la búsqueda NLWeb y las herramientas MCP de descubrimiento (search_products, get_product_details, browse_categories, get_merchant_profile) funcionan sin ninguna API key. El endpoint de checkout pide clave en todas sus herramientas (create_cart, get_shipping_rates, select_shipping_option, apply_discount, preview_checkout, complete_checkout), create_cart incluida, y todas las tools de checkout que gastan o liquidan piden además la cabecera X-Payment-Mandate; el resto de herramientas de checkout (create_cart y attach_agent_identity y verify_age_over_n y verify_residence_country y verify_legal_person_authorization y apply_discount y get_shipping_rates y select_shipping_option y create_payment_mandate y update_payment_mandate y cancel_payment_mandate y ucp_create_checkout y ucp_update_checkout y ucp_add_items_to_checkout y ucp_get_checkout y ucp_cancel_checkout y get_checkout_state y quote_checkout y get_trust_receipt y verify_trust_receipt) no la necesitan (Fases 5-6).

¿Qué 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 qué 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 sinónimos, 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 cuánto se actualiza merchant-index.json?

El endpoint merchant-index.json usa Regeneración Estática 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, así que los cambios de puntuación tardan un poco más en reflejarse.

¿Qué es el aviso de integridad de llms.txt y por qué 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 máquinas | Building Agentic Commerce | Trusteed