Crear un agente de IA local: arquitectura y herramientas recomendadas

#¿Por qué construir un agente de IA local?

Un agente de IA local responde a tres necesidades que la nube gestiona mal. Primero, la confidencialidad: cuando un agente lee tus correos, consulta tu base de datos o recorre tus archivos, cada llamada enviada a una API externa supone una posible fuga de datos. En local, el contexto nunca sale de la máquina. Después, el coste: un agente encadena decenas de llamadas al modelo para una sola tarea, y la factura de una API de pago por uso se dispara rápidamente. Por último, la autonomía: sin límites de frecuencia de solicitudes, sin cortes de red y sin cambios de política tarifaria de un día para otro.

El precio que hay que pagar es real: un modelo local de 14B o 32B no razona con tanta precisión como los mejores modelos propietarios. Por eso, el diseño del agente —herramientas bien delimitadas, prompts estrictos y salvaguardas— importa más que en la nube. Eso es precisamente lo que abarca esta guía sobre el agente de IA local.

#Anatomía de un agente

Independientemente del framework, un agente de IA local se basa siempre en los mismos componentes. Comprenderlos permite elegir tus herramientas con conocimiento de causa, en lugar de seguir un tutorial a ciegas.

El modelo (razonamiento)

El LLM que decide la acción siguiente. Debe gestionar las llamadas a herramientas de forma fiable: Qwen 3.x, Granite 4.x o Mistral Small son buenos candidatos para ejecutarlos en local.

Las herramientas (acciones)

Funciones de Python que el agente puede llamar: leer un archivo, consultar una API, realizar una búsqueda y escribir en una base de datos. Cada herramienta se describe mediante un esquema JSON que el modelo lee.

Memoria (estado)

Corto plazo (el historial de la conversación actual) y largo plazo (un vector store que persiste entre sesiones). Este es el papel del RAG, detallado más abajo.

El orquestador (bucle)

El código que encadena el razonamiento, la llamada a una herramienta y la observación hasta que se cumple la condición de parada. Es lo que proporciona un framework como CrewAI o AutoGen.

El planificador (estrategia)

La lógica que divide un objetivo complejo en subtareas ordenadas. Puede ser explícita (un agente planificador dedicado) o implícita (el modelo razona paso a paso).

Un agente mínimo se basta con un modelo, dos o tres herramientas y un bucle. Un sistema avanzado añade memoria persistente, planificación en múltiples etapas y varios agentes especializados que colaboran. Empieza por algo sencillo: la mayoría de las tareas no justifican un equipo de diez agentes.

#Requisitos previos y pila recomendada

La pila de referencia para un agente de IA local se compone de tres capas: Ollama para servir el modelo, un framework de orquestación en Python y un modelo capaz de realizar llamadas a herramientas. Ollama escucha por defecto en http://localhost:11434 y expone un endpoint compatible con OpenAI, lo que simplifica la integración con la mayoría de los frameworks.

GPU / VRAM

Un agente razona mejor con un modelo de 14B+ que con uno de 7B. Calcula unos 9 GB de VRAM para un modelo de 14B en Q4_K_M y unos 19 GB para uno de 32B. Una RTX 4070 de 12 GB ejecuta cómodamente un modelo de 14B; una RTX 4090 de 24 GB o un Mac M4 Pro apuntan a modelos de 32B.

Modelo

Elige un modelo conocido por su fiabilidad en las llamadas a herramientas. La calidad del function calling importa más que el tamaño bruto: un 14B riguroso supera a un 32B que inventa argumentos.

Python 3.10+

CrewAI y AutoGen son bibliotecas de Python. Trabaja en un entorno virtual dedicado para evitar conflictos de dependencias.

Quantization

Q4_K_M ofrece un buen equilibrio como opción predeterminada. Sube a Q5_K_M o Q8_0 si el modelo comete errores de razonamiento y la VRAM lo permite.

# 1. Vérifier qu'Ollama tourne
curl http://localhost:11434/api/tags

# 2. Récupérer un modèle capable de tool calling
ollama pull qwen3:14b

# 3. Environnement Python isolé
python -m venv .venv && source .venv/bin/activate
pip install crewai crewai-tools

#CrewAI o AutoGen: ¿cuál elegir?

Los dos frameworks orquestan agentes, pero con filosofías diferentes. La elección adecuada depende de tu tarea, no de una clasificación absoluta.

CrewAI

Orientado al trabajo en «equipo»: se definen agentes con un rol, un objetivo y herramientas, y luego se les asignan tareas ordenadas. Enfoque declarativo, legible, ideal para pipelines empresariales (buscar → redactar → revisar). Memoria RAG integrada.

AutoGen

Orientado a la «conversación»: los agentes dialogan entre sí hasta converger. Más flexible para los problemas abiertos y el razonamiento colaborativo, pero requiere más ajustes para mantenerse dentro de unos límites en local. La v0.4 se conecta a Ollama a través de su cliente compatible con OpenAI.

Cuándo optar por la sencillez

Para un solo agente con unas pocas herramientas, basta un framework ligero (o LangChain). CrewAI y AutoGen cobran pleno sentido cuando hay varios roles o una orquestación no trivial.

from crewai import Agent, Task, Crew, LLM

# CrewAI passe par LiteLLM : préfixe 'ollama/' + base_url local
llm = LLM(
    model="ollama/qwen3:14b",
    base_url="http://localhost:11434",
)

chercheur = Agent(
    role="Analyste documentaire",
    goal="Extraire les faits clés des documents fournis",
    backstory="Expert méthodique, ne répond que sur la base des sources.",
    llm=llm,
    verbose=True,
)

tache = Task(
    description="Résume les 3 points essentiels du rapport fourni.",
    expected_output="Une liste à puces de 3 points, sourcés.",
    agent=chercheur,
)

equipe = Crew(agents=[chercheur], tasks=[tache])
print(equipe.kickoff())

from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent

# Endpoint OpenAI-compatible d'Ollama : /v1
client = OpenAIChatCompletionClient(
    model="qwen3:14b",
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignore par Ollama, mais requis par le client
    model_info={
        "function_calling": True,
        "json_output": True,
        "vision": False,
        "family": "unknown",
    },
)

agent = AssistantAgent(name="assistant", model_client=client)

#Construir el agente paso a paso

Este es el procedimiento para pasar de un modelo en bruto a un agente de IA local que realice una tarea real. El orden importa: cada paso valida el anterior.

1. 01
   Definir el objetivo y la condición de finalización

   Escribe en una frase qué debe producir el agente y cómo se sabe que ha terminado. Un objetivo vago («ayúdame») genera un agente que da vueltas sin avanzar; un objetivo delimitado («clasifica estas 20 facturas por proveedor en un CSV») genera un agente controlable.
2. 02
   Dividir en herramientas atómicas

   Cada acción externa se convierte en una función de Python con un nombre explícito, argumentos tipados y una docstring clara: esa es la descripción que lee el modelo. Prefiere varias herramientas pequeñas y precisas a una herramienta grande que intente hacerlo todo.
3. 03
   Redactar el prompt del sistema

   Define el rol, las herramientas disponibles y las reglas (nunca inventar, siempre citar la fuente, detenerse en caso de duda). En local, un prompt estricto compensa la menor sofisticación del razonamiento del modelo.
4. 04
   Conectar el bucle de orquestación

   Deja que el framework gestione el ciclo razonar → actuar → observar, pero fija un límite de iteraciones (por ejemplo, 10) para evitar que un agente atascado consuma recursos indefinidamente. Es una medida de protección esencial cuando el agente funciona de forma autónoma.
5. 05
   Añadir memoria

   Conecta un vector store para la memoria a largo plazo si el agente debe recordar entre sesiones (ver sección siguiente). Sin esta necesidad, el historial de conversación es suficiente.
6. 06
   Probar en casos reales e iterar

   Inicia el agente con entradas variadas, lee los logs de ejecución (verbose), corrige los prompts y las descripciones de herramientas. El 80 % del trabajo de un agente local se realiza aquí, no en el código inicial.

#Memoria a largo plazo con RAG

Un agente sin memoria empieza de cero en cada sesión. La memoria a largo plazo se basa en el mismo principio que el RAG (Retrieval-Augmented Generation): se almacena la información en forma de vectores en una base de datos y se recupera la más pertinente cuando se necesita para reintroducirla en el contexto.

Embeddings locales

Genera los vectores con un modelo de embedding servido por Ollama (por ejemplo, nomic-embed-text o mxbai-embed-large): los datos que se deben memorizar no salen de la máquina, lo que es coherente con el objetivo de privacidad.

Almacenamiento vectorial

ChromaDB es la opción predeterminada en local: ligero, persistente en disco e integrado de forma nativa en CrewAI. Para volúmenes mayores, Qdrant autoalojado toma el relevo.

Memoria integrada de CrewAI

CrewAI ofrece una memoria lista para usar (memoria a corto plazo, a largo plazo y de entidades) que se puede configurar para usar un embedder de Ollama, sin tener que montar manualmente el pipeline RAG.

from crewai import Crew

equipe = Crew(
    agents=[chercheur],
    tasks=[tache],
    memory=True,  # active la memoire long terme (ChromaDB sous le capot)
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

#Planificación de tareas

La planificación es la capacidad del agente para dividir un objetivo complejo en etapas ordenadas antes de actuar. Sin ella, un modelo local tiende a lanzarse a la primera acción que se le ocurre y a perderse. Coexisten dos enfoques.

Planificación implícita (ReAct)

El modelo razona en voz alta paso a paso, elige una acción, observa y luego vuelve a planificar. Es sencillo de implementar, pero frágil con modelos pequeños que pierden el hilo tras unos pocos turnos.

Planificación explícita

Un agente (o una primera tarea) dedicado a la planificación genera una lista de pasos, que luego son tratados por agentes de ejecución. Más robusto localmente: se separa «pensar» y «hacer», lo que reduce la carga de cada llamada.

Descomposición jerárquica

Para tareas largas, CrewAI permite un proceso jerárquico en el que un agente «manager» delega y supervisa. Potente, pero debe reservarse para casos que lo justifiquen — la coordinación cuesta tokens.

Regla práctica para el uso en local: cuanto más pequeño sea el modelo, más explícita debe ser la planificación y más limitado el alcance de cada paso. Un 14B que resuelve una microtarea bien delimitada es más fiable que un 32B al que se le asigna un objetivo vago.

#Seguridad de los datos

Ejecutarlo todo en local elimina la fuga de información hacia API de terceros, pero un agente autónomo introduce sus propios riesgos: ejecuta acciones, a veces destructivas, basándose en texto generado. La confidencialidad no elimina la necesidad de salvaguardas.

Principio del menor privilegio

Dale al agente solo las herramientas estrictamente necesarias. Un agente que no necesita escribir en el disco no debe disponer de ninguna herramienta de escritura: es la primera barrera contra los daños.

Validación humana de acciones sensibles

Para todo lo que sea irreversible (borrar, enviar, pagar, modificar una base de datos), incluye una confirmación manual. La autonomía total solo se justifica en acciones seguras y reversibles.

Aislamiento de la ejecución de código

Si el agente ejecuta código, hazlo dentro de un contenedor o un entorno aislado (sandbox), nunca directamente en la máquina anfitriona. Un prompt malicioso introducido en un documento puede manipular a un agente (inyección de prompt).

Registro de acciones

Registra cada llamada a una herramienta y cada decisión. En caso de comportamiento inesperado, la traza es tu único medio para entender lo que realmente hizo el agente.

#Consejos y solución de problemas

El agente entra en un bucle sin detenerse nunca

Comprueba la condición de parada y el límite de iteraciones. A menudo el objetivo es demasiado vago o el agente no reconoce que ha terminado: especifica claramente el resultado esperado en el prompt.

Llamadas a herramientas mal formadas

El modelo inventa argumentos o omite campos. Simplifica los esquemas de herramientas, aumenta un nivel de cuantización (Q4 → Q5) o pasa a un modelo más confiable en llamadas a herramientas.

Respuestas lentas con varios agentes

Cada agente es una llamada completa al modelo. En local, reduce el número de agentes, acorta los prompts de sistema y verifica que el modelo quepa completamente en VRAM (de lo contrario, la descarga parcial a la CPU desploma la velocidad de generación).

La memoria no recupera nada relevante

Modelo de embeddings inadecuado o fragmentos demasiado grandes o demasiado pequeños. Comprueba que el generador de embeddings de Ollama esté funcionando y ajusta el tamaño de los fragmentos almacenados.

Conexión rechazada en :11434

Ollama no está ejecutándose o está escuchando en otra interfaz. Confírmalo con «curl http://localhost:11434/api/tags» y comprueba la base_url pasada al framework.

#Para ir más allá

Esta guía establece la arquitectura; estos tutoriales profundizan en la implementación concreta de cada componente:

Multiagentes con CrewAI

« CrewAI + Ollama: coordinar varios agentes de IA localmente » detalla la implementación de un equipo de agentes especializados, con roles y tareas definidas.

Un agente en Python de A a Z

« Crear un agente IA local en Python con LangChain y Ollama » construye paso a paso un agente capaz de llamar a herramientas y leer archivos.

La pieza de memoria (RAG)

« RAG en local con ChromaDB y Ollama: tutorial en Python » cubre el pipeline completo embeddings → búsqueda → respuesta, núcleo de la memoria a largo plazo.