Cómo crear un agente de IA que sobreviva a la producción

1. Decidir si el caso requiere un agente o canalización.

El agente es costoso en latencia, costo y superficie de falla. Antes de escribir la primera línea, verifique si el problema tiene ramificaciones de decisión reales. Si el flujo es siempre A, luego B y luego C, desea un flujo de trabajo determinista con una o dos llamadas LLM dentro, no un agente.

El criterio práctico: si puedes dibujar el diagrama de flujo completo sin usar la palabra "depende", no eres un agente. Un agente está justificado cuando el número de caminos posibles es demasiado grande para codificarlos y el costo de cometer errores es recuperable.

• Pipeline: extracción de datos, clasificación, resumen, enriquecimiento por lotes.
• Agente: triaje con seguimiento, soporte que consulta múltiples sistemas, búsqueda iterativa, operaciones que requieren verificación antes de escribir.

2. Modele las herramientas antes del mensaje.

Las capacidades del agente son exactamente el conjunto de funciones que usted expone. Cada función necesita un esquema escrito, una descripción escrita para el modelo (no para el desarrollo profesional), validación de entrada y errores legibles: el modelo lee el mensaje de error y lo intenta nuevamente, por lo que un "Error interno del servidor 500" desperdicia un ciclo completo.

Separar la lectura de la escritura. Se pueden publicar herramientas de lectura; Las herramientas de escritura pasan por la confirmación, la clave de idempotencia y el registro de auditoría.

const buscarPedido = {
  name: "buscar_pedido",
  description:
    "Retorna status, itens e prazo de um pedido. Use quando o cliente citar número de pedido.",
  parameters: z.object({
    pedidoId: z.string().regex(/^\d{6,10}$/),
  }),
  handler: async ({ pedidoId }, ctx) => {
    const pedido = await db.pedido.find(pedidoId, { tenant: ctx.tenantId });
    if (!pedido) {
      return { erro: "Pedido não encontrado para este cliente. Peça o número novamente." };
    }
    return pick(pedido, ["status", "itens", "prazoEntrega"]);
  },
};

3. Elija el bucle de control

Tres topologías cubren casi todo. Un agente único con herramientas resuelve el 80% de los casos y es lo que debes probar primero. Orchestrator con subagentes especializados es útil cuando los dominios tienen indicaciones y herramientas que son incompatibles entre sí. El gráfico de estado explícito es válido cuando el proceso tiene pasos auditables obligatorios.

En cualquier topología, imponga un límite de iteración, un tiempo de espera por herramienta y un tiempo de espera global. Un agente de bucle sin hogar es un incidente pendiente de fecha.

4. Memoria: contexto, sesión y conocimiento

Confundir los tres tipos de memoria es la causa más común de memoria costosa y confusa. El contexto es la ventana de llamada actual y debe montarse, no acumularse. La sesión es el estado de la conversación, guardada en el banco y resumida cuando pasa un límite. El conocimiento es lo que el agente busca a pedido mediante la recuperación.

Para el conocimiento, RAG con incrustaciones resuelve la búsqueda semántica en la documentación; La consulta SQL directa resuelve datos estructurados y es más económica, rápida y auditable. Mucha gente pone lo que debería ser un SELECT en un vector.

• Contexto: mensaje del sistema + últimos N mensajes + resultados de la herramienta redonda.
• Sesión: historial persistente, resumen continuo, entidades ya identificadas.
• Conocimiento: pgvector para texto, base de datos relacional para hechos, caché para lo que se repite.

5. Barandillas y seguridad

Trate todos los resultados del modelo como entradas que no son de confianza. El contenido que lee puede engañar al agente (un correo electrónico, una página, un PDF de un cliente) para que utilice herramientas que usted no pretendía. La defensa no es una indicación mejor, es una autorización en el manejador.

Cada llamada carga el inquilino y el usuario desde el contexto de ejecución, nunca los argumentos del modelo. El alcance de los datos se resuelve en el servidor. Las operaciones destructivas requieren confirmación humana o pasan por una cola de aprobación.

• Nunca acepte el ID de inquilino, el ID de usuario o el rol como parámetro de herramienta.
• Límite de tarifa por sesión y por cuenta, no solo global.
• Filtro de PII en la entrada del registro y lo que se envía al proveedor.
• Kill switch por herramienta, activable sin despliegue.

6. Evaluación: lo que separa la ingeniería del ensayo y error

Sin un conjunto de evaluación, no se pueden cambiar modelos, ajustar indicaciones o reducir costos sin riesgo. Reúna de 30 a 100 casos reales con los resultados esperados, ejecútelos en CI con cada cambio y monitoree tres métricas: éxito de la tarea, elección correcta de la herramienta y costo promedio por ejecución.

Para obtener resultados abiertos, utilice una plantilla de juez con una rúbrica escrita y un muestreo humano semanal. No persiga el 100%: establezca el umbral aceptable y el comportamiento alternativo por debajo de él.

7. Costo y latencia como requisito de diseño

El costo del agente crece de manera no lineal: cada iteración recarga todo el contexto. Dos palancas resuelven la mayor parte de esto: reducir lo que entra en contexto y enrutar por complejidad, con un modelo pequeño en clasificación y un modelo grande solo cuando la tarea lo requiere.

Mida el costo por conversación resuelta, no por token. Es la única métrica que se compara con el costo del proceso manual que reemplaza el agente.

• Caché de avisos para avisos estables del sistema.
• Streaming para concienciar la latencia, con herramientas en paralelo cuando son independientes.
• Límite de gasto por sesión, con degradación controlada en lugar de factura sorpresa.

8. Operación: observabilidad y despliegue

Cada ejecución necesita un seguimiento completo: mensajes, herramientas llamadas, argumentos, latencia, tokens y resultado. Sin esto, los agentes depuradores se convierten en arqueología.

Suba con un alcance pequeño y una ruta de escape despejada. Un agente que pasa el testigo a un humano cuando este no está seguro genera más confianza que uno que responde cualquier cosa con convicción.