build ai agents from scratch

Tiempo estimado de lectura: 12 minutos

Conclusiones clave

• Un agente de IA es más que un chatbot: interpreta objetivos, decide acciones, usa herramientas, observa resultados y repite hasta completar la tarea.
• La arquitectura esencial: modelo + instrucciones + herramientas + estado + bucle de control + guardrails + evaluación.
• Empieza simple: construye primero la versión mínima (nivel 1) y añade orquestación, memoria y controles según la necesidad.
• La seguridad es crítica: aplica principio de menor privilegio, validación de llamadas a herramientas y aprobación humana para acciones sensibles.
• Recursos recomendados: guía de Anthropic — Building Effective Agents, documentación de OpenAI — Agents y repositorios «agents from scratch» en GitHub.

Tabla de contenidos

• Introducción
• Resumen ejecutivo
• ¿Qué significa «desde cero»?
• Componentes centrales de un agente
• Bucle de orquestación e implementación mínima
• Arquitecturas comunes
• Memoria y Retrieval-Augmented
• Seguridad y evaluación
• Frameworks y plataformas
• Secuencia recomendada (pasos prácticos)
• Errores comunes
• Recursos para aprender más
• Preguntas frecuentes (FAQ)

Introducción

Hoy vamos a explorar cómo construir agentes de IA desde cero. *Un agente* es una aplicación que piensa, actúa con herramientas y gestiona estado de forma iterativa. Esta guía resume prácticas, arquitecturas y guardrails extraídos de investigación y guías de la industria.

Resumen ejecutivo

En la práctica, un agente de IA debe:

• Interpretar un objetivo.
• Decidir la siguiente acción.
• Llamar a herramientas cuando sea necesario.
• Observar y validar resultados.
• Iterar hasta completar o pedir intervención humana.

¿Qué significa «desde cero»?

Hay tres niveles prácticos:

• Nivel 1: Sin framework: tú escribes el bucle, validas llamadas, ejecutas funciones y devuelves resultados.
• Nivel 2: Capa propia de orquestación: estado, logging, permisos, reintentos y aprobaciones humanas.
• Nivel 3: Construir/entrenar el modelo. En la mayoría de casos no es necesario: usa modelos hospedados o locales y céntrate en herramientas, orquestación y seguridad.

Componentes centrales de un agente

1) El modelo

El modelo hace razonamiento, planificación y selección de herramientas. Busca uno que soporte: salida estructurada, llamadas a funciones, contexto largo y streaming si hace falta. La elección depende de la tarea y del coste/latencia aceptables.

2) Instrucciones (system prompt)

Define rol, límites, formato de salida, cuándo usar herramientas, cómo manejar incertidumbre y cuándo requerir aprobación humana. Recuerda: los prompts no son un sustituto de controles de seguridad en el código.

3) Herramientas

Las herramientas son APIs o funciones: búsqueda, DB, calculadora, navegación, ejecución de código, etc. Cada herramienta debe incluir nombre, descripción y esquema de parámetros. Diseñar buenas descripciones evita uso indebido.

Ejemplo de esquema de herramienta (JSON):

{
  "name": "get_weather",
  "description": "Obtener el clima actual para una ciudad",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "Ciudad y país"}
    },
    "required": ["city"],
    "additionalProperties": false
  }
}

4) Bucle de orquestación

Flujo básico:

• Recibir petición del usuario.
• Inicializar estado.
• Iterar: preguntar al modelo, ejecutar herramientas solicitadas, inyectar resultados; si la respuesta es final, devolverla.

OpenAI resume el flujo en cinco pasos: enviar petición con herramientas → recibir llamada a herramienta → ejecutar función → devolver resultado al modelo → recibir respuesta final o nuevas llamadas. (Fuente: OpenAI — Function Calling).

Implementación mínima (pseudocódigo)

def run_agent(user_message, max_steps=8):
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_message}
    ]

    for step in range(max_steps):
        response = model_call(messages=messages, tools=tool_schemas(TOOLS))
        messages.extend(response.output_items)

        if response.is_final:
            return response.text

        for tool_call in response.tool_calls:
            name = tool_call.name
            arguments = tool_call.arguments

            if name not in TOOLS:
                messages.append({"role": "tool", "content": "Error: herramienta desconocida"})
                continue

            try:
                validate(arguments, TOOLS[name]["schema"])
                if requires_approval(name, arguments):
                    result = request_human_approval(name, arguments)
                else:
                    result = TOOLS[name]["function"](**arguments)

            except Exception as error:
                result = {"error": "Falló la ejecución de la herramienta", "details": str(error)}

            messages.append({"role": "tool", "content": json.dumps(result)})

    return "No pude completar la tarea dentro del número máximo de pasos."

Este ejemplo es didáctico: la versión de producción necesita autenticación, autorización, timeouts, reintentos, validación, manejo de PII y observabilidad.

Arquitecturas comunes de agentes

• Agente único con herramientas: simple y efectivo para asistentes.
• Prompt chaining: encadenar pasos cuando la tarea es predecible.
• Routing: enrutador que determina qué especialista usar (útil para soporte).
• Orquestador–trabajador: delega subtareas a workers especializados.
• Plan-and-execute y ReAct: plan visible y alternancia razonamiento/acción.

Memoria y Retrieval-Augmented

Tipos de memoria:

• Memoria de trabajo (estado actual).
• Memoria de sesión (preferencias del usuario).
• Memoria a largo plazo (perfiles, hechos organizativos).
• Conocimiento externo (documentos, embeddings, búsquedas).

En Retrieval-Augmented Agents, decide cuándo recuperar, filtra resultados, aporta evidencia al modelo y exige citas cuando sea necesario. Trata documentos externos como no confiables y protege contra prompt injection.

Seguridad, guardrails y evaluación

Riesgos típicos: prompt injection, divulgación de información sensible, envenenamiento de datos, excesiva agencia y fugas del system prompt. OWASP publica guías relevantes: OWASP Top 10 for LLM Applications y OWASP Top 10 for Agentic Applications.

Controles esenciales:

• Principio de menor privilegio.
• Validación de cada llamada (nombre, tipos, valores, autorización).
• Aprobación humana para acciones críticas.
• Sandboxes para ejecución de código y navegación.
• Limitar iteraciones, tokens, tiempo y coste.
• Registrar trazas sin incluir secretos.

Pruebas y métricas: tests unitarios, simulaciones adversariales, tasas de completado, precisión de selección de herramienta, latencia p95, coste por tarea y mediciones de seguridad (e.g., resistencia a prompt injection).

Frameworks y plataformas

Algunas opciones relevantes:

• OpenAI — Agents y Responses
• Anthropic — Building Effective Agents
• LangChain — docs y herramientas de orquestación.
• Microsoft Agent Framework
• Implementaciones locales y educativas en GitHub: agents-from-scratch.

Secuencia recomendada para construir un agente (pasos prácticos)

1. Definir la tarea: usuario, objetivo, inputs, salida esperada y métricas.
2. Construir una línea base no-agent (determinista) para comparar.
3. Añadir una llamada al modelo con control.
4. Incorporar una o dos herramientas estrechas con esquemas estrictos.
5. Implementar el bucle: validación, límites de iteración y manejo de errores.
6. Agregar memoria si hace falta y retrieval con control de acceso.
7. Añadir acciones de escritura solo con aprobación humana y separación de permisos.
8. Desplegar gradualmente con feature flags, límites de gasto y escalado humano.

Errores comunes a evitar

• Confundir un chatbot con un agente: sin herramientas ni bucle no es un agente.
• Dar acceso excesivo a sistemas (shell, SQL) sin controles.
• Confiar en prompts como mecanismo de seguridad.
• No limitar iteraciones o tokens y permitir gasto no acotado.
• No probar escenarios adversariales ni registrar trazabilidad.

Recursos para aprender más

• Anthropic — Building Effective Agents
• OpenAI — Agents y Function Calling
• Microsoft — Agent Framework
• LangChain — docs
• GitHub — agents-from-scratch
• Manning — Build an AI Agent From Scratch (libro)

Conclusión

La clave para construir agentes de IA es empezar simple, diseñar herramientas claras, aplicar controles de seguridad y medir cada cambio. La autonomía sin límites suele ser más peligrosa que útil: prioriza la seguridad, la trazabilidad y la intervención humana donde importe.

Preguntas frecuentes (FAQ)