agent-browser

Descripción general

¿Qué es agent-browser?

agent-browser es una skill de automatización de navegador diseñada para agentes de IA que se ejecutan sobre la plataforma inference.sh. Utiliza Playwright internamente y expone una interfaz sencilla basada en JSON para que los agentes puedan:

• Abrir y navegar páginas web en un navegador real
• Interactuar con elementos usando referencias estables @e
• Hacer clic, escribir, arrastrar y soltar, y subir archivos
• Extraer datos estructurados para scraping e investigación
• Capturar capturas de pantalla y grabar vídeo de las sesiones

En lugar de escribir código de Playwright a mano, llamas a agent-browser mediante la CLI infsh (o desde un agente que pueda ejecutar comandos Bash). La skill coordina la sesión de navegador, devuelve descripciones de la página legibles por máquina y permite que tu agente dirija la interacción paso a paso.

¿Para quién es agent-browser?

agent-browser está orientado a:

• Desarrolladores que conectan agentes de IA con sitios web reales
• Ingenieros de automatización que necesitan flujos de navegador reproducibles
• Equipos de datos e investigación que hacen scraping dirigido o investigación basada en la interfaz
• Creadores de flujos que usan inference.sh como capa de orquestación

Encaja mejor cuando ya usas, o estás dispuesto a usar, inference.sh y quieres que el navegador sea una herramienta controlada y accesible para agentes.

¿Qué problemas resuelve?

agent-browser te ayuda a abordar tareas habituales de automatización de navegador:

• Automatizar flujos de login, navegación y formularios
• Hacer scraping de contenido estructurado que requiere interacción (formularios de búsqueda, filtros, paginación)
• Ejecutar flujos "tipo testing" dirigidos por agentes en sitios en producción
• Grabar vídeos de una sesión de navegación automatizada para revisión

Abstrae la escritura directa de scripts de Playwright y ofrece al agente un conjunto de acciones de nivel superior usando referencias de elementos @e, lo que ayuda a mantener las interacciones estables a lo largo de múltiples pasos.

¿Cuándo es una buena elección usar agent-browser?

Usa agent-browser cuando:

• Ejecutas agentes mediante inference.sh y necesitas que naveguen la web
• Quieres la fiabilidad de Playwright sin tener que escribir código de Playwright
• Tus flujos se basan en abrir páginas, interactuar con elementos y leer resultados

Puede no ser la mejor opción cuando:

• No puedes usar la CLI infsh ni herramientas tipo Bash
• Necesitas funcionalidades de Playwright muy personalizadas más allá de lo que expone la skill
• Tu caso de uso es puramente vía API y no requiere un navegador real

Si necesitas un control muy fino de los internos del navegador o de frameworks más allá de lo que expone la skill, quizá prefieras usar scripts directos de Playwright. Para la mayoría de automatizaciones dirigidas por agentes, agent-browser ofrece una interfaz más simple y de mayor nivel.

Cómo usarla

Requisitos previos

Antes de usar agent-browser, asegúrate de tener:

• Un entorno donde puedas ejecutar comandos Bash
• La CLI de inference.sh (infsh) instalada
• Una cuenta de inference.sh en la que puedas iniciar sesión desde la CLI

El inicio rápido de la skill requiere explícitamente la CLI infsh. Puedes seguir las instrucciones oficiales de instalación de la CLI en el repositorio:

• Documentación de instalación de la CLI: https://raw.githubusercontent.com/inference-sh/skills/refs/heads/main/cli-install.md

Una vez que infsh esté instalada y configurada, puedes invocar la skill agent-browser desde tu terminal o desde cualquier herramienta de agente que pueda ejecutar comandos infsh.

Instalación y activación de la skill

agent-browser se distribuye como parte del repositorio inferen-sh/skills. En la mayoría de entornos basados en inference.sh no necesitas instalar un paquete npm independiente; en su lugar, solo debes asegurarte de que la skill esté disponible y llamarla a través de infsh.

Pasos de configuración típicos:

1. Instalar la CLI de inference.sh
   • Sigue cli-install.md en el repositorio.
2. Autenticarte
   • Ejecuta:

     infsh login
     

   • Sigue las indicaciones para autenticarte con inference.sh.
3. Confirmar la disponibilidad de la skill
   • Asegúrate de que tu entorno de inference.sh tenga acceso a la app/skill agent-browser bajo tools/utilities/agent-browser en el repositorio inferen-sh/skills.

Si estás integrando con un ecosistema de “skills” más amplio que admita npx skills add, también puedes conectar este repositorio como origen, pero el flujo canónico para usar agent-browser es a través de infsh app run.

Flujo principal de automatización de navegador

La documentación de la skill describe un patrón consistente de 4 pasos:

1. Open – Iniciar una sesión de navegador y navegar a una URL.
2. Interact – Usar las referencias de elementos @e devueltas para hacer clic, escribir, arrastrar o subir archivos.
3. Re-snapshot – Solicitar una nueva captura para obtener nuevos refs @e tras una navegación o cambios en el DOM.
4. Close – Cerrar la sesión y, opcionalmente, recuperar una grabación de vídeo si está habilitada.

Este patrón permite que tu agente mantenga un modelo mental del estado de la página. Cada llamada envía una entrada en JSON y recibe una salida JSON estructurada, que alimentas en el bucle de razonamiento de tu agente.

Ejemplo de inicio rápido

Para ver agent-browser en acción con una apertura sencilla de una sola página, sigue el patrón de Quick Start del repositorio:

infsh login

# Open a page and get interactive elements
infsh app run agent-browser --function open --input '{"url": "https://example.com"}' --session new

Qué hace este comando:

• --function open indica a agent-browser que lance una nueva página de navegador en la URL indicada.
• --session new crea una sesión nueva para que las acciones posteriores puedan reutilizar el mismo estado de navegador.
• La skill devuelve JSON que normalmente incluye descripciones de elementos y referencias @e que tu agente puede usar en llamadas posteriores a interact.

Trabajar con referencias de elementos @e

Una característica central de agent-browser es el uso de refs @e. En lugar de exigir selectores CSS o XPath, la skill devuelve identificadores como @e:button-1 (el formato exacto depende de la implementación) junto con descripciones legibles para humanos.

Tu agente entonces:

1. Lee la lista de elementos disponibles y sus descripciones.
2. Elige la referencia @e adecuada (por ejemplo, el botón etiquetado como “Search”).
3. Llama a una función de interacción (como click o fill) usando esa referencia @e.

Este diseño está optimizado para agentes de IA, porque pueden razonar sobre descripciones en lugar de detalles de bajo nivel del DOM. También ayuda a mantener las interacciones robustas incluso si cambian los selectores subyacentes, siempre que las descripciones sigan siendo interpretables.

Ejemplo: open, click y re-snapshot

Un flujo típico de varios pasos podría ser así (solo patrón; ajusta a tus funciones específicas):

# 1. Start a session and open a page
OPEN_RESULT=$(infsh app run agent-browser \
  --function open \
  --session new \
  --input '{"url": "https://example.com"}')

# 2. Use OPEN_RESULT to pick an @e ref (e.g. @e:search-button) in your agent logic
# 3. Interact with that element
INTERACT_RESULT=$(infsh app run agent-browser \
  --function interact \
  --session "$INF_SH_SESSION" \
  --input '{"action": "click", "element": "@e:search-button"}')

# 4. Re-snapshot after the click to get updated elements
SNAPSHOT_RESULT=$(infsh app run agent-browser \
  --function snapshot \
  --session "$INF_SH_SESSION" \
  --input '{}')

Los nombres de las funciones más allá de open pueden variar, así que revisa siempre el SKILL.md más reciente y cualquier documentación asociada en tools/utilities/agent-browser para conocer las firmas exactas de las funciones y el esquema de entrada.

Capturas de pantalla y grabación de vídeo

agent-browser puede capturar artefactos visuales de la sesión de navegación:

• Capturas de pantalla: útiles para depurar el comportamiento del agente o almacenar confirmaciones visuales.
• Vídeo: cuando cierras la sesión con la grabación activada, la skill puede devolver o enlazar a un archivo de vídeo con todo el flujo automatizado.

Estas funciones se configuran mediante las opciones de entrada de la skill. Para más detalles sobre cómo habilitar la grabación y acceder a las salidas, consulta la definición SKILL.md y cualquier documentación adicional en tools/utilities/agent-browser dentro del repositorio.

Consejos de integración para agentes y flujos de trabajo

Para sacar el máximo partido de agent-browser en tus flujos de automatización o investigación:

• Persiste los IDs de --session: asegúrate de que tu agente almacene el identificador de sesión entre llamadas, para que múltiples acciones se ejecuten en el mismo navegador.
• Analiza cuidadosamente el JSON de salida: usa un parseo robusto de JSON en el runtime de tu agente; las listas de elementos y metadatos pueden ser ricas.
• Ajusta el ritmo de las interacciones si es necesario: si una página es lenta o muy dinámica, asegúrate de que tu agente tenga en cuenta los tiempos y espere a que aparezcan los elementos entre pasos cuando la configuración de la skill lo permita.
• Registra acciones clave: mantén un log de las llamadas open, interact y close si necesitas auditar o depurar el comportamiento de navegación de tu agente.

Preguntas frecuentes (FAQ)

¿Cuál es la relación entre agent-browser, inference.sh y Playwright?

agent-browser es una skill que se ejecuta dentro del ecosistema de inference.sh. Cuando la invocas mediante infsh app run, usa Playwright como motor subyacente de automatización de navegador. No llamas a Playwright directamente; trabajas con las funciones de nivel superior de la skill y con las referencias de elementos @e.

¿Cómo instalo agent-browser?

No instalas agent-browser como binario independiente ni como paquete npm. En su lugar:

1. Instala la CLI de inference.sh (infsh) usando las instrucciones oficiales de cli-install.md.
2. Inicia sesión con infsh login.
3. Asegúrate de que tu entorno tenga acceso a la skill agent-browser desde el repositorio inferen-sh/skills (en tools/utilities/agent-browser).

A partir de ahí, puedes invocar la skill directamente mediante infsh app run agent-browser.

¿Necesito experiencia en programación para usar agent-browser?

Se recomienda encarecidamente tener conocimientos básicos de línea de comandos y JSON. No necesitas escribir scripts de Playwright, pero sí deberías sentirte cómodo:

• Ejecutando comandos infsh
• Pasando JSON como --input
• Analizando la salida JSON en tu agente o scripts

Para flujos más avanzados (lógica condicional, bucles, manejo de errores), es útil contar con conocimientos generales de scripting o programación.

¿Puedo usar agent-browser fuera de inference.sh?

La skill está creada específicamente para usarse con inference.sh y se describe como “Browser automation for AI agents via inference.sh.” La forma soportada y documentada de ejecutarla es mediante la CLI infsh. Si necesitas una librería independiente, quizá prefieras usar Playwright directamente en el lenguaje de tu elección.

¿Es agent-browser adecuada para scraping web a gran escala?

agent-browser se puede usar para scraping dirigido, especialmente cuando las páginas requieren interacción o renderizado JavaScript. Sin embargo, para scraping de muy alto volumen a gran escala deberías tener en cuenta:

• Los límites de cuenta y precios de inference.sh
• El respeto a los términos de servicio del sitio objetivo y a su robots.txt
• El rendimiento, la concurrencia y la limitación de tasa (rate limiting)

Para scraping a menor escala o específico de un flujo embebido en un agente, agent-browser es una muy buena opción. Para rastreo masivo a través de muchos sitios, puede ser más apropiada una infraestructura de scraping dedicada.

¿Cómo funciona la gestión de sesiones?

La gestión de sesiones se controla mediante la opción --session al llamar a infsh app run. Un patrón típico es:

• Usar --session new cuando llamas a open por primera vez
• Reutilizar ese ID de sesión en las llamadas posteriores a interact y snapshot
• Llamar a la función de cierre apropiada para terminar la sesión y, opcionalmente, recuperar el vídeo

Consulta siempre el SKILL.md actual para ver las opciones y salidas exactas relacionadas con la gestión de sesiones.

¿Dónde puedo encontrar la especificación completa de funciones y entradas?

La referencia autorizada de agent-browser se encuentra en el repositorio:

• SKILL.md en la raíz del repositorio inferen-sh/skills
• El directorio tools/utilities/agent-browser para detalles de implementación, ejemplos y cualquier documentación adicional

Abre estos archivos para ver la lista actual de funciones, los JSON de entrada esperados y los formatos de salida, y luego diseña tu agente o scripts en torno a esas definiciones.