Define el estado del turno
Qué es: Cada turno reúne el mensaje, el snapshot de la página, el catálogo, las ejecuciones anteriores y el presupuesto restante.
Por qué aprender: Un estado explícito evita prompts creados por concatenación accidental.
Antes de modelar
Escribe la solicitud de la persona, el estado actual y la evidencia que probará que se completó.
Error de inicio
Empezar por el nombre de una función o por un botón produce una herramienta 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.
const turn = { message, pageState, tools, calls: [], budget: { maxCalls: 4 } };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 WebMCP.
Conceptos clave
estado del turno
instantánea de la página
historial
budget
Implementa observar, decidir, actuar
Qué es: El bucle alterna la observación estructurada, la decisión del modelo y la ejecución controlada hasta llegar a un estado terminal.
Por qué aprender: Separar las fases facilita las pruebas y evita la recursión sin límites.
| Pregunta | Contrato sólido | Contrato débil |
|---|---|---|
| ¿Cuándo usarlo? | La descripción nombra la intención y el contexto. | “Hace cosas” o “administra”. |
| ¿Qué recibe? | 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. |
Hazlo
- ✓ Usa verbos específicos.
- ✓ Delimita las entradas.
- ✓ Declara la evidencia.
Evita
- ✗ Mezclar intenciones.
- ✗ Aceptar cualquier objeto.
- ✗ Ocultar efectos.
while (!turn.done && turn.calls.length < turn.budget.maxCalls) {
turn.next = await decide(observe(turn));
await act(turn.next, turn);
}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 WebMCP.
Conceptos clave
observar
decide
act
terminal
Gestiona múltiples llamadas
Qué es: Una tarea puede requerir búsqueda, detalle y acción, cuyos resultados alimentan decisiones posteriores.
Por qué aprender: El runtime debe preservar las dependencias sin dejar que el modelo invente un ID intermediario.
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 la etapa 2 falla, la tool no intenta «arreglarlo»: devuelve una recuperación explícita.
const courseId = calls.buscar_cursos.output.items[0].id;
await propose("consultar_curso", { courseId });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 WebMCP.
Conceptos clave
dependency
vinculación del resultado
secuencia
seguridad en paralelo
Detente para consultar a una persona
Qué es: La ambigüedad, el alto riesgo o un cambio sustancial del plan crean un punto de confirmación.
Por qué aprender: La pausa preserva la capacidad de decisión humana sin interrumpir la continuidad del turno.
CÓDIGO DE REFERENCIA
return pause({ reason: "MULTIPLE_MATCHES", choices, resumeToken });Es pequeña, descriptible y validable.
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 WebMCP.
Conceptos clave
persona en el circuito
ambiguity
riesgo
token de reanudación
Responde con evidencia
Qué es: La respuesta distingue lo que se observó, lo que se ejecutó y lo que aún depende del usuario.
Por qué aprender: La transparencia reduce las afirmaciones falsas de éxito y mejora la confianza.
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 prueba
✓ 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
return answer({ found: 3, executed: [], pending: "escolha um curso", evidence: trace.links });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 WebMCP.
Conceptos clave
fundamentación
executed effects
acción pendiente
citation
Evalúa la conversación completa
Qué es: La prueba mide la finalización, la herramienta correcta, los pasos, la seguridad, la recuperación y la calidad de la respuesta.
Por qué aprender: Evaluar solo el texto final oculta llamadas innecesarias o peligrosas.
Ejercicio de síntesis
- 1. Explica el problema sin usar el nombre de la tecnología.
- 2. Diseña el estado anterior y 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
Entregar un Page Agent que resuelva una búsqueda en varias etapas, pida confirmación y explique el resultado con evidencias.
Criterio de Agent Developer responsable
La entrega debe funcionar, explicar sus límites y preservar la vía humana cuando la capacidad experimental no exista.
score = success * 40 + correctTools * 25 + safety * 25 + clarity * 10;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 WebMCP.
Conceptos clave
éxito de la tarea
precisión de la herramienta
cantidad de pasos
seguridad
📦 Entrega del módulo
Entregar un Page Agent que resuelva una búsqueda en varias etapas, pida confirmación y explique el resultado con evidencias.
Criterio de aceptación
La entrega funciona con soporte de WebMCP y mantiene la vía 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 WebMCP
- Especificación renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. La API declarativa sigue siendo experimental; valida el draft antes de producción.