Aprender a redactar la especificación de un agente de IA en una sola página te obliga a tomar decisiones de diseño antes de llegar a producción, donde corregir sale mucho más caro. Este recurso es para quien diseña agentes de inteligencia artificial y necesita un documento claro que cualquier persona, o modelo generativo, pueda convertir en un prototipo funcional.

La idea central es simple y poderosa: si no puedes resumir el diseño de tu agente en una página, todavía no está claro. Escribirlo te fuerza a decidir, y lo que no se decide en papel se termina decidiendo después en producción a un costo mucho mayor [0:08].

Por qué especificar un agente en una sola página importa tanto

Una página bien escrita no es un trámite, es el punto donde todas tus decisiones de diseño se vuelven concretas. Cada línea deja de ser una intención general para convertirse en una decisión verificable.

Este documento lo leen cuatro audiencias distintas, y aquí viene lo interesante porque cada una busca algo diferente [0:28]:

• Quien construye el agente, que necesita saber exactamente qué hacer.
• Quien lo aprueba, que entiende qué se arriesga al usarlo.
• Quien lo audita, que sabe qué verificar.
• Un modelo de IA generativa como Claude, que lee la especificación y ayuda a construir el prototipo.

Por eso la instrucción tiene que ser nítida. Lo que no está dentro de la especificación, no queda construido en el prototipo [0:52].

¿Qué es la especificación de una página de un agente? Es un documento que reúne en una sola hoja todas las decisiones de diseño de un agente de IA: su propósito, usuarios, entradas, reglas, límites y criterios de éxito. Sirve para construir, aprobar y auditar el agente.

Qué 10 componentes debe tener la especificación de tu agente

Escribir la especificación no es empezar de cero, es juntar todas las decisiones que ya tomaste durante el proceso de diseño [2:40]. Estos son los diez componentes que ocupan las diez secciones del documento [1:12]:

1. El objetivo o propósito del agente.
2. El usuario y el disparador del flujo.
3. Las entradas que recibe.
4. Las instrucciones que sigue.
5. Las herramientas y permisos a los que accede.
6. La memoria para gestionar y almacenar conocimiento de razonamiento.
7. El criterio de parada.
8. Los criterios de éxito.
9. Las fallas posibles.
10. Las estrategias para mitigar esas fallas.

Recuerda la regla de oro: lo que queda fuera del documento queda fuera del alcance. Si algo no está escrito aquí, no se verá reflejado en el prototipo [2:28].

Cómo se ve la ficha del agente de reclamos en la práctica

Reuniendo todos los componentes, la ficha del agente de reclamos toma forma concreta [2:52]. Su propósito es resolver reclamos complejos y reembolsos sin que el cliente tenga que esperar a una persona.

El usuario son los clientes de la tienda, y el flujo se activa cuando un enrutador clasifica un mensaje como reclamo o reembolso [3:04]. Las entradas incluyen el mensaje, el número de pedido si lo trae, y la identidad del cliente que agrega el sistema.

En las instrucciones queda claro que actúa como asistente de posventa: responde solo con datos de sus herramientas, nunca promete un reembolso y escala cuando no puede resolver [3:24].

¿Qué es un criterio de parada en un agente de IA? Es la regla que define cuándo el agente debe detenerse. En el agente de reclamos: resuelve, escala si no puede, y se detiene a las seis vueltas para evitar bucles infinitos.

Para herramientas y permisos se definieron cuatro permisos de lectura, una herramienta que propone compensaciones con aprobación humana y otra que escala el caso [3:40]. La memoria guarda el historial de la tarea, mientras que lo que debe perdurar vive dentro del CRM, sin guardar nunca datos de pago ni de otros clientes [3:58].

Los criterios de éxito son ocho casos de prueba aprobados sin romper ninguna de las cuatro invariantes, y las fallas con sus mitigaciones ya se habían identificado en clases anteriores [4:16].

Por qué lo que el agente no hace es la sección más importante

Aquí está el detalle que muchos pasan por alto: la sección que define los límites del agente suele ser la más valiosa [4:34]. Documentar lo que el agente no hace evita que alguien agregue funciones después sin pasar por la misma decisión de diseño.

En el caso del agente de reclamos, el alcance excluido quedó así:

• No responde el estado del pedido, eso lo hace la automatización.
• No clasifica los correos variados, eso lo hace el enrutador.
• No resuelve cobros duplicados, eso es del equipo de pagos.
• No modifica ni cancela pedidos, eso es del equipo de posventa.

¿Por qué documentar lo que un agente no hace? Porque fija los límites por escrito. Así nadie amplía el alcance sin volver a tomar una decisión consciente, y evitas que el agente asuma tareas que pertenecen a otros equipos.

Con la ficha completa, el siguiente paso es dársela a Claude para convertirla en un prototipo sin escribir código, primero en Google Colab y luego en n8n [4:56]. ¿Ya tienes tu agente resumido en una sola página o todavía te falta decidir algo? Cuéntame en los comentarios qué sección te costó más cerrar.