Introducción

En las lecciones anteriores aprendiste a diseñar prompts, conectarte a una API de IA y estructurar el flujo de trabajo de un agente. Esta lección une todo: construirás una funcionalidad completa impulsada por IA dentro de una aplicación web real, desde la interfaz de usuario hasta la evaluación. La funcionalidad de ejemplo que usaremos es un revisor de código con IA que toma un fragmento de código pegado por el usuario y devuelve comentarios más una puntuación de calidad.

El objetivo no es escribir código de producción perfecto. El objetivo es entender cada capa del stack: formulario frontend, endpoint backend, prompt, llamada a la API, parseo de la respuesta y pruebas, para que puedas repetir el patrón con cualquier funcionalidad.

Estructura del proyecto

Una pequeña aplicación Node.js/Express es suficiente para demostrar el flujo completo. El backend expone una ruta que acepta texto de código, lo envía al modelo de IA y devuelve feedback estructurado. El frontend es un formulario HTML simple que envía el fragmento y renderiza el resultado.

// server.js
import express from "express";
import { reviewCode } from "./agent.js";

const app = express();
app.use(express.json());
app.use(express.static("public"));

app.post("/api/review", async (req, res) => {
  const { code } = req.body;
  if (!code || code.length < 5) {
    return res.status(400).json({ error: "Code snippet required" });
  }
  const result = await reviewCode(code);
  res.json(result);
});

app.listen(3000, () => console.log("Server on http://localhost:3000"));

La capa del agente

El agente es un módulo plano que posee el prompt template y la llamada a la API. Mantenerlo separado del manejador de ruta facilita las pruebas de forma aislada. El prompt pide al modelo que devuelva JSON con una puntuación y una lista de problemas, lo que elimina la necesidad de hacer parseo frágil de cadenas más adelante.

// agent.js
import OpenAI from "openai";

const client = new OpenAI();

export async function reviewCode(code) {
  const prompt = `You are a senior code reviewer. Analyze the following code and respond ONLY with valid JSON in this exact shape:
{"score": <number 0-100>, "issues": [{"line": <number or null>, "severity": "low|medium|high", "message": "<text>"}], "summary": "<one sentence>"}

Code:
${code}`;

  const response = await client.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: prompt }],
    temperature: 0.2,
    response_format: { type: "json_object" }
  });

  return JSON.parse(response.choices[0].message.content);
}

El frontend

La UI es intencionadamente minimalista. Un textarea para el código, un botón de envío y un panel de resultados. Enviar JSON mantiene el código coherente con el backend y evita sorpresas con la codificación de formularios.

<form id="review-form">
  <textarea id="code" rows="10" placeholder="Paste your code here"></textarea>
  <button type="submit">Review</button>
</form>
<pre id="result"></pre>
<script>
  document.getElementById("review-form").onsubmit = async (e) => {
    e.preventDefault();
    const code = document.getElementById("code").value;
    const res = await fetch("/api/review", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code })
    });
    const data = await res.json();
    document.getElementById("result").textContent = JSON.stringify(data, null, 2);
  };
</script>

Probar la funcionalidad

Las pruebas unitarias del agente directamente son la forma más veloz de detectar regresiones en el prompt. Construye un pequeño conjunto de pruebas con fragmentos de código y rangos de puntuación esperados, y ejecútalos en un bucle. Si un ajuste del prompt empeora un caso, lo verás inmediatamente.

// test.js
import { reviewCode } from "./agent.js";

const cases = [
  { code: "def add(a,b): return a+b", expectMin: 70 },
  { code: "eval(input())", expectMax: 30 },
  { code: "function f(){ while(true){} }", expectMax: 40 }
];

for (const c of cases) {
  const r = await reviewCode(c.code);
  const ok = (c.expectMin ? r.score >= c.expectMin : true) &&
             (c.expectMax ? r.score <= c.expectMax : true);
  console.log(`${ok ? "PASS" : "FAIL"} score=${r.score} code=${c.code.slice(0,30)}`);
}

Errores comunes

Tres problemas aparecen una y otra vez. Primero, no establecer response_format en json_object cuando necesitas salida estructurada, lo que provoca fallos silenciosos de parseo. Segundo, olvidarse de validar la longitud de entrada en el servidor, lo que permite a los usuarios enviar prompts enormes y acumular costes. Tercero, probar solo con código perfecto, lo que nunca revela cómo maneja el modelo los bugs. Incluye siempre al menos un fragmento claramente malo en tu conjunto de pruebas.

Resumen

Ahora tienes un patrón funcional para enviar una funcionalidad de IA: un frontend ligero, una ruta Express, un módulo de agente aislado que posee el prompt y la llamada a la API, y un pequeño conjunto de pruebas que protege contra regresiones. Reutiliza esta estructura para resumidores, clasificadores, asistentes de chat o cualquier otra herramienta con IA que añadas a una aplicación web.