Construyendo agentes de IA con LLM APIs: arquitectura y código

Un agente de IA no es un chatbot con function calling. Es un sistema que percibe, razona, actúa y aprende —autónomamente, a través de múltiples pasos, con estado que persiste entre acciones. La guía de Anthropic para construir agentes efectivos es el mejor punto de partida para entender los patrones de arquitectura de agentes. Un chatbot responde tu pregunta. Un agente reserva tu vuelo, reprograma tus reuniones y actualiza el Slack de tu equipo mientras estás en el aire.

Todos están construyendo agentes en 2026. Muchos se rompen en producción —en bucles infinitos, llamando a las herramientas equivocadas, olvidando lo que hacían hace tres pasos. Esta guía cubre la arquitectura que previene esas fallas. Desde el bucle de llamada de herramientas hasta los sistemas de memoria y la orquestación multi-agente, cada sección tiene código funcional. Al final, tendrás un agente asistente de investigación funcional que puedes forkear y extender.

Qué hace a un agente de IA —y qué no

Definición. Un agente de IA tiene tres capas: un núcleo de razonamiento (el LLM), una capa de herramientas (APIs, bases de datos, ejecución de código) y una capa de memoria (conversación a corto plazo, conocimiento a largo plazo, estado de trabajo). La diferencia clave frente a una llamada simple al LLM: el agente toma decisiones autónomas en un bucle. No solo responde. Planifica, actúa, observa el resultado y decide qué hacer después.

Las tres capas:

User Query → Reasoning Core (LLM) → Decision → Tool Execution → Observation → Memory Update → Next Decision → ... → Final Response

Cuándo necesitas un agente vs. una llamada simple al LLM. Agente: tareas de múltiples pasos donde el modelo necesita recopilar información, ejecutar acciones y adaptarse según los resultados. “Investiga este tema y escribe un informe” —agente. “Resume este artículo” —llamada simple. “Depura este error, revisa los logs y abre un PR con la corrección” —agente. “Explica este mensaje de error” —llamada simple.

Si la tarea se puede completar en una llamada de API sin uso de herramientas externas, no necesitas un agente. Si la tarea requiere recopilar información de múltiples fuentes, ejecutar acciones y tomar decisiones basadas en resultados intermedios, necesitas un agente. El árbol de decisiones: ¿un paso? —llamada simple. ¿Múltiples pasos con herramientas? —agente.

El bucle de llamada de herramientas: las manos de tu agente

El bucle central del agente. Cada framework de agentes —LangChain, CrewAI, AutoGen, código puro— implementa alguna versión de esto.

import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.tokspan.com/v1",
    api_key="ts-your-key-here"
)

class Agent:
    def __init__(self, model: str, tools: list, max_iterations: int = 10):
        self.model = model
        self.tools = {t["function"]["name"]: t for t in tools}
        self.max_iterations = max_iterations
        self.memory = []  # Working memory —the agent's scratchpad

    def run(self, user_query: str) -> str:
        messages = [
            {"role": "system", "content": "You are a research assistant. Use tools to gather information, then synthesize a report."},
            {"role": "user", "content": user_query}
        ]

        for iteration in range(self.max_iterations):
            response = client.chat.completions.create(
                model=self.model,
                messages=messages,
                tools=list(self.tools.values()),
                tool_choice="auto"
            )

            msg = response.choices[0].message

            # Agent decided to respond with text —done
            if msg.content and not msg.tool_calls:
                return msg.content

            # Agent decided to call tools —execute and continue
            if msg.tool_calls:
                messages.append(msg)
                for tool_call in msg.tool_calls:
                    tool_name = tool_call.function.name
                    tool_args = json.loads(tool_call.function.arguments)
                    result = self._execute_tool(tool_name, tool_args)
                    messages.append({
                        "role": "tool",
                        "tool_call_id": tool_call.id,
                        "content": str(result)
                    })

        return "Agent reached maximum iterations without completing the task."

    def _execute_tool(self, name: str, args: dict):
        # In production: dispatch to actual functions
        print(f"Calling tool: {name}({args})")
        return f"Result from {name}"

Mejores prácticas de definición de herramientas. La descripción de una herramienta es un prompt —escríbela con claridad. Incluye ejemplos de cuándo usar cada herramienta. Restringe los parámetros estrictamente —enums en lugar de strings de texto libre. Haz que las herramientas sean idempotentes —llamar la misma herramienta dos veces con los mismos parámetros debe producir el mismo resultado. Cuando falla la ejecución de una herramienta, envía el mensaje de error de vuelta al modelo —a menudo puede recuperarse probando diferentes parámetros.

Para la comparación completa de function calling entre proveedores —incluyendo implementaciones de OpenAI vs. Anthropic vs. Google vs. DeepSeek— consulta nuestra guía de function calling entre proveedores.

Manejo de errores en el bucle. La ejecución de la herramienta falla —envía el error al modelo —el modelo decide: reintentar con diferentes parámetros, probar una herramienta diferente o informar al usuario. El modelo es sorprendentemente bueno recuperándose de errores de herramientas —pero solo si le envías el error de vuelta. Tragar silenciosamente las fallas de herramientas produce agentes que fallan misteriosamente.

Sistemas de memoria: enseñando a tu agente a recordar

Un agente sin memoria es un pez dorado —olvida todo entre pasos. Tres tipos de memoria, cada uno con un propósito específico.

Memoria a corto plazo —historial de conversación. El arreglo de messages. Qué dijo el usuario, qué hizo el agente, qué devolvieron las herramientas. Gestionado como una ventana deslizante —cuando el historial se acerca al límite de contexto del modelo, recorta los mensajes más antiguos o resúmelos. Disparador de resumen: cuando los tokens totales superan el 80% de la ventana de contexto, resume el 50% más antiguo de la conversación en un solo mensaje del sistema.

Memoria a largo plazo —almacén vectorial. Interacciones pasadas, preferencias del usuario, hechos aprendidos —almacenados como embeddings en una base de datos vectorial, recuperados por similitud con la consulta actual. Implementación: incrusta cada interacción significativa —almacena en ChromaDB o Pinecone —en cada nueva consulta, recupera las top 3–5 interacciones pasadas más similares —incluye en el prompt del sistema como contexto. Esta es la diferencia entre “el agente sabe de qué hablamos la semana pasada” y “el agente empieza cada conversación desde cero”.

Memoria de trabajo —el bloc de notas. El plan actual del agente, resultados intermedios e hipótesis —almacenados como un objeto JSON actualizado en cada iteración del bucle. ¿Qué está tratando de lograr el agente ahora mismo? ¿Qué ha intentado? ¿Qué aprendió? El bloc de notas es el “hilo de pensamiento” del agente —externalizado para que sobreviva a través de las llamadas de herramientas y pueda inspeccionarse para depurar.

Arquitectura de memoria. Las tres memorias alimentan al agente en cada iteración del bucle: historial de conversación (qué pasó) + memorias a largo plazo recuperadas (qué es relevante del pasado) + memoria de trabajo (qué estamos haciendo ahora). El LLM sintetiza estas en la siguiente decisión.

Sistemas multi-agente: cuándo un agente no es suficiente

Un solo agente con 15 herramientas toma malas decisiones —demasiadas opciones, demasiado contexto, precisión de selección degradada. La solución: agentes especializados, cada uno con un conjunto de herramientas enfocado y una responsabilidad clara.

Patrones de orquestación:

• Supervisor/trabajador. Un agente orquestador asigna tareas a agentes trabajadores especializados. El supervisor no hace el trabajo —coordina. “Investiga este tema” —el supervisor despacha a un agente investigador, un agente analista y un agente escritor —el supervisor compila los resultados.
• Debate entre pares. Dos agentes argumentan lados opuestos de una decisión y luego convergen. “¿Deberíamos aprobar este préstamo?” —el agente A argumenta sí, el agente B argumenta no —ambos revisan los argumentos del otro —producen una recomendación conjunta.
• Pipeline secuencial. La salida del agente A es la entrada del agente B. “Analiza esta base de código” —el analizador de código genera un informe —el buscador de bugs usa el informe para identificar problemas —el generador de correcciones propone soluciones.

Comunicación multi-agente. Usa un bus de mensajes compartido —cada agente publica su salida como un mensaje estructurado con {from: "researcher", to: "analyst", content: "...", type: "report"}. Esto hace que el grafo de interacción de agentes sea observable y depurable. Cuando algo sale mal, puedes rastrear exactamente qué agente produjo qué salida y por qué.

Costo de lo multi-agente. Cada agente hace sus propias llamadas al LLM. Un sistema de tres agentes hace 3 veces las llamadas de API de un sistema de un agente. Mitigación: usa modelos baratos para agentes trabajadores (DeepSeek V4 Flash, $0.14/$0.28) y reserva modelos frontier (Claude Opus, GPT-5.5) para el orquestador. El orquestador toma las decisiones de alto riesgo. Los trabajadores ejecutan.

Aquí hay un pipeline de investigación concreto de 3 agentes que puedes desplegar hoy. El agente Investigador usa Gemini 3.1 Pro ($2.00/M de tokens de entrada) con exactamente dos herramientas —búsqueda web y recuperación de documentos— para que nunca se pierda en parálisis de selección de herramientas. Su salida es un brief JSON estructurado: {sources: [...], key_facts: [...], gaps: [...]}.

El agente Escritor ejecuta GPT-5.5 ($5.00/M de entrada) para transformar ese brief en un borrador, usando solo una herramienta de formato. El agente Revisor usa Claude Opus 4.8 ($5.00/M de entrada) para verificar cada afirmación contra las fuentes originales, marcar alucinaciones y devolver una revisión puntuada: {score: 1-10, issues: [...], corrected_draft: "..."}. El costo por tarea va de $0.12–0.35 —el Investigador consume ~40% de los tokens, el Escritor ~35%, el Revisor ~25%.

El bus de mensajes es un simple dict de Python pasado entre agentes —no se requiere framework. Registra {timestamp, from_agent, to_agent, payload_type, token_count} en cada transición y podrás rastrear cada traspaso cuando algo se rompa.

Depurando fallas de agentes

Los agentes fallan de maneras predecibles. Los tres modos de falla más comunes: bucles infinitos (el agente llama herramientas pero nunca converge), selección incorrecta de herramientas (el modelo elige una herramienta irrelevante con parámetros incorrectos) y desbordamiento de contexto (el historial de conversación excede la ventana de contexto del modelo, descartando silenciosamente mensajes anteriores). Cada uno tiene un patrón de diagnóstico.

Para bucles infinitos, registra las acciones del agente para detectar repetición —si la misma herramienta se llama con los mismos parámetros tres veces seguidas, el agente está atascado. Intervención: inyecta un mensaje del sistema que diga “Has llamado {tool} con {args} varias veces. El resultado no ha cambiado. Intenta un enfoque diferente o informa lo que tienes hasta ahora”.

Para selección incorrecta de herramientas, registra el nombre de la herramienta, los parámetros y el resultado en cada iteración —verás patrones. Un agente que llama search_web cuando debería llamar query_database revela una descripción de herramienta que necesita reescritura, no un problema de modelo.

Para desbordamiento de contexto, rastrea total_tokens en cada iteración usando el campo usage de la API. Cuando los tokens superen el 80% del límite de contexto —1M para GPT-5.5, 200K para Claude Opus— resume el 50% más antiguo de los mensajes antes de la siguiente iteración. El error de desarrollador más común: nunca verificar response.usage.total_tokens hasta que el agente empiece a producir salida incoherente, sin saber que el contexto se truncó silenciosamente hace cinco iteraciones.

El logging estructurado es la herramienta de depuración más efectiva que tienes. Como mínimo, registra por iteración: {iteration, model, tool_calls, tokens_used, latency_ms, error}. Después de 20 ejecuciones del agente tendrás suficientes datos para identificar qué modo de falla te muerde con más frecuencia.

También notarás regresiones de rendimiento inmediatamente —una llamada de herramienta que normalmente toma 200ms de repente tomando 2 segundos es una señal antes de que se convierta en un incidente.

¿Qué modelo para qué rol de agente?

Rol del agente	Mejor modelo	Por qué
Orquestador	GPT-5.5	Uso de herramientas más confiable, mejor llamada paralela de herramientas
Agente de código	Claude Opus 4.8	El mejor SWE-bench, el mejor razonamiento arquitectónico
Agente de investigación	Gemini 3.1 Pro	Contexto de 2M para análisis de documentos, multimodal
Trabajador eficiente en costos	DeepSeek V4 Pro	92% en HumanEval a $0.44/M de salida
Agente de escritura	GPT-5.5	Mejor calidad de prosa y rango estilístico

La ventaja de la plataforma de agregación: accede a los cinco modelos con una sola API key. Enruta cada rol de agente a su modelo óptimo. Cambia modelos sin cambiar el código del agente. El orquestador, el agente de código, el agente de investigación y los trabajadores usan el mismo SDK de OpenAI —solo diferentes parámetros model.

Para una discusión arquitectónica más profunda sobre enrutar diferentes tareas a diferentes modelos —un patrón que todo sistema de agentes de producción usa— consulta nuestra guía para usar múltiples modelos de IA en una app.

FAQ

¿Necesito un framework como LangChain para construir agentes?

No. El bucle central del agente es ~50 líneas de Python —el código en este artículo es un agente funcional completo. Los frameworks agregan conveniencias (herramientas preconstruidas, trazado, backends de memoria) y complejidad (capas de abstracción, árboles de dependencias, cambios que rompen entre versiones). Empieza con código puro. Agrega un framework solo cuando tengas un problema específico que resuelva. Los desarrolladores que saltan directo a LangChain a menudo se arrepienten —pasan más tiempo depurando el framework que construyendo el agente.

¿Qué modelo es mejor para agentes?

GPT-5.5 para confiabilidad de uso de herramientas —es el más consistente al llamar la herramienta correcta con los parámetros correctos. Claude Opus para razonamiento complejo de múltiples pasos donde la profundidad importa más que la confiabilidad. Gemini para tareas de contexto largo. DeepSeek V4 Pro para agentes eficientes en costos. La mayoría de los sistemas de agentes de producción usan 2–3 modelos: un orquestador confiable (GPT-5.5), un especialista en razonamiento profundo (Claude Opus) para pasos complejos y un trabajador eficiente en costos (DeepSeek) para tareas simples de alto volumen.

¿Cómo evito que mi agente haga un bucle infinito?

Tres salvaguardas. Configura max_iterations (10–20 es razonable para la mayoría de las tareas). Rastrea la finalización de la tarea —si las últimas 3 acciones del agente no produjeron información nueva, está atascado; termina y devuelve un resultado parcial. Tope de presupuesto por sesión de agente —un límite de gasto de $0.50 atrapa bucles infinitos antes de que se conviertan en problemas de $50 (consulta nuestra guía de gestión de claves y control de presupuesto para configurar topes de gasto y límites de tasa como barreras de protección). Siempre ten un timeout + respuesta de respaldo elegante.

¿Cuánto cuesta ejecutar agentes de IA?

Agente simple (3–5 llamadas de herramientas): $0.05–0.20 por tarea usando DeepSeek V4 Pro. Multi-agente complejo (10–20 llamadas): $0.50–2.00 por tarea con modelos mixtos. Usa enrutamiento basado en costos: tareas simples —modelos baratos, tareas complejas —modelos frontier. El costo por tarea debe medirse y optimizarse como cualquier otro costo de infraestructura.

¿Cómo pruebo la confiabilidad del agente antes de desplegar a producción?

Construye un banco de pruebas de evaluación con 20–50 casos de prueba etiquetados a mano que cubran el rango de tareas esperado de tu agente. Ejecuta cada caso 5 veces —el comportamiento del agente es no determinista, una sola pasada no prueba nada. Mide dos métricas: tasa de finalización de tareas (¿produjo el agente una salida válida?) y precisión de selección de herramientas (¿llamó las herramientas correctas en el orden correcto?).

Una tasa de finalización por debajo del 85% significa que tus prompts o descripciones de herramientas necesitan trabajo. Para sistemas multi-agente, agrega una tercera métrica: corrección de traspaso —¿recibió cada agente el formato de entrada esperado del agente ascendente? Un mal traspaso se convierte en fallas en cascada aguas abajo.

¿Cuándo debo usar un solo agente vs. un sistema multi-agente?

Empieza con un solo agente. Agrega un segundo agente solo cuando llegues a uno de tres umbrales: la lista de herramientas excede 8–20 funciones (la precisión de selección de herramientas se degrada por encima de este número según los benchmarks de function calling de OpenAI), la tarea tiene subtareas claramente separables con diferentes requisitos de experiencia (investigación vs. escritura vs. revisión), o necesitas verificación de seguridad independiente (un agente revisor que verifica la salida del agente principal).

La arquitectura multi-agente prematura es el error de sobre-ingeniería más común en el desarrollo de agentes —agrega latencia, costo y complejidad de depuración sin beneficio proporcional para flujos simples.

Paso uno: copia el bucle de agente de 50 líneas de este artículo, cambia tus propias definiciones de herramientas, configura max_iterations a 10 y despliega contra una tarea interna no crítica —algo de bajo riesgo donde una falla sea una oportunidad de aprendizaje, no un incidente. Observa los logs. Ve dónde se atasca. Agrega memoria cuando olvide contexto. Agrega multi-agente cuando la lista de herramientas se vuelva difícil de manejar. La única forma de aprender qué se rompe es enviar algo y observar.

El bucle de agente de 50 líneas anterior es un punto de partida funcional. Cuando estés listo para asignar cada rol de agente a su modelo óptimo —la tabla de mapeo de este artículo es una referencia— un endpoint de agregación te permite cambiar el modelo por agente editando un parámetro de cadena. Sin SDKs por proveedor, sin relaciones de facturación separadas. Despliega el bucle contra una tarea interna de bajo riesgo primero, observa los logs e itera desde allí.