Conexiones con tu agente de IA

Por qué la Connection es un objeto aparte

El test (qué probar) y la conexión (contra qué probar) son piezas separadas y reutilizables:

• Un mismo Test Plan puede correrse contra distintas conexiones sin tocar nada del plan — por ejemplo, mismo TP contra el agente de IA en staging y producción.
• Una misma conexión sirve para N test plans diferentes en el mismo proyecto.
• Cuando haces Execute, la plataforma te pide elegir la conexión a usar para esa corrida específica.

Cómo crear una conexión

Ve a Configuration → AI Agents → Add Connection.

El formulario te pide:

• Name — nombre identificable (ej: "agente de IA prod", "Soporte staging").
• Base URL — el endpoint o sitio del agente de IA.
• Protocol — HTTP o Browser (Playwright). Define el resto de campos del form.
• Environment — Production / Staging / Dev. Solo para identificación.
• Description — opcional.

Protocolo Browser (Playwright)

Para agentes de IA embebidos en una página web. ArtificialQA corre Chromium en modo headless en sus workers en la nube y simula las acciones de un usuario contra tu sitio. Tú no abres ni ves Chromium — todo el render pasa del lado del servidor.

Disponible en todos los planes (incluyendo Free).

Browser Configuration

• Chat URL (requerido) — la URL exacta donde está el chat.
• Login URL (opcional) — si el chat requiere login y vive en otra URL distinta a la de chat.

Login Steps

Array JSON con la secuencia de pasos para autenticarte antes de llegar al chat. Acciones soportadas: fill, click, wait, navigate. Por ejemplo: completar usuario, completar contraseña, clic en "Iniciar sesión".

Post-Navigation Steps

Array JSON con pasos que se ejecutan después de cargar la página del chat. Ejemplo típico: hacer clic una pestaña específica, abrir el panel del bot, etc.

Element Selectors

Selectores CSS para los elementos clave del chat:

• Chat Input — dónde escribe el usuario.
• Send Button — el botón de enviar.
• Response Area — dónde aparece la respuesta del bot.
• Response Complete Indicator — un elemento que aparece solo cuando el bot terminó de responder (ej: el botón "Copiar"). Útil para capturar respuestas vía clipboard cuando el bot tiene streaming.

Estos selectores son opcionales — si los dejas vacíos, ArtificialQA usa auto-detección con IA para identificarlos. Solo tienes que llenarlos manualmente si la auto-detección no funciona en tu sitio.

AI Locator Provider

El LLM que la plataforma usa para auto-detectar selectores cuando los hints CSS fallan. Si lo dejas vacío, se usa el provider por default configurado a nivel sistema.

Timeouts

• Response Wait (ms) — cuánto esperar la respuesta del bot. Default: 30.000 ms.
• Navigation Timeout (ms) — cuánto esperar a que cargue la página de chat. Default: 30.000 ms.

Toggles

• Headless mode — el browser corre sin ventana visible (más rápido). Activado por default. La ejecución sucede en nuestros workers en la nube, así que para ti como usuario no hay diferencia visible — el toggle existe para configuración interna.
• Keep chat session — controla si la página se mantiene entre test cases o se recarga.
  • Activado: mantiene la sesión a lo largo de varios casos. Útil cuando el agente de IA guarda contexto y no quieres perderlo.
  • Desactivado: recarga la página antes de cada test case (clean state). Útil cuando quieres que cada caso arranque desde cero, sin contaminación del anterior.
• Navigation mode: Automatic — Playwright navega y hace login por sí solo siguiendo los Login Steps definidos. Es el modo soportado actualmente. (Existe un modo "Manual" planeado en el form que todavía no está habilitado en esta versión.)

Protocolo HTTP/API (plan Pro o Enterprise)

Para agentes de IA que exponen un endpoint propio. La forma más limpia y eficiente cuando tienes acceso al API. No usa Login Steps — la autenticación va en el header del request.

Datos básicos

• Base URL — el endpoint del agente.
• Method — GET o POST.

Authentication

El form ofrece 4 opciones:

• Bearer Token — el formato más común. Pegas el token y la plataforma manda Authorization: Bearer <token>.
• API Key — clave en header o query parameter. Configuras el nombre del campo y el valor.
• Custom Headers — para esquemas de autenticación no estándar. Defines pares clave/valor arbitrarios.
• None — para endpoints abiertos sin autenticación.

Message Configuration

• Request body template (JSON) — el cuerpo del request que le mandas al agente de IA. La plataforma trae un template estilo OpenAI (model + messages[]) que puedes ajustar.
• Input field path — el path JSON donde se inyecta el texto del usuario (por ejemplo messages[0].content).
• Output field path — el path donde se extrae la respuesta del bot (por ejemplo choices[0].message.content).

Conversation Mode (para casos multi-turno)

Define cómo se mantiene el contexto entre turnos en una conversación:

• Message History — cada turno manda toda la historia de la conversación dentro del request body. Estilo OpenAI.
• Conversation ID — el agente de IA mantiene la sesión por su lado y la plataforma le manda el ID para que recuerde el hilo.
• None — cada turno se manda como independiente (útil para agentes de IA stateless).

Si eliges Message History, el form te pide el History field path (dónde va el array de mensajes en el body del request, ej: messages).

Test Connection

Una vez guardada la conexión, usa el botón Test Connection para validarla. La plataforma manda un mensaje de prueba y te muestra qué se envió, qué se recibió y cuánto tardó. Si falla, verás el error exacto:

• Timeout — el agente de IA no respondió en el tiempo configurado.
• 401 / 403 — credenciales inválidas o vencidas (HTTP).
• Selector no encontrado (Browser) — los selectores no matchean en el DOM. Prueba con auto-detección en blanco para que la IA los identifique.
• Output path inválido (HTTP) — el response no tiene el campo donde esperabas la respuesta.

Múltiples entornos del mismo agente de IA

Un patrón común: tienes tu agente de IA en Dev, Staging y Producción. Creas 3 conexiones (una por entorno) usando el campo Environment. Después corres el mismo Test Plan contra cualquiera de ellas eligiendo la conexión al hacer Execute.

Errores comunes

• "Test Connection falla con 401." Verificá que el token / API key sea el correcto y que no esté vencido.
• "El agente de IA responde, pero la plataforma dice que no encontró respuesta." Revisa el Output field path — el response real puede estar en un campo distinto.
• "Selector no encontrado en Browser." El DOM cambió, o tu sitio tiene un layout que no detecta auto. Llená manualmente los selectores de Chat Input / Send Button / Response Area.
• "La conexión funciona suelta pero falla durante un Run." Probablemente el agente de IA está rate-limiteando o tu sesión expiró entre TCs. Prueba ajustar los Login Steps o usar "Keep chat session: OFF" para refresh entre casos.

Próximo paso

Una vez que tienes la conexión configurada y validada con Test Connection, puedes ejecutar Test Plans usándola.