DEV Community

Cover image for De bloquear a autocorregir: una demo práctica de guardrails para agentes de IA con Laravel, Grok y OpenSpec
Francisco
Francisco

Posted on

De bloquear a autocorregir: una demo práctica de guardrails para agentes de IA con Laravel, Grok y OpenSpec

#laravel #ai #openspec #guardrails

Introducción

Hace poco estuve leyendo el artículo “Guardrails para Agentes de IA que se Autocorrigen en Lugar de Bloquear”, publicado por Elizabeth Fuentes L para AWS Español.

La idea principal me pareció muy interesante: muchos guardrails tradicionales funcionan de forma binaria. Si el agente viola una regla, se bloquea la acción y el usuario tiene que intervenir. Eso es necesario en algunos casos, pero no siempre es la mejor experiencia.

El artículo plantea una alternativa: en vez de solo bloquear, podemos guiar al agente para que corrija su acción. A ese enfoque se le llama steer. El agente recibe una corrección, ajusta los parámetros y continúa el flujo.

Artículo original:

https://dev.to/aws-espanol/guardrails-para-agentes-de-ia-que-se-autocorrigen-en-lugar-de-bloquear-3n32

Quise llevar esa idea a una demo práctica usando tecnologías que manejo más en mi día a día:

Laravel
Laravel AI SDK
Vue
Docker Compose
MySQL
Grok / xAI
OpenSpec
Enter fullscreen mode Exit fullscreen mode

Importante: esta demo no implementa directamente Strands Agents ni Agent Control. Lo que hice fue tomar el patrón conceptual del artículo y llevarlo a un stack Laravel + Vue + Laravel AI SDK + Grok.

En lugar de usar Guide() para que el LLM reintente, implementé un GuardrailEngine que corrige el payload de forma determinística y devuelve una propuesta corregida al usuario.

El objetivo fue aprender el patrón, bajarlo a código y demostrar la idea central:

No bloquear por defecto.
Corregir cuando sea seguro.
Bloquear cuando realmente sea necesario.
Enter fullscreen mode Exit fullscreen mode

El problema

Imaginemos un agente de IA para agendar citas.

Un usuario escribe:

Quiero una cita mañana a las 8pm para 3 personas
Enter fullscreen mode Exit fullscreen mode

Pero el negocio tiene estas reglas:

Horario de atención: 8:00 a.m. a 6:00 p.m.
Máximo de personas por cita: 2
Duración de la cita: 30 minutos
No se pueden agendar días bloqueados
No se pueden duplicar slots ocupados
Enter fullscreen mode Exit fullscreen mode

Un guardrail tradicional podría responder:

No puedo agendar esa cita.
Enter fullscreen mode Exit fullscreen mode

Eso funciona, pero corta el flujo.

Una mejor experiencia sería:

No puedo agendar a las 8:00 p.m. ni para 3 personas.
Te puedo ofrecer mañana a las 5:30 p.m. para 2 personas.
¿Deseas confirmar?
Enter fullscreen mode Exit fullscreen mode

Ahí es donde entra la idea de autocorrección.

Qué construí

Construí una demo funcional donde un usuario puede pedir una cita por chat.

La IA interpreta la intención, genera un payload estructurado y luego el GuardrailEngine valida las reglas del negocio.

El usuario no confirma directamente lo que la IA propone. Primero pasa por una capa de control.

También agregué un frontadmin para configurar reglas, servicios, días bloqueados y revisar logs.

En simple:

La IA entiende.
El guardrail decide.
El backend ejecuta.
El admin configura.
Enter fullscreen mode Exit fullscreen mode

Arquitectura de la demo

La demo está compuesta por:

Frontend Cliente
Backend Laravel
Laravel AI SDK
AppointmentIntentAgent
LaravelAiAppointmentAgent
GuardrailEngine
AppointmentController
Frontadmin
MySQL
Enter fullscreen mode Exit fullscreen mode

Arquitectura de la demo

Responsabilidades por componente

Componente Responsabilidad
Frontend Cliente Permite al usuario escribir la solicitud y confirmar la cita propuesta.
Frontadmin Permite configurar reglas, servicios, días bloqueados y revisar logs.
ChatController Recibe el mensaje del usuario y coordina el flujo del agente.
LaravelAiAppointmentAgent Servicio wrapper que invoca el agente creado con Laravel AI SDK.
AppointmentIntentAgent Agente estructurado que convierte lenguaje natural en un payload de cita.
GuardrailEngine Evalúa reglas y decide ALLOW, STEER o BLOCK.
AppointmentController Crea la cita solo después de confirmación y validación.
Admin Controllers Exponen endpoints para reglas, servicios, días bloqueados y logs.
MySQL Guarda citas, reglas, servicios, días bloqueados, conversaciones del SDK y auditoría.

Flujo principal 

Usuario escribe una solicitud
        ↓
Frontend envía el mensaje al backend
        ↓
ChatController recibe el mensaje
        ↓
LaravelAiAppointmentAgent invoca AppointmentIntentAgent
        ↓
Laravel AI SDK usa xAI / Grok como provider
        ↓
El agente devuelve un payload estructurado
        ↓
GuardrailEngine evalúa reglas de negocio
        ↓
Si es válido: ALLOW
Si es corregible: STEER
Si no puede continuar: BLOCK
        ↓
El usuario confirma la propuesta
        ↓
Laravel crea la cita en MySQL
Enter fullscreen mode Exit fullscreen mode

Flujo de administración 

Frontadmin
        ↓
Admin Controllers
        ↓
MySQL
        ↓
Reglas, servicios, días bloqueados y logs
        ↓
GuardrailEngine usa esas reglas en runtime
Enter fullscreen mode Exit fullscreen mode

La parte importante es que las reglas no viven solamente en el prompt del agente. Se pueden cambiar desde el frontadmin y el GuardrailEngine las usa en tiempo de ejecución.

Implementación con Laravel AI SDK

Inicialmente tenía una integración directa con la API de xAI / Grok usando HTTP.

Luego migré la extracción de intención a Laravel AI SDK, para trabajar con un agente más alineado al ecosistema Laravel.

La documentación oficial indica que el SDK se instala así:

composer require laravel/ai
Enter fullscreen mode Exit fullscreen mode

Luego se publican archivos de configuración, stubs y migraciones:

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
Enter fullscreen mode Exit fullscreen mode

Y se ejecutan las migraciones:

php artisan migrate
Enter fullscreen mode Exit fullscreen mode

En mi caso, esto creó la tabla usada por el SDK para conversaciones de agentes:

agent_conversations
Enter fullscreen mode Exit fullscreen mode

Después generé un agente estructurado:

php artisan make:agent AppointmentIntentAgent --structured
Enter fullscreen mode Exit fullscreen mode

El objetivo de este agente es claro: extraer intención, no validar reglas de negocio.

Ejemplo conceptual:

$response = (new AppointmentIntentAgent)->prompt(
    'Quiero una cita mañana a las 8pm para 3 personas'
);
Enter fullscreen mode Exit fullscreen mode

La respuesta esperada es un payload estructurado:

[
    "service" => "consulta_general",
    "date" => "2026-05-03",
    "time" => "20:00",
    "people" => 3,
]
Enter fullscreen mode Exit fullscreen mode

Para mantener el controller limpio, creé un servicio wrapper:

class LaravelAiAppointmentAgent
{
    public function extractPayload(string $message): array
    {
        $response = (new AppointmentIntentAgent)->prompt($message);

        return [
            'service' => $response['service'] ?? 'consulta_general',
            'date' => $response['date'] ?? null,
            'time' => $response['time'] ?? null,
            'people' => (int) ($response['people'] ?? 1),
        ];
    }
}
Enter fullscreen mode Exit fullscreen mode

Así el flujo queda más ordenado:

ChatController
        ↓
LaravelAiAppointmentAgent
        ↓
AppointmentIntentAgent
        ↓
Laravel AI SDK
        ↓
xAI / Grok
        ↓
Payload estructurado
        ↓
GuardrailEngine
Enter fullscreen mode Exit fullscreen mode

La IA no decide si la cita es válida. Solo transforma lenguaje natural en datos estructurados.

La validación queda en el GuardrailEngine.

Decisiones del guardrail

Implementé tres decisiones principales:

ALLOW

La acción es válida y puede continuar.

STEER

La acción tiene errores corregibles. El sistema ajusta los datos y devuelve una propuesta corregida.

BLOCK

La acción no puede continuar porque falta información o hay una regla estricta.

Ejemplo de STEER

Entrada del usuario:

Quiero una cita mañana a las 8pm para 3 personas
Enter fullscreen mode Exit fullscreen mode

El agente estructurado con Laravel AI SDK genera:

{
  "service": "consulta_general",
  "date": "2026-05-03",
  "time": "20:00",
  "people": 3
}
Enter fullscreen mode Exit fullscreen mode

El guardrail evalúa:

20:00 está fuera del horario permitido
3 personas supera el máximo permitido
Enter fullscreen mode Exit fullscreen mode

Respuesta del guardrail:

{
  "decision": "STEER",
  "reason": "Payload was corrected.",
  "corrections": [
    {
      "field": "time",
      "from": "20:00",
      "to": "17:30:00",
      "reason": "Requested time is after business hours."
    },
    {
      "field": "people",
      "from": 3,
      "to": 2,
      "reason": "Requested people count exceeds maximum allowed."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Respuesta para el usuario:

La hora solicitada no cumple las reglas. Te puedo ofrecer 17:30.
El máximo permitido es 2 persona(s).
¿Deseas confirmar esta propuesta?
Enter fullscreen mode Exit fullscreen mode

Ese es el punto clave: el sistema no bloquea de inmediato, sino que corrige cuando es seguro hacerlo.

Ejemplo de BLOCK

No todo debe autocorregirse.

Si el usuario no proporciona fecha, el sistema no debe inventarla si la intención no está clara.

Payload incompleto:

{
  "service": "consulta_general",
  "time": "10:00",
  "people": 1
}
Enter fullscreen mode Exit fullscreen mode

Respuesta:

{
  "decision": "BLOCK",
  "reason": "Date is required."
}
Enter fullscreen mode Exit fullscreen mode

Mensaje:

Necesito que me indiques la fecha para revisar disponibilidad.
Enter fullscreen mode Exit fullscreen mode

Este punto también es importante: STEER no reemplaza BLOCK. Los dos se complementan.

El artículo original también lo explica así: los bloqueos son útiles para reglas estrictas, mientras que steer funciona mejor para errores corregibles como ajustar parámetros, redactar información sensible o corregir formatos.

Reglas configurables desde el frontadmin

Una parte que quise destacar fue que las reglas no estuvieran dentro del prompt.

Desde el frontadmin se pueden cambiar:

Hora inicio
Hora fin
Máximo de personas
Duración de cita
Permitir autocorrección
Servicios activos
Días bloqueados
Enter fullscreen mode Exit fullscreen mode

Por ejemplo, si el admin cambia:

Hora fin: 17:00
Máximo personas: 1
Enter fullscreen mode Exit fullscreen mode

El mismo mensaje:

Quiero una cita mañana a las 8pm para 3 personas
Enter fullscreen mode Exit fullscreen mode

ahora se corrige a algo como:

16:30
1 persona
Enter fullscreen mode Exit fullscreen mode

Esto demuestra una idea muy importante: las reglas del negocio pueden cambiar sin tocar el prompt del agente.

¿Dónde entra Grok?

Grok entra como proveedor del modelo usado por Laravel AI SDK.

Antes lo estaba llamando directamente por HTTP. Ahora el flujo pasa por un agente estructurado:

Laravel AI SDK
        ↓
AppointmentIntentAgent
        ↓
xAI / Grok
Enter fullscreen mode Exit fullscreen mode

Su trabajo es convertir lenguaje natural en un payload estructurado.

Usuario:

Quiero una cita mañana a las 8pm para 3 personas
Enter fullscreen mode Exit fullscreen mode

El agente devuelve:

{
  "service": "consulta_general",
  "date": "2026-05-03",
  "time": "20:00",
  "people": 3
}
Enter fullscreen mode Exit fullscreen mode

Pero Grok no decide si eso se puede ejecutar.

Esa responsabilidad queda en el GuardrailEngine.

Laravel AI SDK estructura.
Grok interpreta.
Guardrail controla.
Laravel ejecuta.
Enter fullscreen mode Exit fullscreen mode

Esto ayuda a separar responsabilidades y evita que el modelo sea quien tenga la última palabra sobre reglas de negocio.

¿Dónde entra OpenSpec?

Usé OpenSpec para definir el cambio antes de implementarlo.

La demo quedó documentada con:

proposal.md
design.md
tasks.md
specs/ai-guardrails/spec.md
specs/appointment-booking/spec.md
specs/admin-rules/spec.md
Enter fullscreen mode Exit fullscreen mode

Esto me ayudó a mantener trazabilidad:

Requisito → Diseño → Implementación → Prueba
Enter fullscreen mode Exit fullscreen mode

Por ejemplo, el requisito decía:

El sistema debe evaluar todas las acciones generadas por la IA antes de llamar al API de citas.
Enter fullscreen mode Exit fullscreen mode

Y eso terminó implementado en el flujo:

ChatController
↓
LaravelAiAppointmentAgent
↓
AppointmentIntentAgent
↓
GuardrailEngine
↓
AppointmentController
Enter fullscreen mode Exit fullscreen mode

Diferencia con Agent Control y Strands

El artículo original trabaja el concepto desde Strands Agents y Agent Control.

En ese enfoque, el agente puede recibir una instrucción correctiva mediante algo similar a Guide(). Luego el agente reintenta la acción con los parámetros corregidos.

En mi demo hice una adaptación más sencilla:

Laravel AI SDK genera un payload estructurado.
GuardrailEngine valida el payload.
Si es corregible, el backend devuelve corrected_payload.
El usuario confirma.
Laravel ejecuta.
Enter fullscreen mode Exit fullscreen mode

Es decir, no hay un reintento automático del LLM guiado por Guide(). La corrección ocurre de forma determinística en el backend.

Aun así, el patrón conceptual se mantiene:

IA propone.
Guardrail evalúa.
Sistema corrige o bloquea.
Backend ejecuta solo si corresponde.
Enter fullscreen mode Exit fullscreen mode

Casos probados

Probé estos escenarios:

ALLOW  → cita válida
STEER  → hora fuera de horario
STEER  → demasiadas personas
STEER  → día bloqueado
STEER  → slot ocupado con alternativa disponible
BLOCK  → falta fecha
BLOCK  → servicio inválido
BLOCK  → autocorrección desactivada
BLOCK  → slot ocupado sin alternativa disponible
Enter fullscreen mode Exit fullscreen mode

Uno de los más interesantes fue el de slot ocupado.

En lugar de bloquear inmediatamente, el guardrail busca el siguiente horario disponible.

Slot solicitado ocupado
↓
Buscar siguiente slot disponible
↓
Si existe: STEER
↓
Si no existe: BLOCK
Enter fullscreen mode Exit fullscreen mode

Eso se acerca mucho a la idea del blog original: si el agente puede corregirse, no detengas el flujo.

Lo que aprendí

La principal lección fue esta:

No todo error del agente debe terminar en bloqueo.
Enter fullscreen mode Exit fullscreen mode

Hay errores que se pueden corregir de forma segura:

Hora fuera de horario
Cantidad mayor al máximo
Formato incorrecto
Día bloqueado
Slot ocupado
Enter fullscreen mode Exit fullscreen mode

Pero también hay casos donde el sistema debe detenerse:

Falta información crítica
Servicio no existe
No hay disponibilidad
Autocorrección desactivada
Regla estricta de negocio
Enter fullscreen mode Exit fullscreen mode

La clave está en clasificar bien las reglas.

También me gustó mucho trabajar con Laravel AI SDK porque permite encapsular la interacción con el modelo en clases de agentes. Eso hace que el código sea más mantenible y más cercano a cómo normalmente organizamos responsabilidades en Laravel.

Conclusión

Esta demo me ayudó a entender mejor cómo llevar los guardrails más allá del “permitir o bloquear”.

El patrón final quedó así:

Usuario pide algo
↓
Laravel AI SDK invoca el agente
↓
IA interpreta y genera payload
↓
Guardrail evalúa
↓
ALLOW / STEER / BLOCK
↓
Usuario confirma
↓
Backend ejecuta
Enter fullscreen mode Exit fullscreen mode

No es una implementación idéntica a Agent Control, pero sí aplica la misma idea central del artículo original: usar guardrails para guiar al agente cuando la corrección es segura, y bloquear solo cuando realmente es necesario.

Para mí, este enfoque tiene mucho valor en aplicaciones reales: citas, reservas, soporte, cotizaciones, DevOps, APIs internas y cualquier flujo donde una IA pueda intentar ejecutar acciones.

Lo más importante es mantener clara la separación:

La IA entiende.
El guardrail decide.
El backend ejecuta.
El admin configura.
Enter fullscreen mode Exit fullscreen mode

Código fuente

El código de la demo está disponible en GitHub:

https://github.com/fmarchena/appointment-agent-demo/tree/main

En el repositorio se incluye:

Laravel API
Laravel AI SDK
Vue frontend
Docker Compose
MySQL
GuardrailEngine
Integración con xAI / Grok
OpenSpec con proposal, design, tasks y specs
Enter fullscreen mode Exit fullscreen mode

Referencias

Artículo base:

Guardrails para Agentes de IA que se Autocorrigen en Lugar de Bloquear — Elizabeth Fuentes L, AWS Español.

https://dev.to/aws-espanol/guardrails-para-agentes-de-ia-que-se-autocorrigen-en-lugar-de-bloquear-3n32

Documentación relacionada:

Laravel AI SDK

https://laravel.com/docs/13.x/ai-sdk

Laravel

https://laravel.com/

xAI / Grok API

https://docs.x.ai/

OpenSpec

https://openspec.dev/

Top comments (0)