Solución de problemas
Busca el síntoma más parecido a lo que ves. El texto entre comillas es el mensaje que muestra VirtuAI, así que puedes buscarlo en esta página.
La mayoría de los problemas provienen de uno de tres lugares: falta una clave en la configuración del espacio de trabajo, un canal no está activado para el agente o se hizo un cambio en un espacio de trabajo distinto del que estás probando. Revisa eso primero.
Calidad del agente
Sección titulada «Calidad del agente»El agente da respuestas deficientes
Sección titulada «El agente da respuestas deficientes»- Haz que las instrucciones de personalidad sean más claras y específicas: el objetivo, el público, las reglas y qué hacer cuando no está seguro.
- Agrega o depura el contenido de la base de conocimiento. Un documento desactualizado produce respuestas seguras, pero desactualizadas.
- Verifica que la base de conocimiento esté asociada a este agente y que sus documentos hayan terminado de procesarse.
- Ajusta la configuración del modelo. Una temperatura más baja produce respuestas más coherentes.
- Verifica que los nombres, las descripciones y los resultados esperados de las herramientas sean precisos. El modelo decide cuándo llamar a una herramienta solo a partir de su descripción.
La respuesta se detiene a mitad de una oración
Sección titulada «La respuesta se detiene a mitad de una oración»Ves “Response was cut off — max output tokens reached”. La respuesta alcanzó el valor de Max Output Tokens del agente. Selecciona Continue para que el agente termine o aumenta ese valor en el agente. El valor predeterminado para agentes nuevos es de 1,000 tokens, que es poco para respuestas largas. Consulta Límites.
El agente cambió de comportamiento después de una edición
Sección titulada «El agente cambió de comportamiento después de una edición»- Si el control de versiones está desactivado para el agente, cada vez que guardas, el cambio llega de inmediato a todos sus canales. Activa el control de versiones en la página del agente para trabajar en un borrador y publicarlo cuando esté listo.
- Con el control de versiones activado, verifica que lo que estás probando sea la versión publicada y no el borrador. La página del agente muestra Unpublished changes cuando ambos difieren.
- Para volver atrás, abre History en la página del agente y revierte a una versión anterior.
- Vuelve a probar primero en el chat web, que es el canal más sencillo.
- Compara con conversaciones anteriores que funcionaron bien en Conversations.
- Deshaz solo el cambio más reciente y vuelve a probar.
“Could not complete the request with the selected model”
Sección titulada «“Could not complete the request with the selected model”»El proveedor del modelo devolvió un error. Vuelve a intentarlo o elige otro modelo. Si sigue ocurriendo:
- Verifica que la clave del proveedor esté en la configuración del espacio de trabajo. Un agente se guarda sin ella, pero falla en cuanto alguien le habla.
- Para Gemini o Anthropic en Vertex AI, el espacio de trabajo necesita
VERTEX_AI_SERVICE_ACCOUNT_JSONyVERTEX_AI_PROJECT_ID, y el proyecto debe tener acceso al modelo que elegiste. - Verifica que el proveedor siga ofreciendo el modelo. Los proveedores retiran modelos y, cuando lo hacen, VirtuAI los quita de la lista.
“The daily usage limit for this agent has been reached”
Sección titulada «“The daily usage limit for this agent has been reached”»Se alcanzó un presupuesto del espacio de trabajo con una acción block (el mensaje indica el período: diario o mensual). Las solicitudes nuevas se rechazan hasta que se reinicie el período o un administrador aumente el límite en Budgets. Un presupuesto con una acción warn deja pasar la solicitud e indica que se superó el límite.
Canales
Sección titulada «Canales»El agente no responde en un canal
Sección titulada «El agente no responde en un canal»- Verifica que el canal esté activado para el agente y que hayas guardado el agente.
- Verifica que las claves del canal estén en la configuración del espacio de trabajo, en el mismo espacio de trabajo que el agente.
- Verifica que el canal apunte a la URL de este agente que aparece en Integration URLs. Cada agente tiene la suya.
- Revisa la verificación del canal. VirtuAI rechaza las solicitudes que no puede verificar, así que un token de autenticación, un secreto de firma o un número de proyecto incorrecto detiene todos los mensajes. Consulta la sección siguiente.
Consulta también las secciones de solución de problemas de WhatsApp, Google Chat, Slack y Telegram.
“Web chat is not enabled for this agent”
Sección titulada «“Web chat is not enabled for this agent”»El canal Chat del agente está desactivado. Edita el agente, activa el chat y guarda.
Las solicitudes de webhook se rechazan con 401 o 403
Sección titulada «Las solicitudes de webhook se rechazan con 401 o 403»Cada canal se verifica con el mecanismo propio de su plataforma. Cuando la verificación falla, la solicitud se rechaza:
| Canal | Estado | Solución |
|---|---|---|
| 403 | La URL del webhook en Twilio debe ser exactamente la URL de WhatsApp Webhook de Integration URLs, y TWILIO_AUTH_TOKEN en Settings debe pertenecer a la cuenta de Twilio a la que pertenece el número. Consulta WhatsApp. |
|
| Google Chat | 401 | El Authentication audience de la app de Chat debe ser Project number, y GOOGLE_CHAT_PROJECT_NUMBER debe ser el número del proyecto de la app. Consulta Google Chat. |
| Slack | 403 | Guarda el agente con su Bot Token y su Signing Secret antes de que Slack verifique la URL, y verifica que el signing secret sea de la misma app de Slack. Consulta Slack. |
Telegram no devuelve un error: los mensajes que no incluyen el secreto del webhook se ignoran. Vuelve a seleccionar Register Webhook en el agente.
Cuando la aplicación obligatoria está activada, se rechaza una conexión de voz sin una clave de integración válida. Verifica que envíe una clave del espacio de trabajo del agente que no se haya revocado.
Responde el agente equivocado
Sección titulada «Responde el agente equivocado»El webhook del canal contiene el ID de otro agente. Vuelve a copiar la URL desde la sección Integration URLs del agente correcto.
Las respuestas largas de WhatsApp llegan como varios mensajes
Sección titulada «Las respuestas largas de WhatsApp llegan como varios mensajes»Es el comportamiento esperado. Las respuestas de WhatsApp de más de 1,600 caracteres se dividen en varios mensajes.
Inicio de sesión y acceso
Sección titulada «Inicio de sesión y acceso»| Mensaje | Qué significa | Qué hacer |
|---|---|---|
| “Incorrect email or password” | Las credenciales no coinciden. | Verifica la dirección con la que te invitaron. Un administrador puede restablecer tu contraseña desde Users. |
| “Native login is disabled; use SSO” | El espacio de trabajo inicia sesión a través de tu proveedor de identidad. | Usa la opción de inicio de sesión único en la página de acceso. |
| “Self-service signup is disabled. Please request an invitation.” | Las cuentas solo se crean por invitación. | Pídele a un administrador del espacio de trabajo que te invite. |
| “Your account is not a member of any workspace. Please contact an administrator.” | La cuenta existe, pero no pertenece a ningún espacio de trabajo. | Pídele a un administrador que te agregue a un espacio de trabajo. |
| “SSO access is not enabled for this email domain” | Tu dominio de correo electrónico no está vinculado al SSO de ningún espacio de trabajo. | Pídele a tu administrador que revise la configuración de SSO del espacio de trabajo. |
| “No role mapping matched your groups; access denied” | El SSO funcionó, pero ninguno de tus grupos del proveedor de identidad está asignado a un rol de VirtuAI. | Pídele a tu administrador que agregue una asignación de grupo o que te agregue a un grupo asignado. |
| “Your email domain is not authorized for this workspace” | El espacio de trabajo solo permite dominios de correo electrónico específicos. | Inicia sesión con una dirección de un dominio permitido o pídele a tu administrador que agregue el tuyo. |
Un vínculo de invitación no funciona
Sección titulada «Un vínculo de invitación no funciona»- “This invitation has expired”: las invitaciones son válidas durante 48 horas. Pídele a tu administrador que la vuelva a enviar desde Users.
- “This invitation has already been used”: la cuenta ya existe. Inicia sesión.
- “This invitation link is not valid”: es posible que tu cliente de correo electrónico haya cortado el vínculo o que se haya revocado la invitación. Pide una nueva.
Falta un elemento del menú o un botón
Sección titulada «Falta un elemento del menú o un botón»Los menús y las acciones se muestran según los permisos de tu rol. Por ejemplo, Settings e Integrations requieren settings.manage, y el Agent Builder solo está disponible para los administradores del espacio de trabajo. Pídele a un administrador que revise tu rol en Usuarios y roles.
Ves los agentes de otro equipo, o no ves los tuyos
Sección titulada «Ves los agentes de otro equipo, o no ves los tuyos»Revisa el selector de espacios de trabajo. Todo en VirtuAI pertenece a un espacio de trabajo, y nada se comparte entre espacios de trabajo.
Ingesta de la base de conocimiento
Sección titulada «Ingesta de la base de conocimiento»Un archivo no aparece después de subirlo
Sección titulada «Un archivo no aparece después de subirlo»Solo se ingieren archivos PDF, Word (.docx), Excel (.xlsx, .xls), CSV y PowerPoint (.pptx). Los archivos con otras extensiones se omiten. Primero conviértelos a un formato compatible; por ejemplo, guarda un archivo .doc como .docx.
Un documento aparece con errores
Sección titulada «Un documento aparece con errores»Cada documento pasa por uploading, processing y, luego, completed o failed. Un documento con errores muestra el motivo junto a él:
| Motivo | Causa probable | Qué hacer |
|---|---|---|
| “Failed to extract text from .pdf file” (u otra extensión) | El archivo está dañado, protegido con contraseña o es una imagen escaneada sin capa de texto. | Exporta una versión del archivo basada en texto y vuelve a subirla. |
| “No text content found after chunking” | El archivo se abrió, pero no tenía texto legible. | Verifica que el archivo tenga texto real, no solo imágenes. |
| “Failed to store embeddings” | Una falla temporal durante la indexación. | Usa Reprocess en el documento. Si vuelve a fallar, comunícate con soporte. |
La nueva configuración de fragmentos no cambia las respuestas existentes
Sección titulada «La nueva configuración de fragmentos no cambia las respuestas existentes»Cambiar la configuración de fragmentos de una base de conocimiento no vuelve a procesar los documentos que ya se subieron. Usa Reprocess en cada documento para aplicar la configuración nueva.
El agente no usa la base de conocimiento
Sección titulada «El agente no usa la base de conocimiento»- Verifica que la base de conocimiento esté asociada al agente y que sus documentos estén en estado completed.
- Haz una pregunta con las palabras que usan tus documentos y revisa el registro de trabajo del agente en Conversations para ver si hizo una búsqueda.
- Si hay muy pocos resultados o son poco precisos, ajusta la cantidad de resultados y el umbral de puntuación en la configuración de recuperación de la base de conocimiento.
Herramientas
Sección titulada «Herramientas»Se agota el tiempo de espera de una herramienta personalizada o no puede conectarse
Sección titulada «Se agota el tiempo de espera de una herramienta personalizada o no puede conectarse»El agente recibe un error como “API call to … timed out after 30 seconds” o “Failed to connect to …”. Verifica que el extremo sea accesible desde Internet y aumenta el tiempo de espera de la herramienta (hasta 300 segundos) o la cantidad de reintentos si la API es lenta. Prueba la herramienta desde el chat antes del lanzamiento del agente.
Una herramienta de MCP indica que falló la autenticación o que se denegó el acceso
Sección titulada «Una herramienta de MCP indica que falló la autenticación o que se denegó el acceso»- “Authentication failed for ‘…’ (HTTP 401). The user may need to reconnect their account.”: la autorización de la cuenta conectada venció o se revocó. Vuelve a conectarla; en el chat web, abre la lista de herramientas del agente y vuelve a conectar el servicio en las cuentas conectadas.
- “Access denied for ‘…’ (HTTP 403)”: la cuenta está conectada, pero no tiene el permiso que necesita la herramienta. Otórgalo en el servicio externo.
- “The tool ‘…’ is temporarily unavailable (HTTP 5xx from the MCP server)”: falló el servidor externo. Vuelve a intentarlo en un momento.
Si falla un servidor de MCP, las demás herramientas del agente siguen funcionando.
El agente pide aprobación antes de ejecutar un comando
Sección titulada «El agente pide aprobación antes de ejecutar un comando»Antes de que un agente ejecute un comando de shell en su entorno de ejecución, le pide aprobación a la persona que participa en la conversación. Si nadie responde en 5 minutos, la solicitud se considera denegada, y una respuesta tardía muestra “That approval request is no longer waiting (it may have timed out).” Pídele al agente que vuelva a intentarlo.
La voz en el navegador no se inicia
Sección titulada «La voz en el navegador no se inicia»- Verifica que voice y el web voice widget estén activados para el agente. De lo contrario, el widget informa que la voz web no está habilitada para el agente.
- Permite el acceso al micrófono cuando el navegador lo solicite. Si lo bloqueaste antes, vuelve a habilitarlo en la configuración del sitio del navegador.
- Verifica la clave del proveedor de voz en la configuración del espacio de trabajo:
GOOGLE_API_KEYpara las voces de Gemini oELEVENLABS_API_KEYpara ElevenLabs.
Un mensaje de voz en el chat web no se transcribe
Sección titulada «Un mensaje de voz en el chat web no se transcribe»- Los mensajes de voz en el chat web necesitan una cuenta de servicio de Vertex AI en la configuración del espacio de trabajo. Sin ella, se informa que la transcripción no está disponible.
- Un mensaje de voz puede ocupar como máximo 5 MB. Graba un mensaje más corto.
- Si no se detectó voz, vuelve a grabar más cerca del micrófono.
- Si el navegador informa que no admite la grabación de voz, actualízalo o cambia a otro navegador actual.
¿Aún tienes problemas?
Sección titulada «¿Aún tienes problemas?»Comunícate con el equipo de soporte e incluye el espacio de trabajo, el ID del agente, el canal y la hora en que ocurrió el problema.