Crear tu Primer Agente IA en Producción: Los Pasos que Nadie Muestra

Los tutoriales de agentes IA se detienen siempre en el mismo punto: el prototipo que funciona en un Jupyter notebook. Aquí cubro lo que viene después — crear un agente que corra en producción con usuarios reales.

Qué Es Realmente un Agente IA (en la Práctica)

Un agente IA es un bucle: el modelo recibe contexto, decide una acción, ejecuta la herramienta correspondiente, recupera el resultado, y repite hasta tener una respuesta final.

Arquitectura mínima:

async function runAgent(userQuery: string, tools: Tool[]): Promise<string> {
  const messages: Message[] = [{ role: 'user', content: userQuery }];

  for (let i = 0; i < MAX_STEPS; i++) {
    const response = await callClaude({ messages, tools });
    const step = parseAgentResponse(response);

    if (step.finalAnswer) return step.finalAnswer;
    if (!step.tool) throw new Error('Agent stuck: no tool, no answer');

    const result = await executeTool(step.tool, step.toolInput);
    messages.push(
      { role: 'assistant', content: response.content },
      { role: 'user', content: `Tool result: ${result}` }
    );
  }
  throw new Error(`Agent exceeded MAX_STEPS (${MAX_STEPS})`);
}

MAX_STEPS es innegociable. Sin esto, un agente puede hacer bucle indefinidamente.

Definir las Herramientas con Precisión

La calidad de las herramientas es lo que diferencia un agente útil de uno que alucina.

Cada herramienta necesita:

• Un nombre explícito (search_database, no search)
• Una descripción que indique cuándo usarla Y cuándo no
• Un esquema JSON estricto para los parámetros

const searchTool = {
  name: "search_client_database",
  description: `Busca en la base de datos de clientes por nombre, NIF o email.
    Usa cuando: el usuario pregunta sobre un cliente específico.
    NO uses para: estadísticas generales — usa get_stats en su lugar.`,
  input_schema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Nombre, NIF o email" },
      limit: { type: "number", description: "Máximo resultados, por defecto 5" }
    },
    required: ["query"]
  }
};

Tests Antes de Producción

Lo que testeo sistemáticamente:

• Happy path: el agente completa la tarea en ≤ N pasos
• Fallo de herramienta: una herramienta devuelve error — el agente debe degradarse bien
• Bucle infinito: MAX_STEPS alcanzado — el agente debe salir limpiamente
• Input malicioso: prompt injection, desbordamiento de contexto

Monitorización en Producción

Dos métricas críticas en tiempo real:

1. Número medio de pasos por sesión — si sube, una herramienta está rota o el prompt es ambiguo
2. Tasa de sesiones MAX_STEPS — si > 2%, hay un bug en la lógica del agente

Sin monitorización, descubres los problemas cuando el usuario se queja. Con ella, los ves antes.

Lo Que No Hacemos

• Nunca desplegar sin suite de tests de regresión
• Nunca superar 10 herramientas por agente (más allá, el modelo se pierde)
• Nunca dejar que un agente modifique datos críticos sin confirmación humana