Prototipo de Laboratorio de Investigación

Una guía práctica para desarrollar y ejecutar agentes de IA (con trazabilidad real).

En muchos proyectos de «agentes», lo difícil no es que el modelo genere texto: lo difícil es operar el agente. Saber qué intentó hacer, qué herramientas usó, qué encontró, qué concluyó y por qué. Por esa razón este prototipo está pensado justamente para eso:

• Definir un agente.
• Crear ejecuciones («runs»).
• Correr un ciclo `ReAct` (Plan → Act → Observe → Reflect).
• Guardar un rastro auditable.

El resultado es una especie de «laboratorio» para agentes: un lugar donde puedes iterar, inspeccionar y depurar comportamientos con evidencia.

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';

export const localOllama = createOpenAICompatible({
  name: "ollama",
  baseURL: "http://localhost:11434/v1",
  apiKey: "not-required",
});

export const OLLAMA_MODEL = 'gpt-oss:20b';

Este prototipo usa una interfaz (Next.js + AI SDK + TypeScript) para configurar agentes, ejecutar investigaciones asistidas con herramientas web y un LLM local (Ollama), y persistir toda la trazabilidad (pasos, resultados de herramientas, observaciones, reflexiones y métricas) en una base de datos.

El corazón del sistema: el ciclo ReAct

La experiencia principal vive en el detalle de una ejecución (un «run»), donde la app orquesta un ciclo:

1. Plan: define o deriva una consulta/objetivo operativo (qué se va a buscar y con qué intención).
2. Act: ejecuta acciones: buscar en web, traer URLs, resumir contenido.
3. Observe: consolida lo encontrado en una «observación» estructurada (headline, detalles, artefactos/claims).
4. Reflect: evalúa si el objetivo está satisfecho; si no lo está, propone ajustes (por ejemplo, nuevas consultas para la siguiente vuelta).

Esto convierte la ejecución en un proceso repetible: no es «un chat», es un pipeline de investigación con feedback.

Donde nace el Agente

La sección Agents funciona como un «constructor» de agentes. Aquí defines:

• Identidad: nombre y rol.
• Objetivo: título y system prompt.
• Parámetros del modelo: temperatura, límites, formato de salida.
• Presupuestos/límites: tokens, costo, pasos, tiempo, y otros parámetros.

Cuando se crea un agente, se crea un contexto de agente y, además, crea una ejecución inicial asociada (un «run»).

Dicho de otra forma: Agents no es solo configuración; es el punto de partida para crear algo ejecutable.

La lista de ejecuciones + el «Run Detail»

En Runs ves todas las ejecuciones, con su estado y última actualización.

Al entrar a un run específico, aparece el panel que realmente importa:

• Resumen del run (iteraciones, pasos, tokens, costo, etc.).
• El ciclo ReAct con resultados visibles: lo buscado, lo traído, los resúmenes.
• La salida estructurada de Observe/Reflect.
• Señales de calidad como distribución de confianzas para claims.

Este diseño te permite responder preguntas operativas típicas:

• ¿Qué URLs se usaron realmente?
• ¿Qué concluyó el sistema y con qué nivel de confianza?
• ¿La reflexión marcó el objetivo como cumplido o no?
• Si no se cumplió, ¿qué sugirió buscar después?

Tools: el catálogo de herramientas disponibles

La sección Tools es un inventario de herramientas:

• Qué hacen
• Cuándo se usan
• Qué entrada/salida esperan.

En el estado actual del proyecto, es importante entender algo: algunas herramientas están implementadas de verdad (por ejemplo búsqueda web, fetch, resumen), pero otras aparecen como «stubs» (endpoints de ejemplo) o como capacidades descritas para una evolución futura (por ejemplo, gestión completa de sub-agentes).

Tools es útil porque «documenta el contrato» de las herramientas y te ayuda a mantener alineado lo que el agente cree que puede hacer con lo que el sistema realmente soporta.

Diagnósticos

import { streamText } from 'ai';
import { localOllama, OLLAMA_MODEL } from '@/lib/localOllama';

export async function GET() {
  const result = streamText({
    model: localOllama(OLLAMA_MODEL),
    messages: [
      { role: 'system', content: 'You are a helpful senior Ollama assistant.' },
      { role: 'user', content: 'Explain what Ollama is and how it works in one concise paragraph.' },
    ],
  });
  return result.toTextStreamResponse();
}

La sección Settings es pragmática.

Incluye pruebas para validar que el entorno está listo:

• Ollama Test: verifica que el LLM local responde (y que el streaming funciona).
• Supabase Database Test: comprueba conectividad con la base de datos.
• pgvector Test: valida que la extensión/vector store esté operativo si tu flujo lo requiere.
• Google Search Config: confirma que las credenciales de búsqueda están bien configuradas y hay resultados de vuelta.

Trazabilidad y persistencia

En muchas demos de agentes, el proceso se pierde: solo queda el texto final. Aquí, el diseño busca lo contrario: que cada ejecución deje huella, una memoria.

A alto nivel, el sistema persiste piezas como:

• Configuración.
• Contexto del agente.
• Estado del run (métricas y resumen).
• Pasos planificados/ejecutados (qué herramienta, con qué argumentos, con qué razón).
• Resultados de herramientas (ok/error + data).
• Observaciones y reflexiones (con su decisión y si se cumplió el objetivo).
• Logs de confianza de claims (útil para calibración, análisis y UI).

Eso permite depurar el «por qué» de un resultado, no solo el «qué».

¿Para quién?

• Para quien construye agentes y necesita instrumentación real.
• Para equipos que quieren convertir investigación asistida en un flujo repetible.
• Para quien puede iterar con un LLM local (Ollama) y mantener costos/control.

La idea apunta a ser un entorno de desarrollo para agentes: con ejecución guiada por fases, herramientas, sub-agentes, evaluación, persistencia y memoria. Esto lo convierte en una base sólida para pasar de prototipo a sistema operable conforme se extiendan sus cualidades y comportamientos.

Lo que se podría explorar

• Monitorear y extender el ciclo de la estrategia ReAct
  Profundizar en la observabilidad del ciclo: Plan → Act → Reflect → Observe, incorporando métricas, checkpoints y análisis de fallos para mejorar la toma de decisiones del agente.
  
• Evaluar ejecuciones resumables, stoppeables y clonables
  Analizar diseños que permitan pausar, reanudar o bifurcar ejecuciones de agentes, facilitando depuración, experimentación controlada y reutilización de contextos.
  
• Desacoplar la ejecución del navegador
  Investigar el uso de workers, colas o runtimes persistentes para que los agentes continúen ejecutándose de forma confiable incluso cuando el usuario cierre el navegador o pierda conexión.
  
• Explorar casos de uso con Convex en lugar de Supabase
  Comparar ambos enfoques desde la perspectiva de agentes: reactividad, jobs de larga duración, consistencia del estado y simplicidad operativa en flujos agenticos.