Un Agente IA de Voz que Responde a tus Órdenes

¿Te imaginas poder dictar una orden y que una inteligencia artificial escriba código, resuma textos o guarde archivos en tu computadora, todo sin tocar el teclado? Esa es la premisa detrás de un Agente IA de Voz Controlado Localmente, un proyecto que combina la potencia de los modelos de lenguaje grandes (LLMs) con la conveniencia del control por voz.

Este artículo detalla la arquitectura, la selección de modelos y las lecciones aprendidas al construir un agente de este tipo utilizando Python, el framework Streamlit para la interfaz de usuario y la rápida inferencia de LLMs de Groq. A diferencia de muchos tutoriales, exploraremos también los aspectos menos glamurosos pero cruciales del desarrollo.

Arquitectura del Sistema: Un Pipeline Modular

El agente sigue un pipeline claro de tres etapas, cada una encapsulada en su propio módulo Python para facilitar la extensibilidad y depuración:

1. Entrada de Audio: Captura de voz o comandos escritos.
2. Speech-to-Text (STT): Transcripción del audio a texto.
3. Clasificación de Intención: Interpretación del texto por un LLM.
4. Ejecución de Herramientas: Realización de acciones basadas en la intención.

El resultado se materializa en archivos, código generado, resúmenes o respuestas de chat. La estructura del proyecto es la siguiente:

voice_agent/
├── app.py          # UI con Streamlit y orquestación del pipeline
├── stt.py          # Módulo Speech-to-Text (Groq / OpenAI / Whisper)
├── intent.py       # Clasificación de intención vía LLM
├── tools.py        # Motor de ejecución de herramientas
├── requirements.txt
└── output/         # Archivos generados

Módulo Speech-to-Text (STT)

El módulo stt.py ofrece flexibilidad con tres backends seleccionables:

• Groq API: Utiliza whisper-large-v3. Es rápido, gratuito y basado en la nube, ideal para la mayoría de los usuarios por su buen manejo de acentos y calidad de audio.
• OpenAI API: Emplea whisper-1. Conocido por su precisión, pero requiere pago.
• Whisper Local: Modelos base o small. Ofrece privacidad total al operar offline, aunque a menor velocidad.

La función transcribe_audio maneja la selección del backend según la configuración.

Clasificación de Intención con LLMs Potentes

Aquí es donde reside la inteligencia. El texto transcrito se envía a un LLM con un system prompt diseñado para forzar una salida estructurada en formato JSON. La clave fue diseñar el prompt alrededor de un arreglo de commands en lugar de una única intención, lo que permite el soporte para comandos compuestos desde el inicio. Por ejemplo, una sola petición puede incluir resumir y guardar un archivo.

Selección de LLMs: Groq vs. OpenAI

Para la clasificación de intención y ejecución de tareas, se compararon varios modelos:

• Groq API (Llama 3.3 70B Versatile): Destaca por su velocidad excepcional, con una capa gratuita disponible.
• OpenAI API (GPT-4o-mini): Ofrece un rendimiento medio, pero es un servicio de pago.
• Ollama Local (Llama3.2, Mistral, etc.): Opciones locales que son más lentas pero gratuitas.

Groq se recomienda enfáticamente por su inferencia notablemente rápida, completando tareas en menos de un segundo que a otros modelos les toma varios segundos.

Ejecución de Herramientas y Manejo de Comandos Compuestos

El módulo tools.py dirige cada intención clasificada a la función de manejo correcta. Cada manejador sigue un contrato estricto: recibe parámetros, directorio de salida y configuración, y devuelve un diccionario con el resultado. El manejador write_code, por ejemplo, realiza una segunda llamada al LLM para generar código puro, sin adornos de markdown.

Un comando de voz puede desencadenar múltiples acciones secuencialmente. El agente procesa cada comando en el arreglo, solicitando confirmación humana (Human-in-the-Loop o HITL) antes de operaciones críticas como la escritura de archivos, previniendo así sobrescrituras accidentales. Los intentos cancelados también se registran para trazabilidad.

Manejo de Fallos y Memoria del Agente

Los agentes de voz fallan constantemente. En lugar de colapsar, este agente implementa degradación elegante:

• Errores Amigables: Captura excepciones (API, red, formato) y presenta mensajes comprensibles al usuario.
• Intenciones Desconocidas: Se degradan a general_chat, explicando lo que entendió.

El agente mantiene dos tipos de memoria:

• Historial de Acciones: Registra cada comando, intención y resultado, con estadísticas de éxito y frecuencia de intenciones.
• Contexto de Chat: Una ventana móvil de las últimas 20 interacciones se pasa al LLM, permitiendo comandos de seguimiento sin repetición.

Benchmarking de Modelos y Lecciones Aprendidas

El agente incluye una pestaña de benchmarking para comparar modelos como Llama 3.3 70B (potente) y Llama 3.1 8B (rápido) en Groq. Los resultados muestran:

• Generación compleja de código: Llama 3.3 70B es superior.
• Preguntas y respuestas simples: Llama 3.1 8B es 3-4 veces más rápido.
• Resúmenes: Rendimiento similar.

Se superaron varios desafíos, incluyendo:

1. Manejo de Múltiples Claves API: Se añadieron campos separados en la interfaz de Streamlit.
2. Parsing de JSON: Se implementó un parser robusto para extraer JSON incluso si está envuelto en markdown.
3. Modelos Deprecados: Se usan bloques try-except para capturar y mostrar errores de modelos, evitando fallos silenciosos.
4. Gestión de Estado en Streamlit (HITL): Se usó st.session_state para mantener el contexto durante las confirmaciones.
5. Errores de Cuota OpenAI: Se muestran los errores inline en el benchmarking para no detener todo el proceso.

Tech Stack Resumido

• UI: Streamlit
• STT: Groq Whisper Large V3 (Cloud), Whisper Local (Offline)
• LLM Principal: Groq Llama 3.3 70B Versatile
• LLM Benchmark: Groq Llama 3.1 8B Instant
• Lenguaje: Python

Conclusión: La Plomería es Clave

Construir un agente IA de voz desde cero revela que los desafíos más significativos no residen en la IA en sí, sino en la "plomería": gestión de estado, manejo de errores, compatibilidad de formatos y las peculiaridades de las APIs. La robustez y la experiencia de usuario toman más tiempo que la funcionalidad básica. El consejo principal es: priorizar el manejo de fallos sobre las características. Un agente que falla ante audio defectuoso o una clave API expirada es peor que no tener ninguno. El código open source está disponible para su experimentación.