Ferramentas de Navegador

O adk-browser crate fornece 46 ferramentas abrangentes de automação de navegador que permitem aos agentes de IA interagir com páginas da web. Construído sobre o protocolo WebDriver (Selenium), funciona com qualquer navegador compatível com WebDriver.

Visão Geral

As ferramentas de navegador permitem aos agentes:

• Navegar em páginas da web e gerenciar o histórico do navegador
• Extrair texto, links, imagens e dados estruturados
• Preencher formulários e interagir com elementos da página
• Tirar capturas de tela e gerar PDFs
• Executar JavaScript para automação avançada
• Gerenciar cookies, frames e múltiplas janelas

Início Rápido

Adicione ao seu Cargo.toml:

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

Pré-requisitos

Inicie um 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(())
}

Ferramentas Filtradas

Selecione apenas as ferramentas que seu agente precisa:

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-Tenant com Conjuntos de Ferramentas Baseados em Pool

Para implantações multi-tenant em produção, use BrowserToolset::with_pool() juntamente com LlmAgentBuilder::toolset(). Cada usuário obtém uma sessão de navegador isolada resolvida do pool em tempo de execução:

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()?;

As sessões do navegador iniciam automaticamente e se recuperam de conexões WebDriver obsoletas. Você não precisa mais chamar browser.start() antes de usar as ferramentas — a sessão inicia de forma transparente no primeiro uso.

Ferramentas Disponíveis (46 no Total)

Navegação (4 ferramentas)

Extração (5 ferramentas)

Interação (5 tools)

Esperar (4 ferramentas)

Capturas de tela (1 ferramenta)

JavaScript (4 ferramentas)

Cookies (5 tools)

Janelas/Abas (8 ferramentas)

Quadros (3 ferramentas)

Ações (7 ferramentas)

Seletores de Elementos

Ferramentas que visam elementos aceitam CSS seletores:

// 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)"

Exemplo: Agente de Pesquisa 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()?;

Exemplo: Automação de Formulários

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()?;

Configuração

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?;

Opções WebDriver

Funciona com qualquer servidor compatível com WebDriver:

Tratamento de Erros

As ferramentas de navegador retornam erros estruturados:

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),
        }
    }
}

Exemplos

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

Melhores Práticas

1. Usar Esperas: Sempre use ferramentas browser_wait_* antes de interagir com conteúdo dinâmico
2. Minimizar Capturas de Tela: Capturas de tela são caras; use-as estrategicamente
3. Fechar Sessões: Sempre feche as sessões do navegador quando terminar
4. Tratar Erros: A automação do navegador pode falhar; trate os timeouts de forma elegante
5. Filtrar Ferramentas: Dê aos agents apenas as ferramentas de que precisam para reduzir a complexidade

---

Anterior: ← Ferramentas Integradas | Próximo: Ferramentas de UI →