Herramientas de Navegador

El adk-browser crate proporciona 46 herramientas completas de automatización de navegador que permiten a los agentes de IA interactuar con páginas web. Construido sobre el protocolo WebDriver (Selenium), funciona con cualquier navegador compatible con WebDriver.

Descripción General

Las herramientas de navegador permiten a los agentes:

• Navegar por páginas web y gestionar el historial del navegador
• Extraer texto, enlaces, imágenes y datos estructurados
• Rellenar formularios e interactuar con elementos de la página
• Tomar capturas de pantalla y generar PDFs
• Ejecutar JavaScript para automatización avanzada
• Gestionar cookies, marcos y múltiples ventanas

Inicio Rápido

Añade a tu Cargo.toml:

[dependencies]
adk-browser = "2.0.0"
adk-agent = "2.0.0"
adk-model = "2.0.0"

Requisitos Previos

Inicia un servidor WebDriver:

# Using Docker (recommended)
docker run -d -p 4444:4444 -p 7900:7900 --shm-size=2g selenium/standalone-chrome:latest

# Or use ChromeDriver directly
chromedriver --port=4444

Uso Básico

use adk_browser::{BrowserSession, BrowserToolset, BrowserConfig};
use adk_agent::LlmAgentBuilder;
use adk_model::GeminiModel;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Configure browser session
    let config = BrowserConfig::new()
        .webdriver_url("http://localhost:4444")
        .headless(true)
        .viewport(1920, 1080);

    // Create and start browser session
    let browser = Arc::new(BrowserSession::new(config));
    browser.start().await?;

    // Create toolset with all 46 tools
    let toolset = BrowserToolset::new(browser.clone());
    let tools = toolset.all_tools();

    // Create AI agent with browser tools
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-2.5-flash")?);

    let mut builder = LlmAgentBuilder::new("web_agent")
        .model(model)
        .instruction("You are a web automation assistant. Use browser tools to help users.");

    for tool in tools {
        builder = builder.tool(tool);
    }

    let agent = builder.build()?;

    // Clean up when done
    browser.stop().await?;

    Ok(())
}

Herramientas Filtradas

Selecciona solo las herramientas que tu agente necesita:

let toolset = BrowserToolset::new(browser)
    .with_navigation(true)   // navigate, back, forward, refresh
    .with_extraction(true)   // extract_text, extract_attribute, extract_links, page_info, page_source
    .with_interaction(true)  // click, double_click, type, clear, select
    .with_wait(true)         // wait_for_element, wait, wait_for_page_load, wait_for_text
    .with_screenshot(true)   // screenshot
    .with_js(true)           // evaluate_js, scroll, hover, handle_alert
    .with_cookies(false)     // Disable cookie tools
    .with_frames(false)      // Disable frame tools
    .with_windows(false)     // Disable window tools
    .with_actions(false);    // Disable advanced actions

let tools = toolset.all_tools();

Uso Multi-inquilino con Conjuntos de Herramientas Respaldados por Pool

Para despliegues multiusuario en producción, utilice BrowserToolset::with_pool() junto con LlmAgentBuilder::toolset(). Cada usuario obtiene una sesión de navegador aislada resuelta del pool en tiempo de ejecución:

use adk_browser::{BrowserSessionPool, BrowserToolset, BrowserConfig, BrowserProfile};
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let pool = Arc::new(BrowserSessionPool::new(BrowserConfig::new(), 10));

// Pool-backed toolset — sessions resolved per-user via ctx.user_id()
let toolset = Arc::new(BrowserToolset::with_pool_and_profile(
    pool,
    BrowserProfile::Scraping,
));

let agent = LlmAgentBuilder::new("web_agent")
    .model(model)
    .instruction("You are a web research assistant.")
    .toolset(toolset)
    .build()?;

Las sesiones de navegador se inician automáticamente y se recuperan de conexiones WebDriver obsoletas. Ya no es necesario llamar a browser.start() antes de usar herramientas — la sesión se inicia de forma transparente en el primer uso.

Herramientas Disponibles (46 en Total)

Navegación (4 herramientas)

Extracción (5 herramientas)

Interacción (5 herramientas)

Espera (4 herramientas)

Capturas de pantalla (1 herramienta)

JavaScript (4 herramientas)

Cookies (5 herramientas)

Ventanas/Pestañas (8 herramientas)

Marcos (3 herramientas)

Acciones (7 herramientas)

Selectores de Elementos

Las herramientas que apuntan a elementos aceptan selectores CSS:

// By ID
"#login-button"

// By class
".submit-btn"

// By tag and attribute
"input[type='email']"

// By data attribute
"[data-testid='search']"

// Complex selectors
"form.login input[name='password']"

// Nth child
"ul.menu li:nth-child(3)"

Ejemplo: Agente de Investigación Web

use adk_browser::{BrowserSession, BrowserToolset, BrowserConfig};
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let config = BrowserConfig::new().webdriver_url("http://localhost:4444");
let browser = Arc::new(BrowserSession::new(config));
browser.start().await?;

let toolset = BrowserToolset::new(browser.clone())
    .with_navigation(true)
    .with_extraction(true)
    .with_screenshot(true);

let mut builder = LlmAgentBuilder::new("researcher")
    .model(model)
    .instruction(r#"
        You are a web research assistant. When asked about a topic:
        1. Navigate to relevant websites using browser_navigate
        2. Extract key information using browser_extract_text
        3. Take screenshots of important content using browser_screenshot
        4. Summarize your findings
    "#);

for tool in toolset.all_tools() {
    builder = builder.tool(tool);
}

let agent = builder.build()?;

Ejemplo: Automatización de Formularios

let agent = LlmAgentBuilder::new("form_filler")
    .model(model)
    .instruction(r#"
        You are a form automation assistant. To fill forms:
        1. Use browser_navigate to go to the form page
        2. Use browser_extract_text to see form labels
        3. Use browser_type to fill text fields
        4. Use browser_select for dropdowns
        5. Use browser_click to submit
    "#)
    .build()?;

Configuración

let config = BrowserConfig::new()
    .webdriver_url("http://localhost:4444")
    .headless(true)
    .viewport(1920, 1080)
    .page_load_timeout(30)
    .user_agent("Custom User Agent");

let browser = Arc::new(BrowserSession::new(config));
browser.start().await?;

Opciones de WebDriver

Funciona con cualquier servidor compatible con WebDriver:

Manejo de Errores

Las herramientas del navegador devuelven errores estructurados:

match result {
    Ok(value) => println!("Success: {:?}", value),
    Err(e) => {
        match e {
            BrowserError::ElementNotFound(selector) => {
                println!("Could not find element: {}", selector);
            }
            BrowserError::Timeout(duration) => {
                println!("Operation timed out after {:?}", duration);
            }
            BrowserError::SessionClosed => {
                println!("Browser session was closed");
            }
            _ => println!("Browser error: {}", e),
        }
    }
}

Ejemplos

cargo check -p adk-browser
cargo check -p adk-rust --no-default-features --features browser

Mejores Prácticas

1. Usar Esperas: Siempre usa las herramientas browser_wait_* antes de interactuar con contenido dinámico
2. Minimizar Capturas de Pantalla: Las capturas de pantalla son costosas; úsalas estratégicamente
3. Cerrar Sesiones: Siempre cierra las sesiones del navegador cuando termines
4. Manejar Errores: La automatización del navegador puede fallar; maneja los tiempos de espera con gracia
5. Filtrar Herramientas: Solo dale a los agentes las herramientas que necesitan para reducir la complejidad

---

Anterior: ← Herramientas integradas | Siguiente: Herramientas de UI →