Patrones de producción

Las funciones más fuertes del framework son más fáciles de recordar como patrones de fallo. Cada fila siguiente representa una clase real de incidente de producción y un mecanismo concreto, no un eslogan.

Fallo parcial en una operación de varios pasos

Failure: el primer paso tiene éxito, el segundo falla y el agente no puede saber qué efecto secundario ya ocurrió.

Mechanism: compón el workflow en una acción con una ruta de compensación explícita. Devuelve f.error() con acciones de recuperación disponibles; no pidas a un agente que adivine si es seguro reintentar. Una transacción o clave de idempotencia pertenece a tu handler y a tu base de datos.

Alucinación de parámetros

Failure: el modelo inventa tenantId, emailAddress u otro campo plausible.

Mechanism: cada esquema de acción es estricto. Las claves desconocidas se rechazan antes del middleware y del handler, con <validation_error> explicando lo enviado y lo esperado. La identidad del tenant debe proceder de ctx, nunca de la entrada de la herramienta.

Estampida de solicitudes

Failure: muchos agentes reintentan el mismo upstream lento hasta que tu conector agota sus propios recursos.

Mechanism: .concurrency({ maxActive, maxQueue }) limita el trabajo activo y en cola. La capacidad completa devuelve SERVER_BUSY con instrucciones de reintento. Combínalo con timeouts del upstream y un limitador de tasa por tenant o token.

Desbordamiento de la ventana de contexto

Failure: una respuesta de colección es demasiado grande, el modelo pierde la fila importante y toma una mala decisión.

Mechanism: Presenter .agentLimit() trunca antes de serializar y antepone un resumen con el número de filas ocultas y la indicación de usar filtros. .enableSelect() permite que el modelo solicite solo campos de primer nivel. La protección de bytes de salida detecta una respuesta de texto final demasiado grande.

Datos obsoletos tras una mutación

Failure: después de una escritura correcta, el agente ve una lectura antigua en su propio contexto.

Mechanism: marca las lecturas con .cached() o .stale(), y las escrituras con .invalidates('domain.pattern'). La capa de sincronización de estado decora las descripciones, emite un marcador de invalidación en el primer bloque y publica actualizaciones de recursos solo después de una mutación correcta.

Bucles de reintento ciegos

Failure: un modelo repite la misma llamada inválida porque el error solo dice "falló".

Mechanism: toolError(code, { suggestion, availableActions, retryAfter }) emite un contrato XML estructurado de recuperación. La siguiente acción tiene nombre, el retraso es explícito y el cliente tipado puede analizarlo como MCPFusionClientError.

Datos filtrados al modelo

Failure: un handler devuelve una fila de base de datos con un campo que el modelo nunca debería ver.

Mechanism: adjunta un Presenter con un esquema de allowlist y .redactPII(). Los campos no declarados nunca entran en la salida validada; la redacción enmascara las rutas sensibles declaradas en la copia clonada que viaja por la red. Prueba result.data con @mcpfusion/testing.

Carreras en operaciones destructivas

Failure: dos agentes emiten un reembolso, cambian un workflow o actualizan el mismo registro a la vez.

Mechanism: f.mutation() marca la acción como destructiva por defecto y el builder crea un serializador FIFO de mutaciones por acción. Añade idempotencia también en la capa de dominio: la serialización ordena llamadas, pero no vuelve idempotente una API de pagos externa.

Checklist operativo

Antes de Deploy:

• entradas estrictas e identidad del tenant desde el contexto
• Presenter en cada herramienta que devuelve datos de dominio
• límites en cada colección
• concurrencia y límites de tasa en llamadas upstream
• invalidación en las escrituras
• campos de recuperación en errores esperados
• lockfile y pruebas en CI
• telemetría y un sumidero de auditoría que nunca almacene secretos sin procesar

Próximos pasos

• Testing: convierte cada fila en una prueba de regresión
• Contracts: bloquea la deriva en CI
• Security pipeline: consulta el orden de ejecución