Agentes

Un Agente es una automatización de navegador que describes en lenguaje natural en lugar de programarla. Le das una misión y una URL de inicio; abre un navegador real en la nube, recorre el sitio (navega, llena formularios, hace clic, lee, descarga) y devuelve datos que coinciden con el esquema de salida que definiste.

La diferencia con un scraper está en el mantenimiento. Un scraper es una lista de selectores CSS que se rompe cuando rediseñan el sitio. Un Agente lee la página en la que está y decide qué hacer, así que un botón que cambió de lugar o un campo con otro nombre no requiere cambiar código.

Usa un Flow cuando los datos están en un documento que recibiste. Usa un Agente cuando los datos viven en un sitio web, o cuando hay que hacer algo en un sitio web con datos que ya tienes.

Los Agentes están en Agentes, en la barra lateral. Puedes empezar con un Agente en blanco o construirlo a partir de un Flow existente, para que los campos de salida del Flow lleguen ya configurados como variables de entrada.

1. 1Haz clic en Crear Agente (o Nuevo desde Flow) y ponle nombre al Agente.
2. 2En la pestaña Configuración del Agente, escribe la Misión y la URL de inicio.
3. 3Agrega las Variables que necesita la misión y las Capturas que quieres de vuelta.
4. 4Haz clic en Guardar, luego en Run de prueba, y mira el Run en vivo.
5. 5Cuando el resultado sea correcto, configura la Entrega y activa el Agente con el interruptor de la barra superior.

Un Agente nuevo empieza como borrador. El interruptor de activación de la barra superior controla si se ejecuta según su programación. Al duplicar un Agente se copia su configuración, pero no los valores secretos ni la programación, así que una copia nunca se pone a ejecutarse sola.

Un Agente se configura con cinco piezas: qué hacer, dónde empezar, qué sabe de antemano, qué debe traer de vuelta y a dónde va eso.

Cada variable tiene un nombre, un tipo (text, number, boolean, date, object o list) y un origen. La misión se refiere a las variables por su nombre.

Variables secretas. Una variable estática de texto se puede marcar como Secreto, por ejemplo para la contraseña de un portal. Su valor se guarda cifrado y nunca aparece en la configuración del Agente, en las entradas o salidas del Run ni en el registro de pasos.

• Solo Propietarios y Administradores, los únicos que pueden editar un Agente, pueden definir o borrar un secreto
• Los secretos deben tener al menos 6 caracteres; una vez guardado, el campo indica que hay un valor sin mostrarlo
• El Agente escribe el secreto en la página por su nombre, sin ver nunca el valor
• Un secreto solo se puede escribir en el sitio de la URL de inicio (el mismo host o uno de sus subdominios)
• Si el valor de un secreto aparece en el texto de la página, se enmascara como *** en los pasos y en la salida

Las capturas declaran la forma del resultado. Cada una tiene un nombre, un tipo y una descripción opcional, y admiten estructuras anidadas, así que un Agente puede devolver una lista de objetos en lugar de un bloque de texto que tengas que procesar después.

Dale a un Agente una captura de tipo file y podrá traer documentos además de leerlos: un estado de cuenta detrás de un inicio de sesión, el PDF de una factura en un portal. Puede descargar un archivo desde un enlace, o hacer clic en un botón de descarga y quedarse con el archivo que devuelva el sitio.

Superar un límite no detiene el Run: al Agente se le avisa que el archivo era demasiado grande y sigue con el resto de la misión. Si un sitio responde a una descarga con una página web en lugar de un archivo (una pantalla de inicio de sesión, por ejemplo), el Agente recibe ese aviso en vez de guardar la página como si fuera el documento.

Algunos portales envían por correo un código de acceso de un solo uso o un enlace de confirmación. Conecta un buzón y el Agente podrá esperar ese correo, leer el código o el enlace y continuar. Se configura en Ajustes → Buzón (el panel Configuración del grupo Ajustes).

• El buzón se lee por IMAP en modo de solo lectura; nada se marca como leído ni se modifica
• Solo cuenta un mensaje que llegue después de iniciado el Run, gana la coincidencia más reciente y cada mensaje se usa una sola vez
• El Agente espera el correo hasta 5 minutos, revisando cada 10 segundos
• Si no llega nada, el Agente recibe el aviso y tu misión decide qué hacer (reenviar el código o detenerse)
• Para Gmail o Google Workspace, activa la verificación en dos pasos y crea una contraseña de aplicación

Dilo también en la misión: “Después de enviar el formulario de acceso, espera el correo de verificación e ingresa el código.”

La configuración más potente es extraer y luego actuar. Un Flow saca campos de un documento y el Agente usa esos campos como entradas, así que el documento que recibiste determina lo que pasa en el sitio web de otro, sin copiar nada a mano.

1. 1En el Agente, agrega variables con el origen From flow run y elige el campo del Flow que lee cada una (o usa Nuevo desde Flow para crearlas todas de una vez).
2. 2Abre el Flow y selecciona el panel Agente en su barra lateral.
3. 3Haz clic en Vincular Agente y elige el Agente.
4. 4Ejecuta el Flow. Cuando el Run termina, el Agente arranca automáticamente con la salida del Flow como entrada.

• El Agente recibe la salida limpia cuando el Flow tiene un Cleaner
• Si el Flow usa Revisión Humana, el Agente se ejecuta solo después de que un revisor aprueba, con los datos aprobados; un Run rechazado nunca llega al Agente
• Las entregas y los webhooks de un Run de Agente iniciado por un Flow llevan el ID de ese Run del Flow
• En un Pipeline, un nodo Agente hace lo mismo sobre un lienzo, alimentado por un nodo de Flow

Ejemplo. Llega una orden de compra por correo. El Flow extrae el proveedor y los números de parte, y un Cleaner los normaliza. El Agente vinculado entra al portal del proveedor, busca las partes, captura el precio unitario vigente y el plazo de entrega, y escribe los resultados en un Bucket junto a lo que decía la orden, así la diferencia se ve antes de que alguien la apruebe.

Un Agente puede entregar cada Run completado a varios destinos a la vez. Activa todas las entregas que necesites en la pestaña Entrega; se ejecutan de forma independiente, así que si una falla las demás siguen. Si no activas ninguna, los resultados quedan en la página del Run para verlos o descargarlos.

Las entregas por Email y Bucket tienen la opción Incluir las variables de entrada en el payload entregado, que hace que una fila del Bucket se explique sola: qué se pidió y qué volvió. El webhook siempre las incluye.

El payload del webhook lleva bot_id, bot_run_id, status, inputs (las variables de entrada resueltas del Run, sin los secretos), output (las capturas, con un enlace por archivo) y, cuando el Run de un Flow disparó al Agente, flow_run_id, para que tu sistema pueda asociar el resultado al documento del que salió.

{
  "bot_id": "3f2a...",
  "bot_run_id": "9c41...",
  "status": "completed",
  "flow_run_id": "b7e0...",
  "inputs": { "part_number": "AX-2210" },
  "output": { "unit_price": 18.4, "lead_time": "3 weeks" }
}

Si una entrega falla, el Run queda como Completado con advertencias y su página muestra los Errores de entrega. Quien creó el Agente recibe además una notificación en la app.

Un Agente puede arrancar de cinco maneras. Arranque como arranque, pasa por los mismos límites y las mismas entregas.

Programación. Activa Ejecutar de forma programada y elige una frecuencia: Cada hora, Cada día, Días hábiles (lun–vie), Cada semana o Cron personalizado (cinco campos: minuto, hora, día del mes, mes, día de la semana; por ejemplo 30 8 * * 1-5). Las horas están en la zona horaria de tu organización, y el panel muestra el Próximo Run.

• Los Runs programados usan las variables estáticas y los secretos guardados en el Agente
• La programación solo se ejecuta mientras el Agente está activo
• Los Runs arrancan aproximadamente un minuto después de la hora programada, o más tarde si todos los workers están ocupados
• Una ventana perdida no se repite: tras un retraso, el Agente se ejecuta una vez, no una por cada horario perdido
• Un Run programado que no puede arrancar (el Run anterior sigue en curso o tu organización no puede iniciar trabajo nuevo en este momento) aparece como un Run fallido que explica el motivo
• Las fallas de los Runs programados y por API generan una notificación en la app para quien creó el Agente, ya que nadie está mirando la página del Run

Por defecto, los disparadores que se solapan se ejecutan en paralelo. A muchos portales no les gustan dos sesiones del mismo usuario a la vez, así que un Agente se puede configurar para ejecutar un Run a la vez en Ajustes → Concurrencia.

• Un Run que espera su turno muestra el estado En espera; no ocupa un worker
• Pueden esperar hasta 20 Runs por Agente; a partir de ahí se rechazan los nuevos disparadores (la API responde 429)
• Un Run que espera más de 24 horas se marca como fallido
• Solo espera un Run programado a la vez, así que un Agente lento con una programación frecuente no acumula Runs

Cada Run transmite sus pasos a medida que ocurren, y puedes abrir una vista en vivo de la sesión del navegador para verlo trabajar. Los Runs terminados guardan una repetición, así ves exactamente qué hizo el Agente en lugar de deducirlo de la salida.

• Pasos: un registro de lo que hizo el Agente, en orden
• Salida capturada y Archivos capturados, con descargas
• Resumen: duración, llamadas LLM y tokens
• Ver sesión en vivo mientras se ejecuta y Ver repetición de sesión después
• Identificadores (ID del Run e ID de Sesión) para las solicitudes de soporte

Cancelar Run detiene un Run en espera, en cola o en ejecución. La sesión del navegador termina en pocos segundos y no se entrega nada.

Los Runs tienen topes para que una misión que sale mal no se ejecute para siempre. Hay dos límites, ambos configurables por Agente en Ajustes → Límites. Deja un campo vacío para usar el valor predeterminado.

Tus propios sistemas pueden iniciar un Agente y consultar el resultado con tu API key, enviada como X-API-Key a https://run.tavnit.io/api. El ID del Agente está en su panel ID del Agente.

Cada llamada a la API inicia un Run nuevo. Un 402 significa que tu organización no puede iniciar trabajo nuevo en este momento; contacta al equipo de Tavnit. Para la referencia completa de solicitudes y respuestas, consulta la página de la API. Si prefieres no llamar al Agente directamente, dispara el Flow vinculado y deja que el Agente lo siga.

Solo Propietarios y Administradores pueden crear, editar, duplicar o eliminar un Agente, lo que incluye definir secretos. Los Miembros pueden ejecutar Agentes y ver sus Runs. Los miembros Solo HITL no tienen acceso a los Agentes.

Consulta roles de usuario y permisos para la matriz completa.