Esta guía consolida la serie de tres artículos sobre el blueprint de agentes de comercio que Anthropic publicó el 2 de septiembre de 2026. Los artículos explican el porqué; la guía ordena el cómo. Si vienes sin contexto, léelos en este orden:
Esta guía está escrita para dos lectores a la vez: la persona que va a aprobar el proyecto y la persona que lo va a construir. Cada sección abre con la decisión que hay que tomar y sigue con el detalle técnico suficiente para tomarla bien. Sirve igual para un desarrollo propio que para evaluar la propuesta de un proveedor.
Fuente principal: el repositorio anthropics/commerce-agents (Apache 2.0) y el artículo técnico The anatomy of effective commerce agents. Todo lo que dice "el blueprint" viene de ahí. Todo lo que dice "recomendamos" es criterio de Saphia Labs, con más de veinte años en pagos y comercio electrónico en la región.
1. Antes de empezar: los prerrequisitos
La decisión: ¿el primer proyecto es el agente, o es arreglar los sistemas sobre los que va a correr?
El agente no trae buscador, catálogo, inventario ni carrito. Llama a los tuyos. Eso significa que la calidad del agente está acotada por la calidad de esos sistemas, y que un buscador mediocre produce un agente mediocre con muy buena redacción. Antes de escribir una línea del agente, pasa esta tabla con tu equipo:
| Sistema | Mínimo para un piloto | Cómo verificarlo |
|---|---|---|
| Buscador de catálogo | Devuelve resultados rankeados vía API, con filtros (precio, categoría, atributos) y sinónimos básicos. | Prueba 20 búsquedas reales de clientes (de tus logs). Si más de 3 no encuentran lo que existe, arregla el buscador primero. |
| Inventario | Disponibilidad por SKU y por ubicación, consultable en tiempo real o con retraso menor a minutos. | Compara la API contra el stock físico en 10 SKU de alta rotación. |
| Carrito y pedidos | API para crear, leer y modificar carritos y consultar pedidos, con identificadores estables. | Si el carrito solo existe en el front, no hay sobre qué construir. |
| Catálogo | Nombres, atributos y precios limpios y consistentes. Precio final con impuestos y comisiones calculable por API. | Muestra 30 productos al azar: si hay precios en texto libre o atributos vacíos, hay trabajo previo. |
| Identidad del cliente | Una forma de saber quién es el cliente en la sesión, y un canal con el que ya interactúa. | Sin identidad no hay memoria ni personalización. Sin canal no hay agente. |
Sobre el equipo: un piloto acotado (búsqueda y detalle de producto) lo lleva un equipo de dos o tres personas con experiencia en integración de APIs y una que entienda el negocio del catálogo. El plugin de Claude Code que acompaña el blueprint arma el esqueleto, agrega flujos y escribe evaluaciones; lo que no hace es conocer tu catálogo ni tus reglas de negocio.
Si no tienes equipo de ingeniería: esta guía te sirve igual, como lista de exigencias. Cada sección termina con lo que deberías pedirle a tu plataforma o proveedor. La sección 11 lo junta todo.
2. Arquitectura de referencia
La decisión: un solo agente con skills, o varios agentes especializados con un orquestador.
El blueprint es categórico: un solo modelo, en un ciclo estándar de razonar, usar una herramienta, mirar el resultado y repetir. Sin enrutador de intenciones, sin subagentes para búsqueda, carrito y soporte. Las capacidades que no se usan en toda conversación se cargan como skills (instrucciones adicionales) cuando hacen falta. Los subagentes quedan reservados para tareas estrechas que no necesitan el hilo de la conversación, como una investigación de mercado para el agente del comerciante.
La regla del 33%
Lo que se usa en más de un tercio de las conversaciones va en el prompt principal (búsqueda, carrito, checkout). Lo demás va en skills. La excepción que no se negocia: seguridad, restricciones legales y reglas de marca van siempre en el prompt principal, sin importar su frecuencia. Cada instrucción del prompt principal se paga en cada turno y compite por la atención del modelo, así que menos es más.
Cada componente visual es una herramienta
El agente no escribe una lista de productos en texto. Invoca una herramienta de "carrusel de productos" con identificadores y precios que vienen del backend. Si la única forma de mostrar un producto es a través de una herramienta que exige un identificador válido, el modelo no puede mostrar lo que no existe. Beneficio adicional: el historial queda estructurado y "el primero que me mostraste" se resuelve sin ambigüedad. En WhatsApp, donde no hay carrusel, la herramienta devuelve un bloque de texto e imágenes con el mismo formato estricto.
Herramientas que explican, no que fallan
Las herramientas devuelven solo los campos que el modelo necesita para razonar, y cuando algo falla lo dicen en lenguaje claro. "No hay stock en Bogotá, pero sí en Chía con entrega en 2 días" es un resultado con el que el agente puede hacer algo. "Error 409" no.
Qué exigir a un proveedor: el diagrama de su propuesta. Más de tres cajas con la palabra "agente" es una arquitectura que va a costar el doble y responder más lento. Y la respuesta a "¿cómo evitan que invente precios?" tiene que ser "no puede: los precios solo entran por herramienta", no "se lo decimos en el prompt".
3. Fases de implementación
La decisión: cuánto encender en el primer lanzamiento.
El consejo del blueprint es más conservador de lo que el instinto pide: empezar con búsqueda y detalle de producto, con todo lo demás apagado por configuración. Cada capacidad apagada es una herramienta menos que el modelo puede usar mal, un flujo menos que evaluar y una superficie de ataque menos que defender. Se enciende la siguiente cuando la anterior cumple su criterio de salida.
Dos notas sobre el orden. Primera: memoria va después de carrito y pago, no antes, porque la memoria introduce datos personales y obligaciones legales que conviene resolver con un agente que ya demostró que funciona. Segunda: el agente del comerciante puede correr en paralelo desde la fase 1 si el equipo lo permite, porque su superficie de riesgo es distinta (no toca al cliente final) y su valor de análisis es inmediato.
4. El harness de seguridad
La decisión: dónde viven las reglas de seguridad: en el prompt o en el código.
En pagos hay una regla que todos aprendemos: el sistema que mueve el dinero nunca confía en quien le pide moverlo. Verifica en el punto donde ya no hay nadie más que verifique. El blueprint aplica exactamente eso: todas las reglas se hacen cumplir dentro de la llamada a cada herramienta, no en las instrucciones al modelo. Si el modelo se equivoca o alguien lo manipula, no puede hacer daño porque el camino no existe.
Las cuatro reglas, tal como deben implementarse:
- Nada mueve dinero sin aprobación humana. La herramienta de checkout produce un resumen y un botón. Del lado del comerciante, un cambio de precio o inventario se prepara en un estado intermedio con identificador del servidor y solo se aplica cuando una persona lo aprueba desde el portal, con registro de quién y cuándo.
- Solo se aceptan identificadores emitidos por el servidor. El harness registra cada producto, pedido y cliente que devolvió en la sesión. Un identificador que no apareció en una respuesta previa se rechaza. Esto cierra a la vez el producto inventado y el identificador ajeno colado en la conversación.
- Los límites se validan sobre el resultado, no sobre el pedido. "Máximo dos unidades por cliente" se verifica sobre el carrito después de aplicar el cambio. La diferencia entre validar el pedido y validar el estado final es exactamente la que explotan la mayoría de los fraudes de cantidad.
- Todo contenido de terceros va cercado y sanitizado, con la instrucción de reportar y no obedecer.
Qué exigir a un proveedor: tres demostraciones en vivo. Que el modelo intente cobrar sin botón. Que intente agregar un producto que no apareció en una búsqueda. Que una reseña contenga instrucciones. Si alguna se responde con "el modelo está entrenado para no hacer eso", no hay seguridad. Hay confianza.
5. Memoria del cliente y datos personales
La decisión: qué se recuerda del cliente, por cuánto tiempo, y quién responde por ello.
Un agente que recuerda la talla, la tienda de siempre y que el cliente prefiere entrega en oficina es mucho más útil. También acumula datos personales. El blueprint resuelve bien la parte técnica y deja la legal, correctamente, en manos de cada empresa. En la región, la parte legal no es una buena práctica: es una obligación desde el primer día.
| País | Marco legal | Lo que implica para la memoria del agente |
|---|---|---|
| Colombia | Ley 1581 de 2012 | Autorización previa e informada, finalidad declarada, derecho a conocer, actualizar y suprimir. |
| Brasil | LGPD | Base legal por tratamiento, minimización, derechos de acceso y eliminación, encargado (DPO). |
| México | LFPDPPP | Aviso de privacidad, derechos ARCO, consentimiento para finalidades secundarias. |
| Argentina | Ley 25.326 | Consentimiento, registro de bases de datos, derechos de acceso, rectificación y supresión. |
Recomendamos que Legal esté en la mesa cuando se diseña la memoria, no cuando se lanza. Agregar "el cliente puede borrar sus datos" antes de construir cuesta una tarde. Agregarlo después cuesta un rediseño. Y la memoria debe poder apagarse por despliegue con un interruptor, sin tocar código: es la forma más barata de cumplir una orden de un regulador o de responder a un incidente.
6. Evaluaciones: el control de calidad
La decisión: cuántos casos, quién los escribe y cuándo corren.
En manufactura nadie discute el control de calidad. En agentes de IA la conversación suele ser "¿podemos lanzar sin eso?". El blueprint dice que no, y da la receta más accionable de todo el documento.
Tres principios para escribir los casos:
- Evaluar en condiciones difíciles. Un caso que arranca de cero no encuentra el error que aparece cuando el cliente ya tiene tres cosas en el carrito, cambió de opinión dos veces y la memoria dice una cosa y la conversación otra.
- Por cada "debe hacer", un "debe rechazar". Si hay un caso que aplica el cupón válido, hay uno que rechaza el vencido. Si uno muestra el precio de la cuenta corporativa, otro verifica que no muestra el de otra cuenta.
- Los escriben quienes saben: Producto, Legal, Operaciones y Servicio al Cliente, cada uno los de su área. Ingeniería los automatiza.
| Tipo de caso | Ejemplo positivo | Ejemplo negativo |
|---|---|---|
| Pedidos básicos | "Carpa para dos por menos de 250" devuelve resultados que cumplen ambas restricciones. | Pregunta de precio: el precio mostrado se traza al dato del backend, no a texto libre. |
| Dependientes del contexto | "El segundo que me mostraste" resuelve al identificador correcto. | Agregar sobre un carrito existente no duplica ni borra lo que ya había. |
| Seguridad | Una reseña con instrucciones se reporta como contenido raro. | Intento de leer datos de otro usuario: rechazado por la herramienta. |
| Marca y regulación | Lenguaje regulado sale exactamente como lo aprobó Legal. | No se ofrece un producto restringido a quien no califica. |
| Interfaz | Se invoca el componente correcto (comparador, no carrusel). | No se filtran identificadores internos en la respuesta. |
| Dos capacidades a la vez | Cambiar dirección del pedido anterior y seguir buscando regalo en el mismo turno. | La skill de devoluciones no pisa el carrito activo. |
Punto de partida: 50 a 100 casos por flujo de usuario, con un responsable por área. Si la propuesta que evalúas no tiene un número de casos ni un dueño por área, no tiene control de calidad. Tiene demos.
7. Latencia y costo
La decisión: qué modelo, y cómo se estructura el prompt para que la factura cierre.
Las dos objeciones que matan pilotos son "es lento" y "es caro". Ambas se resuelven con diseño, no con negociación de precios.
| Palanca | Qué se hace | Efecto |
|---|---|---|
| Menos vueltas | Cargar de entrada el contexto probable (el producto desde el que se abrió el chat), llamar herramientas independientes en paralelo. | La latencia es sobre todo cuántas idas y vueltas hay entre razonar y consultar. Menos vueltas, menos espera. |
| Modelo elegido con evals | Comparar dos o tres modelos con tu batería de casos y tu tráfico, no por nombre ni por precio de lista. | Hallazgo contraintuitivo: a veces el modelo más capaz es más rápido porque planea mejor y da menos vueltas, sobre todo en los casos lentos. |
| Mostrar el trabajo | "Buscando hoteles en Cartagena", "comparando precios", en vez de un spinner. | La misma espera se percibe como progreso. |
| Caché de prompt en tres capas | Global (instrucciones, skills) · sesión (cliente, memoria) · volátil (el turno). Lo estable primero. | Entre 90% y 99% de lo que el modelo lee por turno viene de caché, a una fracción del precio. Es la diferencia de un orden de magnitud en la factura. |
Punto de partida del blueprint: el modelo más capaz para el agente del comerciante, donde pesa el análisis, y uno más rápido para el agente de compras, donde cada segundo cuenta. La recomendación explícita es medir con tu tráfico, no copiar la de ellos. Y como la arquitectura no depende del modelo, cambiarlo cuando salga uno mejor es un ajuste de configuración y una corrida de evaluaciones.
Qué exigir a un proveedor: una estimación de costo por conversación y qué porcentaje viene de caché. Si nadie sabe, la estimación está mal por un orden de magnitud.
8. Operar como producto, no como proyecto
La decisión: quién es dueño de qué cuando cinco equipos quieren cambiarle cosas al agente.
Lo que hace que esto funcione en la práctica es el interruptor. Si la skill de campañas empieza a hacer algo raro, se apaga desde un panel y el resto del agente sigue funcionando. Es el mismo principio que un circuit breaker en pagos: el sistema degrada una capacidad, no se cae entero.
9. Lo que el blueprint no resuelve para América Latina
La decisión: cuánto trabajo de adaptación presupuestar además del blueprint.
El blueprint asume tarjeta como medio de pago, inglés como idioma, interfaz web y regulación estadounidense. Tres cosas que en la región son distintas y que ninguna implementación puede ignorar.
| Diferencia | Qué cambia | Qué hay que construir |
|---|---|---|
| Medios de pago | Pix en Brasil, PSE y Nequi en Colombia, efectivo en OXXO en México, cuotas sin interés en toda la región. | Herramientas de checkout por medio de pago local. Y tratar "¿cuánto queda en cuotas?" como pregunta de producto: el agente debe poder responderla desde la búsqueda, no solo al pagar. |
| Canal | Una parte enorme del comercio conversacional ocurre en WhatsApp: texto e imágenes, sin carruseles ni mapas de asientos. | Las mismas herramientas de UI con una representación de texto e imagen. Es el problema de diseño más importante para una pyme de la región. |
| Datos personales | Ley 1581, LGPD, LFPDPPP, Ley 25.326 (ver sección 5). | Consentimiento, retención, derechos de acceso y borrado, desde el día uno y no como mejora posterior. |
| Idioma y catálogo | "Tenis" y "zapatillas deportivas" son lo mismo según el país; los precios se leen distinto en cada moneda. | Sinónimos regionales en el buscador (para todos, no solo para el agente) y formato de precio por país en las herramientas. |
Recomendación: pide que cualquier demo, propia o de proveedor, corra con tu catálogo real, tus medios de pago reales y en tu canal real. Un agente que funciona perfecto con la tienda de ejemplo y tarjeta de crédito no te dice nada sobre cómo va a funcionar con tu inventario, con Pix y por WhatsApp.
10. Checklist "listo para producción"
Lo que pediríamos ver, con evidencia, antes de aprobar el lanzamiento. Sirve igual para desarrollo propio que para un proveedor. Cada punto se demuestra, no se describe.
- El backend del agente no tiene método de cobro.El checkout termina en un botón que aprieta el cliente. Demostrado en vivo.
- Los cambios del comerciante pasan por aprobación humana.Estado intermedio con identificador del servidor y registro de quién aprobó qué.
- Las herramientas rechazan identificadores que no emitió el servidor en la sesión.Probado con un intento de inyección.
- Los límites por cliente se validan sobre el estado final.No sobre el pedido actual.
- Todo contenido de terceros pasa por sanitizador y va cercado.Probado con una reseña que contiene instrucciones.
- Los precios y productos solo entran por herramienta.El modelo no puede escribir un precio en texto libre.
- La memoria tiene política de retención, el cliente puede ver y borrar sus datos, y hay interruptor.Revisado por Legal contra la ley del país.
- Existen al menos 50 casos de evaluación por flujo, con negativos y un responsable por área.Corren en cada cambio; la suite completa, cada noche.
- Hay estimación de costo por conversación con porcentaje de caché.Y el modelo se eligió con evaluaciones, no por nombre.
- Hay plan de rollout gradual y un interruptor por skill.Que Operaciones puede accionar sin ingeniería.
- La demo corrió con catálogo, medios de pago y canal reales.No con la tienda de ejemplo.
11. Cómo leer una propuesta sin ser ingeniero
Si no vas a construir, vas a comprar, y la propuesta va a llegar. Cinco señales de alerta que se detectan sin leer una línea de código:
- Muchos agentes en el diagrama. Más de tres cajas con la palabra "agente" es una arquitectura que va a costar el doble y responder más lento. Pregunta por qué no es una sola.
- "Vamos a construir nuestro propio buscador o catálogo para el agente". Es un proyecto de plataforma disfrazado de proyecto de IA. Si el buscador actual es malo, arréglalo para todos.
- El agente "escribe" los productos que muestra. Si la respuesta a "¿cómo evitan que invente precios?" es "se lo decimos en el prompt", no hay diseño de seguridad. Hay esperanza.
- No hay plan de caché ni estimación de costo por conversación. La cifra que te den está mal por un orden de magnitud.
- Eligieron el modelo por nombre. "El mejor" o "el más barato" sin una evaluación con tus casos reales es una decisión sin datos.
Y tres preguntas para el comité, antes de la primera línea de código o del primer contrato: ¿qué tan buenos son mis sistemas de base? ¿Construyo, compro o espero, y por qué? ¿Quién es dueño de la seguridad y de los datos?
Cierre
Nada de esta guía es exótico para quien viene de pagos, de banca o de cualquier industria regulada. Separación de funciones, aprobación de cambios, validación en el punto de ejecución, control de calidad antes de liberar. Lo nuevo es aplicarlo a un sistema que habla y que se equivoca de maneras que un sistema tradicional no se equivocaba. Anthropic mostró, con código, que se puede hacer sin sacrificar la experiencia. La seguridad no le quita utilidad al agente. Le da permiso para existir.
¿Vas a implementar o a evaluar un agente de comercio?
Podemos revisar tu propuesta contra este checklist, o acompañar a tu equipo en el diseño del piloto. Una llamada de 30 minutos para saber por dónde empezar.
Agendar llamada gratuita
