Nota del autor: desde la instalación hasta el uso de snapshot y ref y la verificación de resultados, domina en 5 pasos el ciclo de agent-browser: «leer la página, interactuar con un elemento y volver a leer la página». Así podrás hacer que un AI Agent controle un navegador real de forma fiable.
Uno de los problemas habituales al pedirle a un AI Agent que interactúe con una página web es que no puede verla y le cuesta seleccionar los elementos correctos de forma fiable. Usar capturas de pantalla y hacer clic por coordenadas consume muchos tokens y puede fallar; entregar todo el HTML al modelo llena rápidamente la ventana de contexto. En este artículo conocerás el ciclo de operación snapshot-ref de agent-browser y aprenderás a hacer que un Agent controle el navegador «un comando a la vez».
Esto no es otra introducción teórica a los frameworks de automatización de navegadores. Seguiremos el orden de uso real: instalación de agent-browser, combinación de snapshot y ref, estrategias para reintentar tras un fallo e integración en el flujo de trabajo de un Agent.
Qué aprenderás: al terminar, entenderás por qué el ciclo snapshot-ref de agent-browser es adecuado para los Modelos de Lenguaje Grande y podrás completar tu primera tarea de navegador con tu propio Agent y 5 comandos.
Claves del ciclo snapshot-ref de agent-browser
agent-browser es una herramienta de automatización de navegadores de código abierto de Vercel Labs, publicada bajo la licencia Apache-2.0. Es una CLI nativa en Rust con un objetivo claro: dar a los agentes de IA un navegador que puedan controlar comando a comando. Tras abrir una página, el agente la lee como texto compacto en forma de árbol de accesibilidad y ejecuta acciones sobre sus elementos mediante comandos de shell.
| Punto clave | Descripción | Ventaja para el agente |
|---|---|---|
| Texto compacto de snapshot | La página se muestra como un árbol de accesibilidad, con una referencia como @e1 para cada elemento |
Consume menos contexto que una captura de pantalla o el HTML sin procesar |
| Localización precisa mediante ref | Los comandos de acción usan directamente la referencia, como en click @e1 |
El modelo no tiene que construir selectores CSS por su cuenta |
| Navegador siempre activo | Un proceso en segundo plano mantiene abierto el navegador | Cada paso requiere solo una breve llamada al shell |
| Errores explícitos | Si un elemento está cubierto, oculto o deshabilitado, el clic falla en lugar de aparentar que tuvo éxito | El agente puede decidir el siguiente paso a partir de la respuesta real |
| Skills integradas | La CLI incluye instrucciones de uso acordes con su versión | El agente lee instrucciones que coinciden con la versión instalada |
Cómo funciona el ciclo snapshot-ref
Este ciclo se resume en tres acciones: primero se lee la página con snapshot, después se ejecuta una acción sobre un ref y, por último, se vuelve a leer la página para comprobar el resultado. El proceso se repite tantas veces como sea necesario. La instantánea de example.com que ofrece la documentación oficial tiene una sola línea: - link "Learn more" [ref=e1]. Al verla, el modelo sabe que la página contiene un enlace llamado Learn more y que puede hacer clic en él usando @e1.
Este diseño separa la «comprensión de la página» y la «ejecución de acciones» en dos pasos verificables, lo que encaja muy bien con el uso de herramientas por parte de un Modelo de Lenguaje Grande. El modelo no necesita entender una estructura DOM compleja: basta con que encuentre en el texto el elemento correcto por su significado y use el ref correspondiente. Al tomar una nueva instantánea después de cada acción, el agente siempre toma decisiones basadas en el estado más reciente de la página, en lugar de depender de su memoria o hacer suposiciones.
La arquitectura interna de agent-browser
La CLI no controla directamente el navegador. Al ejecutar el primer comando, se inicia un proceso en segundo plano (daemon) que controla el navegador mediante Chrome DevTools Protocol. Cada comando posterior de la CLI se envía a ese proceso. Así, el navegador permanece abierto entre comandos y se conservan tanto la sesión iniciada como la posición en la página.
Cada --session tiene su propio daemon y navegador, lo que permite ejecutar varias tareas en paralelo sin que interfieran entre sí. De forma predeterminada, el navegador sin interfaz gráfica se cierra tras una hora sin recibir comandos y el daemon finaliza. Si se configuró la persistencia de sesión (session persistence), el estado se guarda antes de salir.
El «cerebro» que impulsa este ciclo es un Modelo de Lenguaje Grande. En cada ronda, el texto de la instantánea se incorpora al contexto del modelo, que decide cuál será el siguiente comando. Por eso, su capacidad para seguir instrucciones y su precio unitario influyen directamente en la tasa de éxito y el costo de las tareas. APIYI ofrece acceso por API a los modelos mencionados en este artículo, como Claude, DeepSeek y Kimi, con compatibilidad con los formatos de interfaz de OpenAI y Anthropic. La documentación de integración está disponible en docs.apiyi.com.
Inicio rápido de agent-browser: completa el ciclo snapshot-ref en 5 pasos
Paso 1: instala agent-browser y el navegador
La forma más habitual es instalarlo globalmente con npm y luego descargar Chrome for Testing. El paquete npm selecciona automáticamente el binario nativo correspondiente a la plataforma. Actualmente es compatible con macOS (ARM64, x64), Linux (ARM64, x64, glibc y musl) y Windows (x64).
| Método de instalación | Comando | Cuándo usarlo |
|---|---|---|
| Instalación global con npm | Primero npm install -g agent-browser y luego agent-browser install |
La mayoría de los entornos de desarrollo; la primera vez hay que descargar el navegador |
| Homebrew | Primero brew install agent-browser y luego agent-browser install |
Usuarios de macOS |
| Linux con dependencias | agent-browser install --with-deps |
Servidores y contenedores que también necesitan las bibliotecas de sistema del navegador |
| Sin instalación | npx agent-browser open example.com |
Pruebas rápidas o tareas puntuales en CI |
| Comandos de mantenimiento | agent-browser upgrade, agent-browser doctor |
Actualizar la versión o diagnosticar problemas del entorno |
Si quieres compilarlo desde el código fuente, la documentación oficial exige Node.js 24 o superior, pnpm 11 o superior y la cadena de herramientas de Rust. Ejecuta, en este orden, pnpm install, pnpm build:source y pnpm link --global. Por último, ejecuta agent-browser install. Para el uso habitual, basta con instalarlo directamente mediante npm.
Pasos 2 a 5: el ciclo mínimo completo
Una vez terminada la instalación, este conjunto de comandos completa un ciclo de snapshot-ref. Conviene ejecutarlo primero a mano en la terminal y comprobar la salida de cada paso antes de dejar que el Agent lo haga automáticamente.
| Paso | Comando | Función | Resultado esperado |
|---|---|---|---|
| 2. Abrir la página | agent-browser open example.com |
Inicia el daemon y abre la dirección | El navegador permanece activo en segundo plano |
| 3. Leer la instantánea | agent-browser snapshot -i |
Lista solo los elementos interactivos, cada uno con su ref | Una salida como link "Learn more" [ref=e1] |
| 4. Interactuar con el ref | agent-browser click @e1 |
Hace clic en un elemento de la instantánea | La página cambia o se actualiza su estado |
| 5. Comprobar el resultado | agent-browser get url |
Lee la URL actual para confirmar que la acción funcionó | Devuelve la dirección de destino |
| Cierre | agent-browser close |
Cierra el navegador | Libera los recursos |
El parámetro -i del paso 3 es clave: solo muestra los elementos interactivos y reduce considerablemente el texto de la instantánea, algo especialmente útil cuando el presupuesto de tokens es limitado. Tampoco conviene omitir la comprobación del paso 5: el Agent debe basarse en la respuesta real para determinar si la operación tuvo éxito, en lugar de asumir que hacer clic basta.
🚀 Inicio rápido: una vez que hayas completado el ciclo manualmente, puedes pasarle estos comandos al Agent. Primero, puedes obtener crédito de prueba a través de APIYI apiyi.com y probar varios modelos con las mismas tareas para ver cuál elige mejor el ref correcto a partir del texto de la instantánea. La interfaz es compatible con los formatos de OpenAI y Anthropic, por lo que en la mayoría de los frameworks de Agent existentes basta con cambiar la clave y la dirección. Consulta la documentación de docs.apiyi.com para más detalles.
Vigencia de los ref de agent-browser y nuevas capturas
Un ref describe la página en el momento de la captura. Si la página navega a otra dirección o cambia el DOM, el ref anterior puede dejar de ser válido o incluso apuntar al elemento equivocado. Por eso, la regla de oro es: después de cada navegación o cambio importante en la página, ejecuta snapshot de nuevo antes de usar el nuevo ref.
Conviene incluir esta regla directamente en la indicación de sistema del agente. Un ciclo fiable sería «captura, acción, captura», en lugar de «una captura y diez acciones seguidas». El costo de una captura adicional es mucho menor que el de investigar y revertir los efectos de un clic en el elemento equivocado.
Qué hacer cuando falla un clic en agent-browser
agent-browser no «finge que el clic funcionó». Si el elemento de destino está oculto, deshabilitado, fuera del área visible o tapado por otro elemento —como una ventana de consentimiento de cookies—, click devuelve un error. Esto le resulta muy útil al agente, porque el propio mensaje de error sirve para decidir el siguiente paso.
| Causa del fallo | Ejemplo típico | Acción recomendada |
|---|---|---|
| Elemento tapado | Una ventana de consentimiento o una capa flotante cubre el botón | Cierra primero el elemento que lo tapa, toma una nueva captura y vuelve a intentarlo |
| Fuera del área visible | El elemento está más abajo en la página | Desplázate con scroll y toma una nueva captura |
| Elemento deshabilitado | No se puede hacer clic en el botón porque el formulario está incompleto | Completa los campos obligatorios con fill y toma una captura para comprobarlo |
| Elemento oculto | Hay que desplegar un menú para que aparezca | Haz clic para desplegarlo, espera con wait y toma una captura |
| ref caducado | La página ha navegado a otra dirección o se ha recargado | Ejecuta snapshot de nuevo para obtener un ref actualizado |
Además de los ref, agent-browser admite selectores CSS, texto, XPath y localizadores semánticos. Por ejemplo, agent-browser find role button click --name "Submit" permite encontrar el botón de envío por su rol y nombre, y hacer clic en él. Cuando la estructura de la página es estable y la función de los elementos está bien definida, los localizadores semánticos pueden complementar los ref.
Grupos de comandos habituales de agent-browser
agent-browser cuenta con una amplia variedad de comandos. Puedes consultar la lista completa con agent-browser --help y la ayuda de un comando específico con agent-browser <command> --help. Estas son las categorías más habituales, para que decidas qué capacidades poner a disposición del agente.
| Grupo | Comandos principales | Usos habituales |
|---|---|---|
| Navegación y lectura | open、back、reload、read、snapshot、get、is |
Abrir páginas, leer instantáneas y consultar estados |
| Interacción | click、fill、type、press、select、check、scroll、upload、find |
Hacer clic, rellenar formularios y subir archivos |
| Espera | wait |
Esperar a que aparezca un elemento o se cargue una página |
| Captura | screenshot、pdf、record、download、diff |
Capturar pantallas, exportar PDF, grabar la pantalla y comparar páginas |
| Estado de página y red | cookies、storage、network、eval |
Gestionar cookies, interceptar tráfico de red y ejecutar scripts |
| Pestañas y ventanas emergentes | tab、frame、dialog |
Gestionar varias pestañas, iframes y cuadros de diálogo |
| Depuración y rendimiento | console、errors、trace、vitals、a11y |
Recopilar errores de consola y métricas de rendimiento |
| Sesiones y autenticación | session、state、auth、confirm、deny |
Aislar sesiones, gestionar el estado de autenticación y confirmar operaciones sensibles |
| Integración con agentes | skills、mcp、flow、batch、plugin |
Cargar habilidades e iniciar servicios MCP |
En cuanto al motor del navegador, se utiliza Chrome for Testing de forma predeterminada. También puedes usar --cdp o --auto-connect para conectarte a una instancia de Chrome que ya esté en ejecución, cambiar al motor Lightpanda u Obscura con --engine, controlar Mobile Safari en un simulador de iOS o conectarte a servicios de navegador en la nube como Browserbase, Browserless, Browser Use, Kernel o AgentCore.
Integra agent-browser con un agente de IA
Enseña al agente con las skills integradas
Una función ingeniosa de agent-browser es que distribuye las instrucciones de uso junto con la CLI. Al ejecutar agent-browser skills get core, obtienes el ciclo principal, el uso de ref, las estrategias de espera y los flujos de trabajo habituales. Si añades --ref commands, puedes consultar una referencia específica, como la lista completa de comandos; con --full, también obtienes la referencia completa de comandos y las plantillas. Por su parte, agent-browser skills list muestra skills especializadas como electron, slack y dogfood.
En un framework de agentes, puedes instalar la skill con npx skills add vercel-labs/agent-browser. Esta skill es solo una guía mínima: indica al agente que cargue agent-browser skills get core, de modo que las instrucciones siempre coincidan con la versión instalada de la CLI. Si prefieres no instalarla, también puedes añadir una línea en AGENTS.md: usa agent-browser para automatizar el navegador y, antes de utilizarlo por primera vez, ejecuta agent-browser skills get core y sigue sus instrucciones.
Integración mediante MCP
Si tu cliente admite MCP, ejecuta agent-browser mcp para iniciar un servidor MCP a través de stdio. Así, los clientes de escritorio como Claude o los agentes propios pueden invocar las operaciones del navegador como herramientas estándar, sin tener que crear una capa de ejecución de shell.
Elige un modelo para el ciclo snapshot-ref
Las tareas de navegador suelen tener muchas rondas y cada una incluye un fragmento de texto con la instantánea. Por eso, los tokens de entrada suelen superar ampliamente a los de salida. Al elegir un modelo, además de su capacidad para seguir instrucciones, conviene fijarse en el precio de entrada y el de caché. Los precios de la siguiente tabla se basan en los datos reales de la página de precios de APIYI, docs.apiyi.com/models; consulta esa página para conocer las unidades y los criterios de facturación.
| Modelo | Precio de entrada | Precio de salida | Precio de caché | Uso recomendado | Plataforma disponible |
|---|---|---|---|---|---|
| claude-opus-5-5 | $4 | $20 | $0.2 | Tareas complejas de varios pasos y páginas difíciles | APIYI apiyi.com |
| claude-sonnet-5-5 | $2 | $10 | $0.1 | Modelo principal para el uso diario | APIYI apiyi.com |
| kimi-k3.1-pro | $2 | $10 | $0.2 | Páginas web en chino | APIYI apiyi.com |
| deepseek-v4.1-flash | $0.3 | $1.2 | $0.006 | Formularios sencillos y revisiones por lotes | APIYI apiyi.com |
Una combinación práctica es usar deepseek-v4.1-flash para tareas por lotes con estructuras sencillas y pasos fijos, claude-sonnet-5-5 como modelo principal de uso general y pasar a claude-opus-5-5 cuando encuentres interacciones complejas o páginas que fallen con frecuencia. Como el texto de las skills y la indicación del sistema se repiten en cada ronda, los modelos con precios de caché más bajos ofrecen una ventaja de costos en ciclos largos.
Cabe señalar que la serie ERNIE de Wenxin aún no aparece en la lista de precios de APIYI: APIYI todavía no ofrece ese modelo, aunque esperamos incorporarlo pronto. Si tu agente depende de ERNIE, puedes hacer pruebas mientras tanto con los modelos de la tabla.
💡 Recomendación: ningún modelo es el mejor para todos los sitios web. Elige de 3 a 5 páginas reales de tu actividad para hacer una prueba con una muestra pequeña. En APIYI apiyi.com puedes cambiar de modelo mediante una interfaz unificada y comparar la tasa de éxito y el costo por tarea antes de elegir el modelo principal.
Recomendaciones para usar agent-browser de forma segura
Cuando un agente opera un navegador real, es fundamental definir de antemano los límites de seguridad. La sección de seguridad de la documentación oficial de agent-browser ofrece mecanismos como la bóveda de autenticación (auth vault), la lista de dominios permitidos, las políticas de actuación y los límites de contenido. En cuanto a los comandos, auth sirve para gestionar las credenciales de inicio de sesión, mientras que confirm y deny permiten confirmar o rechazar acciones sensibles.
En producción, se recomienda tomar al menos estas tres medidas:
- Limitar los dominios accesibles: usa una lista de dominios permitidos para restringir al agente a los sitios relacionados con la actividad y evitar que una página lo induzca a visitar sitios desconocidos.
- Mantener las credenciales fuera del contexto: guarda los datos de acceso en el auth vault en lugar de incluirlos en la indicación, para evitar que aparezcan en los registros del modelo.
- Exigir confirmación humana para acciones sensibles: configura acciones como pagos, eliminaciones y envío de pedidos para que requieran confirmación, de modo que una persona conserve la decisión final.
El contenido de las páginas web también puede incluir instrucciones maliciosas dirigidas al agente, por lo que conviene activar el mecanismo de límites de contenido. Su función es ayudar al modelo a distinguir entre «el texto de la página» y «las instrucciones del usuario», lo que reduce el riesgo de inyección de indicaciones.
Preguntas frecuentes FAQ
P1: ¿Qué es el ciclo snapshot-ref de agent-browser?
Es la forma de trabajo principal de agent-browser: primero usa `snapshot` para leer la página como texto compacto con referencias o ref; después, ejecuta una acción sobre una ref y toma una nueva instantánea para comprobar el resultado. Este ciclo divide la comprensión de la página y la ejecución de acciones en pequeños pasos verificables, lo que facilita el razonamiento paso a paso de un Modelo de Lenguaje Grande.
P2: ¿En qué se diferencia agent-browser de un agente de navegador basado en capturas de pantalla?
Las soluciones basadas en capturas son más versátiles para la comprensión visual, pero consumen muchos tokens y los clics por coordenadas pueden desviarse. En cambio, agent-browser utiliza el texto del árbol de accesibilidad y las ref para localizar elementos. Así, el contexto es más compacto, las operaciones son más precisas y los errores se notifican de forma explícita. Esto lo hace más adecuado para tareas de automatización que requieren una ejecución estable.
P3: ¿Por qué no se pueden seguir usando las ref anteriores después de navegar a otra página?
Las ref solo describen la página en el momento de la instantánea. Después de una navegación o un cambio en el DOM, los elementos pueden haber desaparecido o sido reemplazados, por lo que las ref anteriores pueden dejar de funcionar o apuntar al elemento equivocado. Lo correcto es volver a ejecutar `snapshot` después de cada cambio en la página y usar las nuevas ref.
P4: ¿Para qué casos de uso es adecuado agent-browser?
Es especialmente útil para los siguientes casos:
– **Relleno automático de formularios**: procesos con pasos fijos, como registros, inscripciones o introducción de datos en paneles de administración.
– **Revisión de sitios y pruebas de regresión**: combina `errors`, `console` y `vitals` para comprobar errores y rendimiento de las páginas.
– **Recopilación de información**: después de iniciar sesión en un panel de administración, lee los datos página por página siguiendo los menús.
– **Casos específicos como Electron y Slack**: amplía sus capacidades mediante las habilidades especializadas disponibles en `skills list`.
P5: ¿Cómo se conecta el modelo que controla agent-browser?
Puedes seguir estos pasos:
1. Visita APIYI en apiyi.com, crea una cuenta y obtén una clave API.
2. En el framework del agente, elige un formato compatible con OpenAI o Anthropic y configura los parámetros de conexión según la documentación de docs.apiyi.com.
3. Usa el ciclo de 5 pasos de este artículo como tarea de prueba y compara el rendimiento de los distintos modelos.
APIYI permite acceder de forma unificada a modelos como Claude, DeepSeek y Kimi. Para cambiar de modelo, solo tienes que modificar su nombre.
P6: ¿Cómo se estima el costo del modelo para ejecutar el ciclo snapshot-ref?
Las tareas de navegador consumen principalmente tokens de entrada, ya que cada ronda incluye el texto de la instantánea y la indicación de sistema. Para estimar el costo, fíjate sobre todo en el precio de entrada y el precio de la caché, y usa `snapshot -i` siempre que sea posible para reducir el tamaño de las instantáneas. Consulta los precios reales de cada modelo en la página de precios de APIYI, docs.apiyi.com/models, y evita usar tarifas de terceros que puedan estar desactualizadas.
P7: ¿Qué limitaciones conocidas tiene agent-browser?
La vigencia limitada de las ref obliga al agente a tomar nuevas instantáneas con frecuencia, lo que aumenta el número de rondas. En páginas con información de accesibilidad muy incompleta, las instantáneas pueden no ser suficientes; en esos casos, hay que recurrir a selectores CSS, XPath o capturas de pantalla como apoyo. Además, el navegador sin interfaz gráfica se cierra automáticamente después de una hora de inactividad, por lo que las tareas largas requieren configurar la persistencia de la sesión.
Puntos clave del ciclo snapshot-ref de agent-browser
- Definición: agent-browser es una CLI de Rust de código abierto de Vercel Labs que permite a un Agent controlar el navegador comando a comando.
- Ciclo básico: leer la página con una instantánea, actuar sobre un ref y tomar otra instantánea para verificar el resultado.
- Regla de oro del ref: después de navegar a otra página o modificar el DOM, hay que tomar una nueva instantánea antes de usar un ref.
- Los errores son señales: si un elemento está bloqueado o deshabilitado, el clic fallará. El Agent debe resolver el bloqueo antes de reintentar.
- Integración: usa
skills get corepara cargar las instrucciones compatibles con la versión, oagent-browser mcppara conectar un cliente MCP. - Seguridad ante todo: en producción, activa una lista de dominios permitidos, auth vault y la confirmación de operaciones sensibles.
- Selección de modelos: compara los modelos que controlan el Agent mediante una interfaz unificada en APIYI apiyi.com. Consulta los precios en docs.apiyi.com/models.
Resumen
Los puntos clave del ciclo snapshot-ref de agent-browser son:
- Usar texto en lugar de capturas de pantalla: las instantáneas del árbol de accesibilidad y los ref permiten al modelo entender la página con un contexto mínimo.
- Verificar cada paso: después de cada acción, lee la página o la URL para evitar que el Agent siga trabajando en un estado incorrecto.
- Gestionar los errores: hay formas claras de resolver los bloqueos, los problemas de viewport, los elementos deshabilitados y los ref caducados.
- Integración sencilla: la instalación con npm, los skills integrados y el servicio MCP permiten incorporarlo rápidamente a un Agent existente.
Se recomienda probar primero en la terminal los cinco comandos open, snapshot, click, get y close. Después, añade las reglas del ciclo a la indicación del sistema del Agent y, por último, elige el modelo que lo controlará mediante pruebas con páginas reales.
Puedes usar APIYI apiyi.com para comprobar rápidamente cómo funcionan distintos modelos con agent-browser. La plataforma es compatible con los formatos de interfaz de OpenAI y Anthropic. Encontrarás las instrucciones de integración en docs.apiyi.com y los precios de los modelos en docs.apiyi.com/models.
📚 Referencias
- GitHub – agent-browser: repositorio oficial de código abierto
- Enlace:
github.com/vercel-labs/agent-browser -
Descripción: incluye instrucciones de instalación, inicio rápido, grupos de comandos e información para desarrolladores
-
Documentación oficial de agent-browser: guía completa y referencia de comandos
- Enlace:
agent-browser.dev -
Descripción: cubre instantáneas, selectores, sesiones, modo CDP y mecanismos de seguridad
-
Documentación de seguridad de agent-browser: autenticación y control de acceso
- Enlace:
agent-browser.dev/security -
Descripción: presenta auth vault, listas de dominios permitidos, políticas de acción y límites de contenido
-
Centro de documentación de APIYI: instrucciones para integrar modelos
- Enlace:
docs.apiyi.com -
Descripción: métodos de integración con formatos compatibles con OpenAI y Anthropic
-
Página de precios de modelos de APIYI: tarifas de cada modelo
- Enlace:
docs.apiyi.com/models - Descripción: esta página es la referencia para todos los precios de modelos mencionados en el artículo
Autor: equipo técnico de APIYI
Consultas técnicas: puedes contactarnos desde la página principal de APIYI en apiyi.com. Encontrarás más información sobre la integración en el centro de documentación docs.apiyi.com
