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, list o file) y un origen. La misión se refiere a las variables por su nombre.

Variables de archivo. Una variable de tipo file le entrega al Agente el documento original de un Run de un Flow para que lo suba al sitio (una factura a un portal de aduanas, por ejemplo). Configúrala como Documento del Run que lo dispara para recibir el documento del Run del Flow que arrancó al Agente, o dale un ID de Run; un Run de prueba o una llamada a la API pueden enviar otro ID de Run en cada Run. El Run debe ser de tu organización; si no, el Run del Agente falla antes de abrir el navegador, sin cobrar nada.

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 seis maneras. Arranque como arranque, pasa por los mismos límites, la misma concurrencia 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

Disparo por bucket. En Ajustes → Disparo por bucket, activa Un Run por cada fila que cumpla la condición para arrancar un Run por cada fila de un Bucket que pase tus filtros, por ejemplo un Run por cada lead cuyo estado todavía no sea completo. Elige la Clave de la fila que la identifica y qué columnas llenan qué variables de entrada.

• El Bucket se revisa cada 30 segundos aproximadamente; una fila cuyo Run sigue en curso nunca recibe un segundo Run
• Cada fila tiene un número limitado de intentos por 24 horas (de 1 a 10, 3 por defecto), con al menos 10 minutos entre uno y otro
• El ritmo lo marca el límite de concurrencia del Agente: N Runs trabajan mientras otros N esperan, y el disparo mantiene el límite activado
• Cierra el ciclo con una entrega a Bucket que actualice la misma fila (estado = completo), así una fila procesada deja de cumplir la condición
• Si el Bucket ya no existe o se acaban los créditos, el disparo se pausa y un Run fallido explica el motivo

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, y a algunos sitios no conviene saturarlos, así que un Agente se puede limitar a un Run a la vez, o hasta diez, en Ajustes → Concurrencia.

• Un Run que espera su turno muestra el estado En espera; no ocupa un worker ni se cobra
• 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
• Sesiones del navegador: una entrada por cada sesión del navegador cuando el Run se pausó por una persona y se reanudó
• Identificadores (ID del Run e ID de Sesión) para las solicitudes de soporte

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

Algunos pasos solo los puede hacer una persona: un captcha, un código enviado al teléfono del titular de la cuenta, un inicio de sesión que alguien tiene que aprobar. Activa Ajustes → Ayuda humana y el Agente puede detenerse a pedir ayuda en lugar de fallar, y luego seguir con la misión.

1. 1El Agente pide ayuda. Quien lanzó el Run (o quien creó el Agente) recibe una notificación en la app que abre la página del Run.
2. 2El Run sigue En ejecución con el navegador abierto. La página del Run muestra El agente necesita tu ayuda con lo que pide, encima de la sesión en vivo.
3. 3Haz lo que pide en la sesión en vivo, deja si quieres una Nota para el agente (“escribí el código del SMS e inicié sesión”) y pulsa Listo — continuar. El Agente lo retoma en unos segundos, en el mismo navegador.
4. 4Si nadie llega dentro de la espera, se cierra el navegador y el Run queda guardado donde estaba, con el estado Esperando a una persona. Pulsa Reanudar run cuando puedas: se abre un navegador nuevo en la misma página, con la sesión todavía iniciada, y el Agente sigue donde quedó. Si el obstáculo sigue ahí vuelve a pedir ayuda, así que quédate en la página del Run.

• La espera cuenta dentro de la Duración máxima y se cobra como minutos de navegador; el Agente siempre conserva unos dos minutos para terminar después de una espera
• Un Run en pausa no ocupa navegador ni worker y no cuesta nada mientras espera; reanudarlo pide el mismo saldo mínimo de un minuto que un Run nuevo
• Reanudar continúa el mismo Run: los pasos, las capturas, la duración y los créditos se suman, y Sesiones del navegador lista cada sesión con su repetición
• Un Run en pausa se puede reanudar durante 72 horas; después se marca como fallido. Un Run puede usar hasta 10 sesiones del navegador
• Un Run en pausa se puede cancelar; libera su lugar de concurrencia, pero su programación y su fila del disparo por bucket lo siguen contando como en curso

Dilo también en la misión, para que el Agente sepa cuándo pedir ayuda: “Si aparece un captcha o un código de verificación, pide ayuda y espera.” Para los códigos que llegan por correo, un Buzón (arriba) no necesita a ninguna persona.

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. Nombra al Agente por su ID, que está en su panel ID del Agente, o por su nombre.

Por nombre. bot_name debe coincidir con el nombre del Agente tal como aparece en la app, sin distinguir mayúsculas ni espacios de más. Los Agentes archivados con el mismo nombre se ignoran (un nombre que solo tiene un Agente archivado responde 409, Agente archivado). Si no coincide ninguno responde 404; si varios Agentes activos comparten el nombre responde 409 con sus IDs en bot_ids, así que renombra uno o usa el ID. Renombrar un Agente cambia lo que debe decir bot_name: usa bot_id en las integraciones que deban sobrevivir a un cambio de nombre.

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, ver sus Runs, ayudar a un Run que pide una persona y reanudar uno en pausa. Los miembros Solo HITL no tienen acceso a los Agentes.

Consulta roles de usuario y permisos para la matriz completa.