MÓDULO 2 · PRIMEROS PASOS CON OPENAI · 40 MIN

Creación de asistentes inteligentes con OpenAI

40 min Intermedio OpenAI Assistants API Python Code Interpreter File Search
La API de Asistentes delega la gestión del estado (memoria) y la ejecución de herramientas a OpenAI, liberando a tu backend de esa carga. El patrón — configuración persistente + conversación con estado + ejecución — es el que importa recordar, más allá del nombre exacto de los objetos.
Auditoría — vigencia

Importante: la Assistants API que enseña esta lección está deprecada y OpenAI la apaga por completo el 26 de agosto de 2026 — prácticamente ahora mismo. Fue reemplazada por la Responses API (combinada con Conversations y Prompts), anunciada en marzo de 2025 con esta fecha de cierre confirmada. La arquitectura conceptual de 3 piezas se mantiene, solo cambian los nombres:

Assistants API (esta lección)Responses API (actual)
AssistantPrompt (versionado desde el dashboard, no por código)
ThreadConversation
Run (asíncrono, requiere polling)Response (la llamada básica es síncrona — sin bucle de espera)

Vale la pena entender el patrón Assistant/Thread/Run de este ejercicio porque el mismo curso de OpenAI está construido sobre él y porque el modelo mental es el mismo — pero para código nuevo en un proyecto real, arrancá directamente con client.responses.create() en vez de client.beta.assistants.

01 —
El problema

Con la API básica de Chat, sos vos responsable de todo: guardar el historial, contar tokens, y si querés que la IA analice un PDF de 100 páginas, tenés que trocearlo vos mismo.

Situación típica: querés crear un "Analista Financiero" que pueda leer tus Excel y PDFs de facturas. Con la API normal, tendrías que escribir cientos de líneas de código para extraer texto y manejar la ventana de contexto.

Por qué es importante: la API de Assistants abstrae toda esa complejidad. OpenAI gestiona la memoria (hilos "infinitos") y la ejecución de herramientas, permitiéndote crear agentes autónomos robustos con mucho menos código.

02 —
La solución: Assistants API

La arquitectura se basa en 3 pilares:

Assistant: El "cerebro" configurado con instrucciones y herramientas Thread: El "chat" o historial que guarda el estado automáticamente Run: La "acción" de procesar el hilo y generar una respuesta

Cómo funciona: 1) creás el Asistente una vez (o lo reutilizás); 2) cuando un usuario llega, creás un Thread vacío; 3) añadís mensajes del usuario al hilo; 4) creás un Run para que el Asistente lea el hilo y responda.

03 —
Cuándo aplicarlo
Usá Assistants API cuando...NO lo uses cuando...
Necesitás memoria persistente y automática de largas conversacionesQuerés la mínima latencia posible (Chat Completions es más rápido)
Necesitás que la IA ejecute código Python, genere gráficos o lea archivos (RAG)Querés control total y granular sobre cada mensaje exacto que se envía al modelo
Estás construyendo agentes complejos con múltiples pasos de razonamientoEl costo es un factor crítico (Assistants puede consumir más tokens ocultos en gestión de contexto)
04 —
Ejercicio práctico

Objetivo: crear un "Tutor de Matemáticas" que no solo chatea, sino que escribe y ejecuta código Python real para resolver ecuaciones, y lee documentos para responder preguntas específicas.

Contexto inicial: necesitás tu API Key configurada.

pythonfrom openai import OpenAI from dotenv import load_dotenv load_dotenv() cliente = OpenAI()
Paso 1 — Crear el asistente con herramientas

Vamos a crear un asistente y darle la herramienta code_interpreter.

pythonasistente = cliente.beta.assistants.create( name="Profe Matemáticas", instructions="Eres un tutor de matemáticas. Responde preguntas usando código " "Python cuando sea necesario para calcular con precisión.", model="gpt-4o", tools=[{"type": "code_interpreter"}] ) print(f"✅ Asistente creado con ID: {asistente.id}")
Paso 2 — Iniciar una conversación (Thread y Run)

Vamos a preguntarle algo que requiera cálculo, como la secuencia de Fibonacci.

python# 1. Crear Hilo thread = cliente.beta.threads.create() # 2. Añadir mensaje cliente.beta.threads.messages.create( thread_id=thread.id, role="user", content="Genera los primeros 10 números de Fibonacci usando código." ) # 3. Ejecutar (Run) run = cliente.beta.threads.runs.create( thread_id=thread.id, assistant_id=asistente.id ) print("⏳ Pensando...") # 4. Bucle de espera (Polling) while run.status in ['queued', 'in_progress', 'cancelling']: time.sleep(1) # Esperar un segundo run = cliente.beta.threads.runs.retrieve( thread_id=thread.id, run_id=run.id ) if run.status == 'completed': # 5. Obtener mensajes mensajes = cliente.beta.threads.messages.list(thread_id=thread.id) # Los mensajes vienen del más nuevo al más viejo respuesta = mensajes.data[0].content[0].text.value print(f"\n🤖 Respuesta:\n{respuesta}") else: print(f"❌ Error en el Run: {run.status}")
Paso 3 — Añadir File Search (RAG)

Ahora actualizaremos el asistente para que pueda leer archivos.

// Nota: para este paso necesitás un archivo pequeño en tu carpeta.

python# 1. Subir archivo a OpenAI (creamos uno de ejemplo) with open("datos_empresa.txt", "w") as f: f.write("La empresa 'TechCorp' fue fundada en 2020 por Elon y Sam.") archivo = cliente.files.create( file=open("datos_empresa.txt", "rb"), purpose='assistants' ) # 2. Actualizar asistente para usar File Search asistente = cliente.beta.assistants.update( assistant_id=asistente.id, tools=[{"type": "code_interpreter"}, {"type": "file_search"}] ) # 3. Crear nuevo hilo con el archivo adjunto thread_archivo = cliente.beta.threads.create( messages=[ { "role": "user", "content": "¿Cuándo se fundó TechCorp y por quién?", "attachments": [ {"file_id": archivo.id, "tools": [{"type": "file_search"}]} ] } ] ) # 4. Ejecutar Run (reutilizando la lógica de espera del paso 2) run_archivo = cliente.beta.threads.runs.create( thread_id=thread_archivo.id, assistant_id=asistente.id ) # ... (repetir bucle de espera) ...
Validación

Al ejecutar el paso 2, deberías ver que el asistente responde con la lista de Fibonacci. Si inspeccionaras los run_steps, verías que generó código Python y lo ejecutó.

05 —
Troubleshooting rápido
Si ves esto...CausaSolución
run.status se queda en requires_actionEl asistente quiere llamar a una función personalizada (function calling) que no manejasteEn este ejemplo básico solo usamos Code Interpreter; revisá si definiste herramientas extra
Error file_not_foundNo creaste el archivo local antes de subirloAsegurate de que datos_empresa.txt exista en tu carpeta
Respuesta lentaAssistants API es más lenta que Chat API porque guarda estado y gestiona herramientasEs normal; implementá indicadores de carga en tu UI
06 —
Puntos clave

Concepto central: la API de Asistentes delega la gestión del estado (memoria) y la ejecución de herramientas a OpenAI, liberando a tu backend de esa carga.

Para recordar: