Modela el recorrido como estados
Qué es: Cada etapa declara qué ya ocurrió, qué acciones están disponibles y qué transición es válida.
Por qué aprender: Sin un modelo de estado, el agente puede confirmar antes de iniciar o repetir un efecto ya completado.
Antes de modelar
Escribe la solicitud de la persona, el estado actual y la evidencia que probará la finalización.
Error de inicio
Empezar por el nombre de una función o por un botón produce una tool sin un objetivo humano claro.
Anticípate antes de abrir el código
¿Qué información cambia la decisión? ¿Qué efecto debe aparecer en la interfaz? Responde antes de implementar.
rascunho -> iniciado -> aguardando_confirmacao -> confirmadoProfundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
estado explícito
transición válida
precondición
efecto
Separa los errores recuperables de los definitivos
Qué es: Los errores recuperables indican una próxima acción; los errores definitivos cierran el intento con un motivo verificable.
Por qué aprender: La clasificación evita ciclos a ciegas y permite que el agente explique alternativas reales al usuario.
| Pregunta | Contrato sólido | Contrato débil |
|---|---|---|
| ¿Cuándo usarlo? | La descripción expresa la intención y el contexto. | “Hace cosas” o “gestiona”. |
| ¿Qué recibes? | Solo los datos necesarios. | Objeto genérico e ilimitado. |
| ¿Qué devuelve? | Estado y próxima acción verificables. | Texto sin protocolo. |
| ¿Cómo falla? | Código, motivo y recuperación. | Excepción opaca. |
Haz
- ✓ Usa verbos específicos.
- ✓ Delimita las entradas.
- ✓ Declara la evidencia.
Evita
- ✗ Mezclar intenciones.
- ✗ Aceptar cualquier objeto.
- ✗ Ocultar efectos.
return {
ok: false,
code: "INSCRICAO_NAO_INICIADA",
recovery: { tool: "iniciar_inscricao" }
};Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
código estable
mensaje accionable
próxima acción
final honesto
Protégete contra el estado obsoleto
Qué es: El estado usado para decidir puede cambiar antes de la ejecución, especialmente en vacantes, precios y permisos.
Por qué aprender: Volver a validar en el momento del efecto impide que una tool use una fotografía antigua como autorización vigente.
Observa
Captura el estado, la entrada y el contexto antes de la acción.
Decide
Valida las precondiciones y elige la transición permitida.
Ejecuta
Aplica la regla compartida y respeta la cancelación.
Demuestra
Actualiza la interfaz y devuelve un resultado estructurado.
Punto de control
Si el paso 2 no se aprueba, la tool no intenta «arreglárselas»: devuelve una recuperación explícita.
if (input.version !== inscricao.version) {
throw new ConflictError("Estado mudou; consulte novamente.");
}Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
revalidación
versión de estado
conflicto
nueva lectura
Haz mutaciones idempotentes
Qué es: Una clave de idempotencia permite repetir una solicitud sin duplicar una suscripción, un cobro o un envío.
Por qué aprender: Los agentes, las redes y los usuarios pueden repetir llamadas; la operación debe distinguir entre un reintento y un nuevo efecto.
CÓDIGO DE REFERENCIA
headers: { "Idempotency-Key": executionId }Es pequeña, está descrita y se puede validar.
Reutiliza la regla real de la aplicación.
Permite verificar el efecto y continuar.
Lee el código como contrato
Subraya dónde se valida la entrada, dónde ocurre el efecto, dónde llega la cancelación y dónde se actualiza la UI.
Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
idempotency key
retry seguro
resultado anterior
efecto único
Cancela y limita el tiempo
Qué es: AbortSignal y el timeout terminan el trabajo que dejó de ser relevante o superó la ventana operativa.
Por qué aprender: Cancelar de verdad preserva los recursos y evita que la interfaz muestre un éxito después de que la persona desistió.
Fallo provocado
Ejecuta el escenario con estado ausente, entrada no válida o capacidad no disponible.
Recuperación esperada
La respuesta informa qué falló, qué sigue siendo seguro y qué acción puede continuar.
Matriz mínima de pruebas
✓ camino feliz reproducible
✓ entrada inválida accionable
✓ la cancelación termina el trabajo
✓ el fallback preserva el recorrido
✓ la interfaz refleja el estado
✓ el backend mantiene la autorización
const signal = AbortSignal.any([
executionSignal,
AbortSignal.timeout(8000)
]);Profundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
AbortSignal
timeout
cleanup visual
resultado cancelado
Prueba la recuperación de extremo a extremo
Qué es: La integración debe demostrar el camino feliz, el orden inválido, el reintento, la cancelación y el cambio concurrente.
Por qué aprender: Una matriz de fallos convierte la resiliencia en un comportamiento verificable, no en una intención de arquitectura.
Ejercicio de síntesis
- 1. Explica el problema sin usar el nombre de la tecnología.
- 2. Diseña el estado anterior y el posterior.
- 3. Implementa la prueba funcional más pequeña.
- 4. Provoca un fallo y registra la recuperación.
- 5. Entrega código, evidencia y una limitación conocida.
Desafío del módulo
Implementa una inscripción por etapas que bloquea las llamadas fuera de orden y devuelve instrucciones de recuperación.
Criterio del Integrator responsable
La entrega debe funcionar, explicar sus límites y preservar la opción humana cuando la capacidad experimental no esté disponible.
confirmar antes de iniciar -> recovery: iniciar_inscricao
retry com mesma chave -> mesmo resultado
timeout -> interface volta ao estado estávelProfundiza: evidencia que vale la pena guardar
Registra la entrada, el estado anterior, la decisión tomada, el resultado y el cambio visible en la página.
Incluye también un fallo provocado y el comportamiento observado sin soporte de WebMCP.
Conceptos clave
escenarios
evidencia
reproducción
regresión
📦 Entrega del módulo
Implementa una inscripción por etapas que bloquea las llamadas fuera de orden y devuelve instrucciones de recuperación.
Criterio de aceptación
La entrega funciona con soporte de WebMCP y mantiene la opción manual cuando la API no existe.
Evidencia
Incluye código, escenario probado, resultado observado y una limitación conocida.
Fuentes técnicas
- Draft y repositorio oficial de WebMCP
- Especificación renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. La API declarativa sigue siendo experimental; valida el draft antes de producción.