🤖 Agente de IA Conversacional con Herramientas

Un agente de IA inteligente construido con Python y OpenAI que puede mantener conversaciones y utilizar múltiples herramientas para realizar tareas específicas.

🎯 Dos Versiones Disponibles

Este proyecto incluye dos interfaces para el mismo agente:

1. 🖥️ CLI (Línea de Comandos) - agente_ia.py

   • Interfaz de terminal rápida y ligera
   • Ideal para desarrollo y automatización
   • Ver guía rápida

2. 🌐 Web (Gradio) - agente_gradio.py

   • Interfaz gráfica moderna en navegador
   • Ideal para demostraciones y usuarios finales
   • Ver guía rápida

📊 Ver comparación detallada

✨ Características

• Conversación natural: Mantiene el contexto de la conversación a lo largo de múltiples mensajes
• Múltiples herramientas: El agente puede usar diferentes herramientas según la necesidad:
  • 🧮 Calculadora: Operaciones matemáticas básicas
  • ⏰ Hora actual: Obtiene fecha y hora del sistema
  • 🌡️ Conversor de temperatura: Conversión entre Celsius, Fahrenheit y Kelvin
  • 🔐 Generador de contraseñas: Crea contraseñas seguras personalizadas
  • 📝 Analizador de texto: Cuenta palabras, caracteres, líneas y oraciones

📋 Requisitos

• Python 3.8 o superior
• Una API key de OpenAI

🚀 Instalación

1. Clonar o descargar el proyecto

2. Instalar las dependencias:

pip install -r requirements.txt

3. Configurar la API key de OpenAI:

   Opción 1 - Variable de entorno:

   # Windows (PowerShell)
   $env:OPENAI_API_KEY="tu_api_key_aqui"
   
   # Windows (CMD)
   set OPENAI_API_KEY=tu_api_key_aqui
   
   # Linux/Mac
   export OPENAI_API_KEY="tu_api_key_aqui"

   Opción 2 - Archivo .env:

   • Copia el archivo .env.example a .env
   • Edita .env y agrega tu API key

   OPENAI_API_KEY=tu_api_key_aqui
   

💻 Uso

Versión CLI - Línea de Comandos

Ejecuta el agente en modo conversacional en la terminal:

python agente_ia.py

Luego puedes interactuar con el agente naturalmente. Ejemplos:

👤 Tú: ¿Cuánto es 25 + 17?
🤖 Agente: El resultado de 25 + 17 es 42.

👤 Tú: ¿Qué hora es?
🤖 Agente: La fecha y hora actual es...

👤 Tú: Convierte 100 grados Fahrenheit a Celsius
🤖 Agente: 100°F equivalen a 37.78°C

👤 Tú: Genera una contraseña de 16 caracteres
🤖 Agente: Aquí está tu contraseña segura de 16 caracteres...

👤 Tú: Analiza este texto: "Hola mundo, esto es una prueba."
🤖 Agente: El texto tiene 6 palabras, 35 caracteres...

Comandos especiales:

• salir - Termina la conversación
• limpiar - Limpia el historial de conversación

Versión Web - Interfaz Gradio

Ejecuta el agente con interfaz gráfica en el navegador:

python agente_gradio.py

La aplicación se abrirá automáticamente en http://127.0.0.1:7860

Características de la interfaz web:

• 💬 Chat interactivo con burbujas de conversación
• 🔧 Visualización de herramientas usadas
• 💡 Ejemplos predefinidos con un clic
• 📊 Panel informativo con todas las herramientas
• 🗑️ Botones para limpiar historial o reiniciar el agente
• 📱 Responsive - funciona en móviles y tablets

Para más detalles, consulta README_GRADIO.md

Uso programático

También puedes usar el agente en tu propio código:

from agente_ia import AgenteIA

# Crear el agente
agente = AgenteIA(api_key="tu_api_key")

# Enviar mensajes
respuesta = agente.enviar_mensaje("¿Cuánto es 15 multiplicado por 8?")
print(respuesta)

# Limpiar historial si es necesario
agente.limpiar_historial()

🔧 Cómo funciona

El agente utiliza la funcionalidad de Function Calling de OpenAI, que permite:

1. El usuario envía un mensaje
2. El modelo de IA determina si necesita usar alguna herramienta
3. Si es necesario, ejecuta la(s) herramienta(s) correspondiente(s)
4. Procesa los resultados y genera una respuesta natural

Arquitectura

Usuario → Mensaje → Agente IA → Determina herramientas necesarias
                         ↓
                   Ejecuta herramientas
                         ↓
                   Procesa resultados
                         ↓
                   Respuesta al usuario

🛠️ Agregar nuevas herramientas

Para agregar una nueva herramienta, modifica agente_ia.py:

1. Define la herramienta en _registrar_herramientas():

self.herramientas.append({
    "type": "function",
    "function": {
        "name": "nombre_herramienta",
        "description": "Descripción de qué hace la herramienta",
        "parameters": {
            "type": "object",
            "properties": {
                "parametro1": {
                    "type": "string",
                    "description": "Descripción del parámetro"
                }
            },
            "required": ["parametro1"]
        }
    }
})
self.funciones_disponibles["nombre_herramienta"] = self._nombre_herramienta

2. Implementa la función:

def _nombre_herramienta(self, parametro1: str) -> str:
    """Implementación de la herramienta"""
    resultado = # ... tu lógica aquí
    return json.dumps(resultado)

📝 Ejemplos de uso

Ejemplo 1: Cálculos matemáticos

👤 Tú: Necesito dividir 1234 entre 7
🔧 Usando herramienta: calculadora
   Argumentos: {'operacion': 'division', 'numero1': 1234, 'numero2': 7}
🤖 Agente: El resultado de dividir 1234 entre 7 es 176.29

Ejemplo 2: Conversión de temperatura

👤 Tú: ¿Cuántos grados Kelvin son 25 Celsius?
🔧 Usando herramienta: convertir_temperatura
   Argumentos: {'valor': 25, 'de_unidad': 'celsius', 'a_unidad': 'kelvin'}
🤖 Agente: 25°C equivalen a 298.15 K

Ejemplo 3: Múltiples herramientas

👤 Tú: ¿Qué hora es y cuánto es 50 más 75?
🔧 Usando herramienta: obtener_hora_actual
🔧 Usando herramienta: calculadora
🤖 Agente: Actualmente son las 14:30:00 del 2024-10-13. 
           Y el resultado de 50 + 75 es 125.

🔐 Seguridad

• NUNCA compartas tu API key de OpenAI
• NO subas el archivo .env a repositorios públicos
• El archivo .gitignore ya está configurado para ignorar .env

📚 Recursos

• Documentación de OpenAI Function Calling
• OpenAI Python SDK
• API Reference

🤝 Contribuir

¡Las contribuciones son bienvenidas! Algunas ideas:

• Agregar más herramientas útiles
• Mejorar el manejo de errores
• Agregar persistencia de conversaciones
• Crear una interfaz gráfica

📄 Licencia

Este proyecto es de código abierto y está disponible para uso educativo.

⚡ Troubleshooting

Error: "No module named 'openai'"

pip install -r requirements.txt

Error: "Authentication error"

Verifica que tu API key esté correctamente configurada en la variable de entorno OPENAI_API_KEY

El agente no usa las herramientas

Asegúrate de estar usando un modelo compatible con function calling como gpt-4o-mini, gpt-4o, gpt-4-turbo, o gpt-3.5-turbo

---

¡Disfruta conversando con tu agente de IA! 🚀