Convertir una especificación en un documento de arquitectura es el primer paso real para construir un agente de inteligencia artificial. Aquí aprenderás cómo usar Claude para traducir ese documento de una página en instrucciones técnicas que una máquina entiende, y por qué esto importa si estás diseñando un prototipo sin tocar sistemas reales.

Qué diferencia hay entre la especificación y la arquitectura

Estos dos documentos cumplen funciones distintas y conviene ponerlos lado a lado para entenderlo [00:28].

La especificación está escrita para las personas. Dice el propósito del agente, las reglas, los permisos y lo que queda fuera del alcance. La arquitectura, en cambio, está escrita para construir: describe cada herramienta como una función con sus entradas y salidas, define los datos de prueba, los controles en el código y las pruebas que se van a ejecutar.

¿Qué es un documento de arquitectura de un agente de IA? Es la versión técnica de la especificación. Describe cada herramienta como función con nombre, entradas, salidas y permisos, además de los datos simulados, los controles y los casos de prueba listos para ejecutar.

Y aquí viene lo interesante: no tienes que escribirla tú. Claude la escribe a partir de la especificación mediante un buen prompt, y tu trabajo es revisarla [00:48].

Qué cinco cosas agrega la arquitectura a la especificación

El salto de un documento al otro suma información concreta que permite pasar del concepto al prototipo [01:07].

• Cada herramienta descrita como una función con nombre, entradas y salidas.
• Los datos simulados de los sistemas de la tienda para probar sin tocar nada real.
• El modelo de lenguaje y el tope de vueltas del agente.
• Los controles que van en el código, como validar números de pedido, fijar la identidad del cliente y dejar las compensaciones pendientes de aprobación.
• Los ocho casos de prueba escritos para que se puedan ejecutar.

Así se ve una herramienta dentro de la arquitectura: es la misma tarjeta que diseñaste para consultar el envío, pero escrita para que una máquina la entienda. Tiene un nombre exacto, una descripción con el momento de uso, qué recibe y de qué tipo, qué devuelve y qué permiso tiene [01:46].

Por qué usar datos simulados en el prototipo

Un detalle clave es que la función de consulta no habla con la transportadora real, sino que devuelve datos simulados. Así puedes probar el agente completo sin tocar ningún sistema de la tienda [02:09].

¿Por qué usar datos ficticios al construir un agente? Porque permiten probar todos los casos sin conectarse a sistemas reales. Los datos cubren escenarios concretos, como pedidos retenidos o clientes con reclamos previos, para validar el comportamiento del agente de forma segura.

La arquitectura define estos datos para que cubran los ocho casos de prueba [02:27]:

• Cuatro pedidos: un juego de olla retenido en aduana, un microondas entregado, información de otro cliente y el 9999, que no existe.
• Dos clientes: el C102, cliente de la sesión con un reclamo anterior, y el C311, el vecino, que no se puede consultar.
• Tres políticas: cambio o reembolso hasta 30 días por daño, cupón del 10 % de descuento si hay siete días de demora, y escalar a posventa en otros casos.

Cómo estructurar el prompt que le das a Claude

El prompt que convierte la especificación en arquitectura tiene cinco partes bien definidas [03:36].

1. El rol: le pides que actúe como arquitecto de soluciones de inteligencia artificial.
2. El contexto: adjuntas la especificación del agente de la clase anterior.
3. La tarea: convertir ese documento en una arquitectura con siete secciones.
4. Las restricciones: todo con datos simulados, nada externo, pensando en un prototipo en Python sobre Google Colab y sin escribir código todavía.
5. El formato: Markdown con los nombres de las funciones dentro de la especificación.

En la práctica, cargas el prompt junto con el documento de especificación. Claude lo lee y empieza a armar la arquitectura: el modelo, el tope, cada herramienta como función, los datos simulados, los controles y los casos de prueba [04:35]. El motor de razonamiento del agente será uno de los modelos de Anthropic a través de su API [04:21].

Qué contiene el documento que genera Claude

El resultado incluye el modelo y cómo se condiciona el bucle, junto con el ciclo de decisión, ejecución y observación [05:04].

También define el tope de vueltas, que en este caso es de seis, cada herramienta escrita como función sobre código, la muestra de datos simulados, los controles del agente, los casos de prueba (normales, de límite y adversarios) y lo que queda fuera del alcance [05:21].

Qué revisar antes de usar la arquitectura

Claude escribe rápido, pero la responsabilidad del diseño sigue siendo tuya. Antes de avanzar, revisa cinco puntos [05:46]:

• ¿Están las seis herramientas, cada una con lo que recibe y devuelve?
• ¿La herramienta de compensación deja la propuesta pendiente, sin ejecutarla?
• ¿Los datos simulados alcanzan para los ocho casos de prueba?
• ¿El tope es de seis vueltas y la identidad la pone el sistema?
• ¿Respeta el fuera de alcance?

Si algo falla, no lo corrijas a mano. Pídele a Claude que lo ajuste diciéndole exactamente qué no cumple la especificación [06:17].

Con la arquitectura ya revisada, Claude puede escribir el código del agente. En la siguiente clase lo harás en Google Colab, viendo la implementación bloque por bloque y corriendo los ocho casos de prueba [06:24]. ¿Qué parte de tu propia especificación crees que necesitaría más detalle antes de pasarla a arquitectura? Cuéntamelo en los comentarios.