Crear agente de IA local: Ollama, herramientas y privacidad

Para crear un agente de IA local instalas un programa que corre modelos abiertos en tu equipo (el más sencillo es Ollama), descargas un modelo que soporte llamadas a herramientas (por ejemplo, de las familias Llama, Qwen o Mistral) y escribes un pequeño programa que le da al modelo funciones que puede usar: leer archivos, consultar una base de datos, buscar en tus documentos. Todo corre en tu computadora o servidor y tus datos no salen de ahí. Aquí tienes el paso a paso, código y qué esperar del rendimiento.

Cuándo conviene un agente local

• Privacidad: datos de clientes, contratos, expedientes, información fiscal que no quieres mandar a un tercero.
• Sin pago por uso: tareas repetitivas de mucho volumen (clasificar miles de documentos).
• Sin internet o con internet inestable.

Cuándo no conviene: si necesitas el mejor razonamiento posible, respuestas rápidas en un equipo modesto, o no tienes quién mantenga el equipo.

Paso 1: instalar Ollama y un modelo

1. Descarga Ollama desde ollama.com (Windows, Mac, Linux).
2. Descarga y prueba un modelo:

ollama pull llama3.2      # modelo pequeño, buen punto de partida
ollama run llama3.2       # chat en la terminal; escribe /bye para salir

3. En la biblioteca de Ollama filtra por modelos con soporte de tools (herramientas). Los modelos más grandes razonan mejor pero piden más memoria.

Alternativas a Ollama: LM Studio (interfaz gráfica) o llama.cpp (más técnico). Todos exponen una API local.

Paso 2: un agente con herramientas en Python

Ollama expone una API compatible con la de OpenAI en http://localhost:11434/v1, así que puedes usar la librería openai apuntando a tu equipo:

pip install openai

# agente_local.py
import json
from pathlib import Path
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
MODELO = "llama3.2"  # cualquier modelo descargado que soporte tools

def listar_facturas() -> str:
    return ", ".join(p.name for p in Path("facturas").glob("*.xml"))

def leer_factura(nombre: str) -> str:
    ruta = Path("facturas") / Path(nombre).name  # evita salir de la carpeta
    return ruta.read_text(encoding="utf-8")[:4000]

FUNCIONES = {"listar_facturas": listar_facturas, "leer_factura": leer_factura}
TOOLS = [
    {"type": "function", "function": {"name": "listar_facturas",
     "description": "Lista los archivos XML de facturas disponibles.",
     "parameters": {"type": "object", "properties": {}}}},
    {"type": "function", "function": {"name": "leer_factura",
     "description": "Devuelve el contenido de un XML de factura.",
     "parameters": {"type": "object", "properties": {"nombre": {"type": "string"}},
                    "required": ["nombre"]}}},
]

mensajes = [
    {"role": "system", "content": "Analizas facturas CFDI en XML. Usa las herramientas. Responde en español."},
    {"role": "user", "content": "¿Qué proveedor tiene el total más alto?"},
]

for _ in range(8):  # límite de vueltas del agente
    r = client.chat.completions.create(model=MODELO, messages=mensajes, tools=TOOLS)
    msg = r.choices[0].message
    mensajes.append(msg)
    if not msg.tool_calls:
        print(msg.content)
        break
    for call in msg.tool_calls:
        args = json.loads(call.function.arguments or "{}")
        salida = FUNCIONES[call.function.name](**args)
        mensajes.append({"role": "tool", "tool_call_id": call.id, "content": salida})

Pon tus XML en una carpeta facturas/ junto al script y córrelo. El agente lista los archivos, abre los que necesita y responde. Si el modelo pequeño se confunde, prueba uno más grande o simplifica la tarea.

Paso 3 (opcional): sin código con n8n

Si prefieres bloques visuales, n8n autoalojado se conecta a Ollama: en el nodo AI Agent elige como modelo Ollama Chat Model y apúntalo a http://localhost:11434 (o a la IP del equipo donde corre Ollama). Así armas agentes locales conectados a correo, hojas de cálculo o bases de datos. Ver qué es n8n.

Qué equipo necesitas (orientativo)

Equipo	Qué esperar
Laptop con 16 GB de RAM, sin GPU dedicada	Modelos pequeños (1-8 mil millones de parámetros), lentos pero usables para pruebas
Mac con chip Apple Silicon y 32 GB+	Modelos medianos con buena velocidad
PC con GPU con mucha VRAM	Modelos medianos y grandes, respuestas rápidas
Servidor dedicado	Uso por varias personas a la vez

Son referencias generales: el rendimiento real depende del modelo, de la “cuantización” (versión comprimida del modelo) y de tu equipo. Mide con tu caso.

El detalle que más confunde: el contexto

El contexto es cuánto texto puede “ver” el modelo a la vez: instrucciones, historial, resultados de herramientas y documentos. En Ollama el tamaño de contexto por defecto puede ser bastante menor que el máximo que soporta el modelo (depende de la versión de Ollama). Si le pasas una factura larga o varios documentos, el modelo puede ignorar en silencio la parte que no le cabe y responder como si no existiera.

Síntoma típico: el agente lee el archivo pero contesta mal datos que están al final. Soluciones:

• Sube el contexto con el parámetro num_ctx del modelo o con la variable de entorno OLLAMA_CONTEXT_LENGTH, según tu versión; revisa la documentación de Ollama.
• Recuerda que más contexto usa más memoria y hace todo más lento.
• Mejor aún: haz que tus herramientas devuelvan solo los datos necesarios (por ejemplo, emisor y total del XML) en vez del archivo completo.

Responder con tus documentos sin salir de tu equipo

Si quieres que el agente conteste con manuales, contratos o políticas, el patrón es el mismo que en la nube (RAG), pero todo local:

1. Divide los documentos en fragmentos de unos cuantos párrafos.
2. Convierte cada fragmento en un vector con un modelo de embeddings que también corre en Ollama (en su biblioteca hay varios; búscalos por la etiqueta embedding).
3. Guarda los vectores en una base local, como Chroma o Postgres con pgvector.
4. Dale al agente una herramienta buscar_en_documentos(pregunta) que devuelva los 3 a 5 fragmentos más parecidos.

Así ningún documento sale de tu red y el modelo solo recibe lo relevante, lo que además ayuda con el problema del contexto.

Local, nube o los dos

Concepto	Agente local	Agente en la nube
Privacidad	Los datos no salen de tu equipo	Dependes de las condiciones del proveedor
Calidad en tareas complejas	Menor con modelos pequeños	Mayor con los modelos grandes
Costo	Equipo y electricidad	Pago por uso
Mantenimiento	Tú actualizas equipo y modelos	Lo hace el proveedor

Un esquema híbrido es común: lo sensible (extraer datos de expedientes) se procesa local, y lo que no tiene datos personales (redactar un texto genérico) va a un modelo en la nube.

Seguridad aunque sea local

• Limita lo que las herramientas pueden tocar: en el ejemplo, solo una carpeta y solo lectura.
• No expongas la API de Ollama a internet sin protección; por defecto escucha solo en tu equipo.
• Licencias: algunos modelos abiertos tienen restricciones de uso comercial; revisa la licencia de cada uno.
• Respaldos y registros de lo que hace el agente.

Errores comunes

• “model does not support tools”: elige un modelo marcado con soporte de herramientas.
• Respuestas lentísimas: el modelo es demasiado grande para tu memoria; usa uno más pequeño.
• El agente inventa contenido de archivos: verifica que realmente llamó a la herramienta; refuerza las instrucciones.
• Conexión rechazada en localhost:11434: Ollama no está corriendo (ollama serve).

Para cerrar

Un agente local es la mejor opción cuando la privacidad pesa más que tener el modelo más potente. Si quieres comparar con las opciones en la nube, revisa crear agente de IA, y para casos de oficina, automatizar facturas con IA. En Black Engine instalamos agentes locales en tu equipo o servidor, conectados a tus documentos; escríbenos por WhatsApp.