Crear tu primer agente de inteligencia artificial en Python mola. Es emocionante, engancha y te hace sentir que ya estás dentro del juego.

Pero aquí viene la bofetada de realidad: una cosa es hacer que “funcione” y otra muy distinta es escribir código que no se rompa en cuanto añadas una nueva función, que no exponga tus claves API al mundo y que no dé vergüenza ajena cuando lo revise alguien con experiencia.

El salto importante no está en saber llamar a un modelo LLM. Está en dejar de escribir scripts sueltos y empezar a arquitectar software. Ese cambio pasa por cinco piezas clave:

• Programación orientada a objetos para dar estructura.
• Git y GitHub para versionar y no perder trabajo.
• Ficheros .env y .gitignore para proteger secretos.
• Ruff para limpiar y estandarizar el código.
• UV para gestionar proyectos y dependencias como una persona seria.

El gran problema de la mayoría de proyectos de IA

Muchos proyectos de Python para IA nacen como una prueba rápida. Una clave API aquí, una función allá, una variable global más arriba, otra más abajo. Y mientras solo hay 30 líneas, parece que todo va bien.

El problema llega cuando quieres escalar.

De repente necesitas varios modelos, múltiples configuraciones, tratamiento de errores, lectura de datos, herramientas externas, lógica de negocio y quizá una pequeña sociedad de agentes. Entonces el castillo de naipes se viene abajo.

La razón es simple: falta ADN de software. Y en Python, ese ADN suele empezar por la programación orientada a objetos.

Clases en Python: el momento en que tu código deja de parecer un garaje caótico

Una clase es una plantilla. Define qué datos tiene una cosa y qué puede hacer.

Si piensas en un coche, sus atributos serían el color, la marca o los caballos. Sus métodos serían acelerar, frenar o abrir una puerta.

En IA pasa lo mismo. Un cliente para OpenAI, Claude o Gemini puede tener:

• Nombre del proveedor
• Modelo
• Clave API
• URL base
• Métodos para generar respuestas

Sin clases, todo eso queda desperdigado por el código. Con clases, lo encapsulas en una sola entidad coherente.

Pasas de esto:

api_key = "sk-..." 
prompt = "Explícame qué es Python" 
response = make_api_call(api_key, prompt) 
print(response)

a algo conceptualmente mucho más sólido:

class OpenAIClient:     
    def __init__(self, api_key, model):         
        self.api_key = api_key         
        self.model = model      

    def generate_response(self, prompt):         
        return "respuesta del modelo"

La diferencia no es solo estética. Es una diferencia de legibilidad, escalabilidad y mantenimiento.

Cómo pensar la evolución natural de tu código

Una progresión muy habitual en Python suele ser esta:

1. Scripts con variables sueltas
2. Funciones para no repetir código
3. Módulos separados por responsabilidad
4. Clases para encapsular estado y comportamiento

Ese es el camino sano.

No hace falta arrancar un proyecto pequeño con 25 patrones de diseño y una catedral arquitectónica. Pero sí conviene entender cuándo el script ya se te ha quedado corto y necesitas subir de nivel.

Tu primera clase: constructor, self e instancias sin drama

En Python, una clase básica suele tener:

• La palabra reservada class
• Un constructor __init__
• La referencia self para acceder al propio objeto

Ejemplo clásico:

class Dog:     
    def __init__(self, name, breed):         
        self.name = name         
        self.breed = breed

Luego puedes crear instancias:

dog1 = Dog("Fluffy", "Golden Retriever") 
dog2 = Dog("Max", "Poodle")

Aquí la clave mental es esta: la clase es la receta, la instancia es el plato. Puedes crear tantos objetos como quieras usando la misma plantilla, pero cada uno tiene sus propios datos.

Métodos y atributos: dónde empieza a tener sentido de verdad

Una clase no solo guarda información. También hace cosas.

Por ejemplo, una configuración para una API puede contener clave, modelo, tokens máximos y URL base. Eso ya te permite crear objetos distintos para desarrollo y producción:

class APIConfig:     
    version = "1.0"     
    max_retries = 5      
    def __init__(self, api_key, model="gpt-3.5-turbo", max_tokens=100):         
        self.api_key = api_key         
        self.model = model         
        self.max_tokens = max_tokens         
        self.base_url = "https://api.com/v1"

Con esto puedes tener una configuración para desarrollo con pocos tokens y otra para producción con más capacidad. Misma clase, distintos objetos, distinto comportamiento práctico.

Y aquí aparece una distinción muy útil:

• Atributos de instancia: pertenecen a cada objeto, como self.model.
• Atributos de clase: se comparten entre todas las instancias, como version.

Herencia: clonar el cerebro base y especializarlo

La herencia es un superpoder. Te permite crear una clase hija a partir de una clase padre.

La idea es sencilla: si varias clases comparten una base común, esa base vive arriba y luego cada hija añade lo suyo.

Ejemplo típico:

class Animal:     
    def __init__(self, name):         
        self.name = name      

    def eat(self):         
        return f"{self.name} está comiendo"  

class Dog(Animal):     
    def bark(self):         
        return f"{self.name} está ladrando"

El perro hereda lo que hace cualquier animal, pero añade su propia especialización.

En IA esto es oro puro. Puedes tener un BaseModel o un Agent genérico y luego derivar agentes especializados:

• Agente de ventas
• Agente de research
• Agente de scraping
• Agente de análisis de texto

Todos comparten un cerebro base, pero cada uno incorpora sus poderes concretos.

Eso sí, no fuerces la herencia porque quede elegante. Úsala cuando realmente exista una relación clara del tipo B es un tipo de A.

Funciones o clases: no mates moscas a cañonazos

Python soporta muy bien tanto programación funcional como orientada a objetos. Y aquí conviene ser práctico.

Si solo necesitas limpiar texto, quizá con un par de funciones te basta:

def clean_text(text):     
    return text.strip().lower()  

def remove_punctuation(text):     
    return text.replace(".", "").replace(",", "")

Ahora bien, si necesitas mantener estado, encadenar transformaciones o crear múltiples procesadores con comportamientos similares, una clase puede tener más sentido.

La regla rápida sería esta:

• Empieza con funciones cuando el problema sea pequeño.
• Pasa a clases cuando necesites agrupar datos y comportamiento.
• No sobreingenierices por el simple placer de complicarte la vida.

Git y GitHub: la máquina del tiempo que te salva la carrera

Programar sin Git es jugar una partida difícil sin guardar.

Un borrado accidental, una refactorización catastrófica o una prueba fallida y puedes perder horas o semanas de trabajo. Git resuelve eso con control de versiones.

Los cuatro comandos fundamentales son:

git init 
git add . 
git commit -m "mensaje descriptivo" 
git push

Conceptos básicos que debes dominar:

• Repositorio: la carpeta de tu proyecto controlada por Git.
• Commit: una fotografía del estado del código.
• Push: subir tus commits a GitHub.
• Pull: traer cambios desde GitHub.
• Branch: una rama paralela para experimentar sin romper la principal.

Además, un buen perfil de GitHub es una carta de presentación brutal. Si quieres profundizar en este camino y convertirlo en parte de tu flujo profesional, merece la pena explorar una formación completa de Git y GitHub.

El error más caro del principiante: subir tus API keys a GitHub

Esto pasa muchísimo. Se crea un script, se pone la clave de OpenAI dentro del archivo, se sube el repo público y listo: acabas de dejar la puerta de casa abierta con un cartel que pone “adelante”.

La solución profesional es usar variables de entorno y ficheros .env.

Ejemplo de fichero .env:

API_KEY=sk-1234567890ABCDEF 
DATABASE_URL=sqlite:///mi_app.db 
DEBUG=true

Y luego cargarlo en Python con python-dotenv:

from dotenv import load_dotenv 
import os  

load_dotenv()  
api_key = os.environ.get("API_KEY") 
debug = os.environ.get("DEBUG")

Pero esto solo es la mitad del trabajo. La otra mitad es impedir que ese fichero se suba al repositorio. Para eso existe .gitignore:

.env 
.venv 
__pycache__/

Un buen truco es crear también un .env.example con los nombres de variables necesarias, pero sin secretos reales.

Ruff: haz que tu código deje de parecer escrito a machetazos

El mal formato no es solo feo. Muchas veces es síntoma de caos mental, de importaciones inútiles, de inconsistencias y de pequeños errores que acaban pasando factura.

Ruff es una herramienta rapidísima para Python que:

• Formatea el código
• Detecta problemas de estilo
• Ordena imports
• Elimina señales de descuido de principiante

La gracia está en configurarlo para que formatee automáticamente al guardar. Así conviertes la limpieza en una costumbre, no en una tarea manual tediosa.

Si trabajas con Python serio, Ruff es de esas herramientas que una vez pruebas ya no quieres quitar.

Olvida pip: UV es el futuro

Y ahora llega una de esas herramientas que te hacen sentir que todo lo anterior pertenecía a la edad de piedra: UV.

UV es un gestor moderno de proyectos y paquetes para Python, escrito en Rust, absurdamente rápido y muy cómodo de usar. Reemplaza gran parte del lío clásico de pip, venv y compañía.

Comandos básicos:

uv init mi-proyecto 
uv add requests pandas numpy 
uv run main.py

¿Por qué merece la pena?

• Es mucho más rápido que pip.
• Crea y gestiona entornos virtuales automáticamente.
• Controla dependencias de forma más fiable.
• Genera un lockfile reproducible para replicar entornos.

Para proyectos de IA, donde acabas instalando librerías pesadas, dependencias cruzadas y herramientas auxiliares, UV te ahorra tiempo y dolores de cabeza. Si quieres profundizar en Python como base de trabajo para machine learning e IA, puede resultarte muy útil complementar esta parte con una formación práctica de Python para machine learning.

Tu setup profesional mínimo para agentes de IA

Si tuviera que resumir el setup pro en una checklist clara, sería esta:

• Organiza el proyecto con clases cuando haya estado y lógica compartida.
• Usa Git desde el minuto cero.
• Protege secretos con .env y .gitignore.
• Formatea con Ruff.
• Gestiona proyectos con UV.

Con solo eso, tu código ya se separa muchísimo del típico script improvisado que funciona hoy y explota mañana.

La diferencia real entre un novato y alguien profesional

El novato se obsesiona con que el programa funcione.

El profesional se asegura de que pueda crecer, mantenerse, compartirse, depurarse y protegerse.

Ahí está la diferencia de nivel.

Si estás construyendo agentes, herramientas con LLMs o cualquier proyecto de IA en Python, no necesitas solamente más prompts ni más APIs. Necesitas mejor arquitectura.

Y si quieres seguir profundizando en esta ruta para convertirte en un perfil sólido dentro del sector, puedes echar un vistazo a la ruta completa de inteligencia artificial, donde todo este ecosistema cobra todavía más sentido cuando pasa de ejemplo a proyecto real.

Porque sí, crear un agente está bien.

Pero construirlo como lo haría alguien del 1% ya es otra historia.