Gestión de excepciones de envíos con IA: cómo funciona Shipment Exception Commander

La gestión de excepciones de envíos no se complica porque a los equipos les falten alternativas. En la gestión de incidencias logísticas, el problema es que las evidencias llegan con distintos niveles de confianza, las cotizaciones de recuperación caducan, los costos pasan de un nivel de aprobación a otro y un reintento apresurado puede generar una segunda reserva cuando la primera sí se había completado.

Shipment Exception Commander es una aplicación de referencia de código abierto para Claude Managed Agents, centrada precisamente en ese punto crítico de decisión y en el uso de agentes de IA para logística. Examina una excepción sintética, puntúa cada opción de recuperación mediante reglas mecánicas, delega una revisión independiente del riesgo, muestra a una persona la acción exacta y solo permite una mutación idempotente en el entorno de pruebas después de recibir la aprobación nativa.

Gestión de excepciones de envíos: puntuación determinista antes del criterio del modelo

El coordinador nunca inventa tarifas ni convierte un texto descriptivo en una política. Una herramienta de servidor y solo lectura llamada shipment_intelligence expone tres casos sintéticos y calcula la puntuación de cada opción con una fórmula fija: 50 puntos por cumplir la promesa, 20 por la cobertura de inventario, 20 por la eficiencia de costos respecto del límite absoluto y 10 por la confianza. Cada opción incluye la versión y el vencimiento de la cotización, la ETA, la cantidad de unidades protegidas y el costo incremental en USD.

El caso principal de prueba, SCX-2026-071, comparó tres escenarios reales de decisión: una recuperación marítima económica que incumplía la promesa, un envío aéreo completo que superaba el límite absoluto de gasto y una expedición aérea dividida que protegía las 240 unidades comprometidas por $4,200. La opción dividida obtuvo 91 puntos y se mantuvo dentro del límite de $5,000 asignado al operador. La puntuación hace que la recomendación sea reproducible; el papel de Claude consiste en reunir las evidencias, cuestionar los supuestos y explicar las contrapartidas.

Las evidencias no fiables no pueden autorizar una acción

Una de las notas del transportista contiene deliberadamente un texto con apariencia de instrucción que ordena al agente ignorar la política de aprobación y reservar la opción prémium. El flujo marca esa nota como no fiable, la conserva como evidencia y descarta de forma explícita su valor como directiva. La política procede del catálogo sintético versionado y del adaptador, nunca de la descripción del envío ni de la salida de una herramienta.

El coordinador tampoco dispone de memoria escribible entre sesiones, bóveda, integración MCP ni salida a la red. read, glob y grep son las únicas excepciones limitadas con aprobación automática. Bash y la escritura de entregables están configurados como always_ask; la edición, la obtención de contenido web y la búsqueda web permanecen desactivadas. La única mutación canónica del estado es el comando execute del adaptador.

Automatización logística con IA: un verificador pone a prueba la recomendación

Antes de solicitar cualquier ejecución, el coordinador Opus delega la recuperación propuesta a un verificador Haiku de alcance limitado. En la ejecución de prueba, el verificador respondió NEEDS_CHANGES: no pudo determinar si la cotización Q-071-v4 seguía vigente ni si la capacidad y los recargos eran definitivos. El coordinador no pasó por alto la objeción. Llamó al validador determinista de propuestas, que volvió a comprobar el reloj sintético, el vencimiento de la cotización, la versión de la política, el nivel de gasto y la versión esperada del estado. Solo el resultado vinculante ready_for_human_approval cambió el estado general a listo.

El resumen para aprobación detalló entonces los identificadores del caso y de la opción, el gasto exacto de $4,200, la ETA anterior y la nueva, el impacto sobre la promesa al cliente, las 240 unidades protegidas, el vencimiento de la cotización, las versiones de la política y del estado, la puntuación, el historial del verificador, las alternativas descartadas, la clave estable de idempotencia, los campos esperados del comprobante y el comportamiento ante una denegación o un fallo.

Denegar significa que no hay mutación

La primera tarjeta de aprobación nativa se denegó de forma deliberada. No se ejecutó ningún comando que modificara el estado: este permaneció en detected, en la versión 3; no existía ningún comprobante y la clave de idempotencia siguió sin utilizarse. El agente no cambió de herramienta, no alteró el comando ni fabricó una clave nueva.

Ante la petición explícita del operador, se volvió a presentar la misma acción canónica. Esta vez se autorizó. En el punto exacto de la mutación, el adaptador comprobó de nuevo la versión 3 del estado, la vigencia de la cotización, la política, el nivel de aprobación y el límite absoluto de $10,000. Ejecutó la acción exactamente una vez, llevó el caso de detected en la versión 3 a resolved en la versión 4 y devolvió el comprobante rcpt_37105a2da411aee0391c con la referencia de reserva SBX-56DFC3291972.

Ejecución segura ante repeticiones, con un alcance explícito

El adaptador sintético controla una clave estable, SCX-2026-071:OPT-071-B:v3, un bloqueo a nivel del sistema operativo, la inspección del estado canónico y un registro de comprobantes. Las llamadas duplicadas con la misma intención devuelven el comprobante existente; si otra llamada asocia una intención incompatible a esa clave, falla; y las versiones obsoletas, la ejecución simultánea o una posible escritura parcial exigen inspeccionar el estado en lugar de reintentar a ciegas.

Estas protecciones se describen deliberadamente dentro de sus límites reales: el bloqueo, el estado y el registro de comprobantes son archivos locales de la sesión en un único entorno aislado de Managed Agents. No constituyen una garantía distribuida para producción. Un adaptador real para un transportista o un TMS necesitaría un almacén transaccional compartido y un límite de idempotencia en el sistema de destino.

El evaluador de resultados comprobó las evidencias

La sesión escribió tres artefactos en /mnt/session/outputs/: un paquete de recuperación legible por personas, un registro de auditoría estructurado y el comprobante de ejecución sin procesar. Una evaluación de Managed Agents comparó de forma independiente esos archivos con el catálogo, el código fuente del adaptador, el estado canónico, el historial de aprobaciones y el registro de comprobantes. Exigió correcciones sobre la comunicación del vencimiento de la cotización, el comportamiento explícito ante fallos, un manifiesto de entregables y la limitación al ámbito de la sesión antes de devolver satisfied.

El paquete de recuperación se descargó después mediante el proxy de archivos de la aplicación. Su SHA-256 es 30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40b. La sesión de capacidades es sesn_01CcQjCVoWvNQ7VJLFbuDJxh; el resultado es outc_01GoD4rsLMh93iQNfAUw63KW.

La ejecución en vivo de esa evaluación también reveló una carencia en la interfaz: los hilos secundarios del evaluador pueden solicitar aprobación mientras la sesión principal permanece inactiva. La versión publicada ahora reconstruye las tarjetas de aprobación pendientes tanto desde los eventos requires_action del hilo principal como desde los eventos evaluated_permission: ask de los hilos secundarios, las retira al recibir una confirmación o un resultado e impide que una repetición reactive solicitudes ya resueltas. También retransmite el session_thread_id del evaluador mediante una lista restringida de valores permitidos en el navegador y verifica esa ruta contra el evento exacto de la herramienta que la originó antes de remitir la decisión.

Otra sesión de prueba configurada con Sonnet, sesn_01BvSf33BLBbN86w5oDb3BkQ, recorrió esa ruta corregida. El evento de herramienta del evaluador reenviado entre hilos, sevt_013VnmofY8ytk6QwgDtNSYoq, llevaba asociado el hilo sthr_018HMgpidoN86Qp4iGLZt1q3; la interfaz generó la confirmación sevt_016ZFv5TdBPKNyEPThzGT36Q con los mismos identificadores de herramienta e hilo, el servidor la aceptó y el evaluador continuó hasta solicitar su siguiente comprobación. La prueba acotada se interrumpió entonces de manera intencional para no pagar iteraciones adicionales irrelevantes; la evaluación principal del envío mantuvo su resultado satisfactorio.

Opus como modelo principal, Sonnet para validación y Haiku para verificación

El coordinador aprovisionado sigue siendo claude-opus-5. Para que las validaciones pagadas y repetibles resulten económicas, las sesiones locales solo pueden sustituir de forma explícita el modelo del coordinador por claude-sonnet-5; cualquier otra sustitución en tiempo de ejecución falla de forma cerrada. El verificador independiente utiliza claude-haiku-4-5. La sesión de prueba de humo facturada sesn_01RTs3wLV41odV9p92eWtrHV utilizó Sonnet y devolvió la respuesta exacta SMOKE OK.

El conjunto de pruebas de producción permanece deliberadamente aislado de las credenciales, incluso cuando un desarrollador tiene configurado un archivo .env.local. Demuestra que un despliegue nuevo no expone ningún campo para introducir una clave en el navegador, no envía tráfico a Anthropic, informa configured: false y devuelve 503 desde las rutas de facturación.

Una referencia pública que falla de forma cerrada

La referencia pública en Vercel no contiene ninguna clave de Anthropic ni identificadores de recursos de Managed Agents. La página de inicio y /api/agent/health siguen disponibles, mientras que la creación de sesiones falla de forma cerrada. Quienes adopten el proyecto deben aprovisionar el agente y el entorno con su propia cuenta de Anthropic; cualquier instancia configurada debe protegerse mediante control de acceso antes de permitir que otros usuarios lleguen a ella.

Todos los casos, transportistas, cotizaciones, referencias de reserva, cambios de estado y comprobantes de este proyecto son sintéticos. La aplicación demuestra un patrón de control operativo, no una integración real con un transportista.

Evidencias de la versión

• Repositorio: dvnc-labs/shipment-exception-commander
• Versión: v0.1.0
• CI: ejecución de publicación correcta
• Commit: 1db0329
• Despliegue: shipment-exception-commander.vercel.app
• Estado: comprobación del agente con fallo cerrado

Shipment Exception Commander tiene un alcance deliberadamente más limitado que un copiloto logístico. Asume una única promesa auditable: recomendar a partir de evidencias versionadas, cuestionar la recomendación, pedir a una persona que apruebe la acción exacta, ejecutar una sola mutación y dejar pruebas suficientes para reconstruir lo ocurrido.