¡Hola Devs! Por Qué la Confiabilidad Es un Problema de Arquitectura, No de Modelo

Cuando construyes un agente de IA para un dominio donde una respuesta equivocada puede mandar a un buque patrulla a kilómetros en la dirección opuesta, el modelo es la parte menos interesante del sistema. El verdadero reto de ingeniería es construir algo en lo que puedas confiar: que sea correcto, que se mantenga dentro de sus límites y que aguante en tareas totalmente distintas — contra datos en vivo, no un snapshot estático.

Esta es la historia de cómo el equipo detrás de una plataforma abierta de conciencia del dominio marítimo construyó su agente. Las lecciones aplican para cualquiera que esté llevando agentes a producción — ya sea en salud, finanzas o soporte al cliente.

El insight central: los agentes son no-determinísticos, pero las herramientas que usan no tienen por qué serlo. Cada mejora de confiabilidad vino de restringir qué puede fallar en cada capa del stack.

Si has estado pensando en cómo los agentes aprenden de conocimiento experto sin reentrenamiento, este patrón arquitectónico es compañero natural de el enfoque del segundo cerebro organizacional.

AI agent answering maritime domain awareness query about Ghana EEZ with source attribution and map deep link IT Technology Image

La Anatomía del Agente: Alma, Habilidades y Config

El equipo descompone al agente en tres partes:

  • Alma (Soul) — el system prompt que define la persona y los límites de comportamiento. Dice explícitamente lo que el agente no hará (ej.: "nunca hacer determinaciones legales", "nunca especular más allá de los datos").
  • Habilidades (Skills) — archivos markdown con frontmatter estructurado que codifican cómo manejar tipos específicos de petición. Misma spec que usan Claude Code y Codex.
  • Config — elección de harness, elección de LLM, ajustes de runtime. Cambiar el modelo es cambio de config, no rebuild.

Alma + habilidades se empaquetan en una imagen Docker — artefacto versionado y desplegable. Los secretos se inyectan en runtime.

Por Qué Esta Separación Importa

Cuando los límites viven en el system prompt (y no en fine-tuning), son auditables y fáciles de revisar. Cuando las habilidades son markdown puro, cada una es comprensible, versionable y diffeable en un PR.

Herramientas Determinísticas para un Agente No-Determinístico

La mayor victoria de confiabilidad: envuelve tu API en una CLI hecha a medida en vez de dejar que el agente construya llamadas crudas.

# ANTES: el agente construye llamadas de API desde cero
# Resultado: paginación malformada, errores de encoding de geometría,
# bugs silenciosos de tipo de filtro que devuelven datos *equivocados*

# DESPUÉS: el agente emite un comando tipado, la CLI maneja la plomería
# skylight events search --region "EEZ de Panamá" \
#   --type fishing --since 2024-01-01 --output resultados.json

Por qué funciona el enfoque de CLI:

  1. Flags de filtro tipados colapsan objetos de query anidados complejos en una interfaz predecible.
  2. Auto-documentada — texto extenso de --help y mensajes de error estructurados dejan al agente recuperarse sin adivinar.
  3. Escribe en disco, no en stdout — pasar JSON grande por pipe de shell revienta buffers y rompe herramientas como jq. Escribir a archivo local resuelve ambos problemas y permite que el agente lea resultados a lo largo de workflows multi-paso.

Debajo de la CLI queda una API tipada con un par común de operaciones search/aggregate en todos los tipos de recurso. Cada capa restringe qué puede fallar en la siguiente: API tipada → CLI determinística → habilidades del agente referenciando comandos de la CLI.

Kubernetes pods provisioning isolated agent sandbox sessions for multi-user AI platform Software Concept Art

Sandbox, Aislamiento y Evaluar al Agente Completo

Sesiones Aisladas por Usuario

Cuando tu agente atiende a cientos de agencias gubernamentales y ONGs en más de 70 países, el aislamiento de datos no es negociable. El patrón:

  • Cada sesión de usuario obtiene un deployment de Kubernetes dedicado con sus propios pods.
  • El JWT del usuario se inyecta en el aprovisionamiento, escopando todas las llamadas de API a sus datos.
  • Archivos escritos durante el análisis existen solo en esa sesión.
  • El acceso de red se restringe solo a los servicios que el agente necesita.

Este es el tipo de decisión de infraestructura que se ve aburrida en una slide, pero es donde la mayoría de los proyectos de agentes en producción fallan silenciosamente.

⚠️ Los Límites Que Necesitas Conocer

Incluso un agente bien arquitectado tiene modos de falla. De los propios datos de evaluación del equipo:

  • Pasarse a recomendaciones — el agente se deslizó de apoyo a la decisión hacia consejo táctico. Los guardrails deben probarse, no asumirse.
  • Bugs de simplificación de geometría — fronteras simplificadas espacialmente hicieron que el agente perdiera eventos reales cerca de los bordes.
  • Llamadas de herramienta inventadas — el agente alucinó un comando de CLI que no existía. Es exactamente por eso que tu CLI debe devolver un error claro de "comando desconocido" con la lista de válidos.

Evaluar al Agente, No al Modelo

Los benchmarks estáticos no te dicen si tu agente funciona en producción. El equipo construyó su propio pipeline de evaluación:

  1. Expertos de dominio escriben escenarios y rúbricas, y ponderan cada criterio por tarea.
  2. Un prompt en lenguaje natural corre por el sandbox real, contra datos en vivo.
  3. Un juez LLM puntúa cada criterio de 0 a 1 con justificación escrita.
  4. El agregado ponderado se compara contra un umbral fijo de aprobación.
  5. Los resultados se timestampan y diffean contra la corrida anterior.

Una versión que regresa en los criterios de evaluación nunca llega a los usuarios finales. Esa es la disciplina que separa un demo de un producto.

Para otro ángulo sobre hacer el comportamiento de la infraestructura transparente y debuggeable, checa este texto sobre hacer visibles las fallas de trust anchor de DNSSEC.

LLM judge evaluation pipeline scoring AI agent responses against weighted rubric criteria on live data Developer Related Image

Qué Robarle a Tu Propio Agente

Si estás construyendo un agente en producción, aquí está el checklist que salió de este proyecto:

  1. Separa alma, habilidades y config. Empaqueta alma+habilidades en una imagen versionada. Haz que cambiar el modelo sea cambio de config.
  2. Nunca dejes que el agente construya llamadas crudas de API. Envuelve todo en una CLI tipada y auto-documentada con errores estructurados.
  3. Escribe salidas grandes en disco, no en stdout. Los pipes de shell te van a traicionar a escala.
  4. Haz sandbox de cada sesión. El aislamiento por usuario no es opcional cuando hay datos reales involucrados.
  5. Evalúa al agente completo, no al modelo. Rúbricas, jueces LLM, scores ponderados, diffs de versión.
  6. Bloquea el release en regresión de evaluación. Sin verde, sin ship.

Lo Que Viene en Este Espacio

Tres patrones que vale la pena seguir: control de UI dirigido por el agente (el agente no solo devuelve links, maneja el mapa), ruteo de modelo (modelos baratos para lookups, modelos frontier para investigaciones) y memoria entre threads (hechos persistentes como la jurisdicción de un usuario cargados automáticamente entre conversaciones).

Para Dónde Ir Desde Aquí

  • Empieza instrumentando tu agente actual con un harness de evaluación antes de agregar features.
  • Si aún no tienes un wrapper de CLI para tu API, ese es el paso uno.
  • Lee el writeup original de ingeniería para el contexto completo: evidencia y material fuente.

La confiabilidad no es una feature que agregas al final. Es la arquitectura que eliges al principio. 🚀

Este contenido fue redactado con la asistencia de herramientas de IA, basándose en fuentes confiables, y fue revisado por nuestro equipo editorial antes de su publicación. No reemplaza el asesoramiento de un profesional especializado.