Separa la propuesta de la ejecución
Qué es: La llamada generada por el modelo es una propuesta no confiable hasta que pasa la validación y la política.
Por qué aprender: La frontera impide que el texto probabilístico se convierta directamente en un efecto.
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 proposal = await model.chooseTool(context);
const approved = await gate.evaluate(proposal, session);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
llamada a la herramienta
entrada no confiable
control de políticas
ejecución
Valida el schema de nuevo
Qué es: Aunque el proveedor aplique esquemas, el runtime valida tipos, límites, enums y campos adicionales.
Por qué aprender: La defensa en profundidad contiene las divergencias entre providers y las llamadas generadas por código externo.
| 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.
const result = validator.validate(tool.inputSchema, proposal.arguments);
if (!result.ok) return fail("INVALID_ARGUMENTS", result.errors);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
JSON Schema
coerción prohibida
límites
error estable
Aplica la política antes del efecto
Qué es: El riesgo, la autenticación, el alcance y la necesidad de confirmación se deciden fuera del modelo.
Por qué aprender: El LLM puede recomendar; la aplicación sigue siendo responsable de autorizar.
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.
if (tool.annotations?.destructiveHint) {
await requireHumanConfirmation(proposal);
}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
autorización
riesgo
confirmación
alcance
Ejecuta con presupuesto y cancelación
Qué es: Cada ejecución recibe AbortSignal, deadline y límites compatibles con la experiencia.
Por qué aprender: Una conversación abandonada no debe mantener la red, la UI ni el backend trabajando indefinidamente.
CÓDIGO DE REFERENCIA
const signal = AbortSignal.any([turn.signal, AbortSignal.timeout(10_000)]);
const tools = await document.modelContext.getTools();
const tool = tools.find((item) => item.name === proposal.name);
if (!tool) throw new Error("Tool não está mais disponível");
return document.modelContext.executeTool(tool, proposal.arguments, { signal });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
AbortSignal
deadline
presupuesto de recursos
cleanup
Normaliza los resultados y los errores
Qué es: El runtime convierte retornos heterogéneos en sobres con estado, datos, evidencia y la siguiente acción.
Por qué aprender: Una forma común simplifica el loop sin ocultar el error original.
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 { ok: false, code: "AUTH_REQUIRED", recovery: { action: "request_login" } };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
envelope
error recuperable
evidencia
siguiente acción
Registra un rastro reproducible
Qué es: Cada ejecución vincula el turno, el catálogo, la propuesta, la decisión de política, la duración y el resultado sanitizado.
Por qué aprender: El rastro permite depurar la selección, la ejecución y el efecto sin guardar secretos.
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
Implementa un ejecutor que recibe una llamada del modelo, valida la intención y devuelve un sobre de éxito, error o recuperación.
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.
trace.record({ turnId, tool: proposal.name, policy: approved.reason, durationMs, outcome });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
traceId
catalog version
latencia
redacción
📦 Entrega del módulo
Implementa un ejecutor que recibe una llamada del modelo, valida la intención y devuelve un sobre de éxito, error o recuperación.
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.