Cómo crear un chatbot con OpenAI y Python

Crear un chatbot con OpenAI y Python es una excelente forma de aprender cómo una aplicación local puede enviar mensajes a un modelo de lenguaje, recibir respuestas y mantener una conversación con contexto. En esta guía construirás un chatbot para terminal con la biblioteca oficial de OpenAI, variables de entorno, memoria conversacional y manejo de errores.

No se trata de una traducción literal del artículo en portugués. El proyecto fue reorganizado para un lector hispanohablante que quiere llegar rápidamente a una solución actual, segura y fácil de ampliar. El ejemplo utiliza la Responses API y deja el modelo configurable para que puedas cambiarlo sin modificar la lógica principal.

Qué vas a construir

El programa final hará lo siguiente:

• leer mensajes escritos en la terminal;
• enviarlos a la API de OpenAI;
• mostrar la respuesta generada;
• conservar el contexto entre turnos;
• proteger la clave de API con un archivo .env;
• mostrar mensajes claros cuando ocurra un error.

Este proyecto es distinto de un bot basado en reglas. En un chatbot sencillo con Python, el programa compara palabras y elige respuestas previamente definidas. Aquí el texto se envía a un servicio externo capaz de responder preguntas abiertas.

Requisitos

Antes de comenzar, prepara lo siguiente:

• Python instalado;
• un editor como Visual Studio Code o PyCharm;
• una cuenta para usar la API de OpenAI;
• una clave de API activa;
• saldo o facturación disponible para realizar solicitudes.

La suscripción de un producto de chat y el uso de la API son servicios separados. Revisa siempre el panel de la API y la página de precios antes de publicar una aplicación para otras personas.

1. Crear el proyecto y el entorno virtual

Crea una carpeta llamada chatbot-openai y abre una terminal dentro de ella. Después crea un entorno virtual:

python -m venv .venv

En Windows PowerShell, actívalo con:

.venv\Scripts\Activate.ps1

En macOS o Linux:

source .venv/bin/activate

El entorno virtual evita mezclar las dependencias de este proyecto con las de otros programas. El tema se explica con más detalle en la guía de entornos virtuales con Python.

2. Instalar las bibliotecas

Instala la biblioteca oficial de OpenAI y python-dotenv:

python -m pip install openai python-dotenv

La primera biblioteca proporciona el cliente para la API. La segunda permite cargar variables desde un archivo local sin escribir secretos directamente en el código.

3. Guardar la clave de API de forma segura

Crea un archivo llamado .env en la raíz del proyecto:

OPENAI_API_KEY=reemplaza_esto_con_tu_clave
OPENAI_MODEL=gpt-5.6-luna

El modelo queda en una variable separada porque la disponibilidad puede variar entre cuentas y puede cambiar con el tiempo. Consulta el catálogo oficial de modelos antes de desplegar el proyecto.

Nunca publiques tu clave de API. No la pegues en un repositorio, una captura de pantalla, una pregunta de soporte ni un archivo compartido. Si se expone, revócala y genera una nueva.

Crea también un archivo .gitignore:

.env
.venv/
__pycache__/

4. Enviar la primera solicitud

Crea un archivo llamado chatbot.py con este ejemplo mínimo:

import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

modelo = os.getenv("OPENAI_MODEL", "gpt-5.6-luna")
cliente = OpenAI()

respuesta = cliente.responses.create(
    model=modelo,
    instructions=(
        "Eres un tutor de Python. "
        "Responde en español claro y utiliza ejemplos breves."
    ),
    input="Explica qué es una función en Python en tres frases.",
)

print(respuesta.output_text)

La clase OpenAI() lee automáticamente OPENAI_API_KEY desde el entorno. El método responses.create() envía la solicitud. El parámetro instructions define el comportamiento del asistente y input contiene el mensaje del usuario.

La respuesta de texto se obtiene mediante respuesta.output_text. El patrón coincide con el inicio rápido oficial para desarrolladores.

5. Añadir un bucle de conversación

Un chatbot necesita continuar leyendo mensajes hasta que la persona decida salir. Para eso utilizaremos un bucle while y una variable con el identificador de la respuesta anterior.

respuesta_anterior = None

while True:
    mensaje = input("Tú: ").strip()

    if mensaje.lower() in {"salir", "exit", "quit"}:
        print("Conversación finalizada.")
        break

    if not mensaje:
        continue

    datos = {
        "model": modelo,
        "instructions": (
            "Eres un tutor de Python. "
            "Responde en español claro y utiliza ejemplos breves."
        ),
        "input": mensaje,
    }

    if respuesta_anterior is not None:
        datos["previous_response_id"] = respuesta_anterior

    respuesta = cliente.responses.create(**datos)
    respuesta_anterior = respuesta.id

    print("Bot:", respuesta.output_text)

previous_response_id permite que una nueva solicitud continúe la conversación anterior. Las instrucciones se envían en cada turno para mantener estable el tono y la función del chatbot.

6. Manejar errores de la API

Las solicitudes pueden fallar por una clave inválida, problemas de conexión, límites de uso o un modelo no disponible. El programa debe explicar el problema en lugar de terminar con un mensaje difícil de interpretar.

import openai

try:
    respuesta = cliente.responses.create(**datos)
except openai.AuthenticationError:
    print("La autenticación falló. Revisa OPENAI_API_KEY.")
except openai.RateLimitError:
    print("Se alcanzó un límite de uso. Intenta nuevamente más tarde.")
except openai.APIConnectionError:
    print("No se pudo conectar con la API. Revisa tu conexión.")
except openai.APIError as error:
    print(f"La API devolvió un error: {error}")

Para comprender mejor este patrón, consulta la guía sobre try y except en Python y la documentación oficial de códigos de error de la API.

Código completo del chatbot

La siguiente versión combina configuración, funciones, memoria conversacional, validación y manejo de errores:

import os

import openai
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

MODELO = os.getenv("OPENAI_MODEL", "gpt-5.6-luna")
INSTRUCCIONES = (
    "Eres un tutor de programación especializado en Python. "
    "Responde en español neutro, explica paso a paso y usa "
    "ejemplos breves cuando sean útiles."
)

cliente = OpenAI()


def crear_respuesta(mensaje, respuesta_anterior=None):
    datos = {
        "model": MODELO,
        "instructions": INSTRUCCIONES,
        "input": mensaje,
    }

    if respuesta_anterior is not None:
        datos["previous_response_id"] = respuesta_anterior

    return cliente.responses.create(**datos)


def main():
    respuesta_anterior = None

    print("Chatbot con OpenAI y Python")
    print("Escribe 'salir' para terminar.")

    while True:
        mensaje = input("Tú: ").strip()

        if mensaje.lower() in {"salir", "exit", "quit"}:
            print("Conversación finalizada.")
            break

        if not mensaje:
            print("Escribe un mensaje antes de continuar.")
            continue

        try:
            respuesta = crear_respuesta(
                mensaje=mensaje,
                respuesta_anterior=respuesta_anterior,
            )
        except openai.AuthenticationError:
            print("Clave inválida o revocada. Revisa OPENAI_API_KEY.")
            break
        except openai.RateLimitError:
            print("Se alcanzó un límite de uso. Intenta más tarde.")
            continue
        except openai.APIConnectionError:
            print("No fue posible conectar con la API.")
            continue
        except openai.APIError as error:
            print(f"Error de la API: {error}")
            continue

        respuesta_anterior = respuesta.id
        print("Bot:", respuesta.output_text)


if __name__ == "__main__":
    main()

Ejecuta el programa con:

python chatbot.py

Cómo funciona el código completo

Configuración

load_dotenv() carga el archivo .env. Después, MODELO lee el nombre del modelo y OpenAI() obtiene la clave sin que tengas que pasarla manualmente.

Función reutilizable

crear_respuesta() concentra la lógica de comunicación con la API. Separar esta parte facilita reemplazar la terminal por una interfaz web, una aplicación de escritorio o un bot de mensajería.

Memoria de la conversación

Después de cada respuesta correcta, el programa guarda respuesta.id. En el turno siguiente, ese valor se envía como previous_response_id. Al reiniciar la variable se inicia una conversación nueva.

Validación de entrada

strip() elimina espacios innecesarios. Los mensajes vacíos no se envían y un conjunto permite comprobar rápidamente los comandos de salida.

Personalizar el comportamiento

La forma más sencilla de adaptar el chatbot es modificar INSTRUCCIONES. Puedes definir el rol, la audiencia, el formato y las restricciones. Por ejemplo:

INSTRUCCIONES = (
    "Eres un asistente para estudiar matemáticas de secundaria. "
    "Explica cada paso, no saltes operaciones y termina con "
    "un ejercicio breve para practicar."
)

También puedes convertir el proyecto en un asistente de soporte, un tutor de idiomas, un ayudante para documentación o un prototipo para atención al cliente.

Ideas para ampliar el proyecto

• guardar las conversaciones en SQLite;
• añadir una interfaz con Flask o FastAPI;
• conectar el bot con Telegram;
• crear perfiles con instrucciones diferentes;
• registrar métricas sin almacenar datos sensibles;
• añadir límites de longitud para los mensajes;
• mostrar respuestas por streaming.

La guía para crear un bot de Telegram con Python puede servir como siguiente paso para llevar la misma lógica a una plataforma de mensajería.

Buenas prácticas de seguridad y costes

• mantén la clave únicamente en el servidor;
• no expongas secretos en JavaScript del navegador;
• añade .env a .gitignore antes del primer commit;
• revoca claves que ya no utilices;
• limita el tamaño de los mensajes en aplicaciones públicas;
• revisa el consumo y configura límites en la cuenta;
• elige un modelo adecuado para la tarea, no necesariamente el más grande;
• evita registrar conversaciones privadas sin consentimiento.

Consulta la guía oficial de generación de texto y la documentación de modelos cada vez que actualices el proyecto.

Problemas frecuentes

La clave no se encuentra

Comprueba que el archivo se llame exactamente .env, que esté en la carpeta del proyecto y que load_dotenv() se ejecute antes de crear el cliente.

El modelo no está disponible

Abre el catálogo oficial, selecciona un modelo habilitado para tu proyecto y cambia OPENAI_MODEL. Como el nombre está fuera del código, no necesitas modificar las funciones.

El bot olvida la conversación

Verifica que guardas respuesta.id y que lo envías como previous_response_id en el siguiente turno.

El programa muestra un traceback

Coloca la solicitud dentro de try y maneja las excepciones de la biblioteca. Durante el desarrollo puedes registrar información adicional, pero nunca la clave de API.

Conclusión

Ahora tienes un chatbot con OpenAI y Python que funciona en la terminal, conserva contexto, protege las credenciales y responde de manera controlada ante errores comunes. La estructura es lo bastante sencilla para aprender y lo bastante organizada para convertirse en un proyecto mayor.

El siguiente paso recomendado es separar la interfaz, la configuración y la lógica de la API en módulos distintos. Así podrás cambiar la terminal por una web o una integración de mensajería sin reescribir la parte central del chatbot.