أدوات المتصفح

توفر adk-browser 46 أداة شاملة لأتمتة المتصفح تمكن وكلاء الذكاء الاصطناعي من التفاعل مع صفحات الويب. بنيت على بروتوكول WebDriver (Selenium)، وتعمل مع أي متصفح متوافق مع WebDriver.

نظرة عامة

تسمح أدوات المتصفح للوكلاء بما يلي:

• التنقل في صفحات الويب وإدارة سجل المتصفح
• استخراج النصوص والروابط والصور والبيانات المهيكلة
• ملء النماذج والتفاعل مع عناصر الصفحة
• أخذ لقطات شاشة وإنشاء PDFs
• تنفيذ JavaScript للأتمتة المتقدمة
• إدارة ملفات تعريف الارتباط والإطارات والنوافذ المتعددة

بدء سريع

أضف إلى Cargo.toml الخاص بك:

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

المتطلبات الأساسية

ابدأ خادم 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

الاستخدام الأساسي

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

أدوات مصفاة

حدد فقط الأدوات التي يحتاجها وكيلك:

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

الاستخدام متعدد المستأجرين مع مجموعات الأدوات المدعومة بالمجمعات

لعمليات النشر متعددة المستأجرين في بيئة الإنتاج، استخدم BrowserToolset::with_pool() جنبًا إلى جنب مع LlmAgentBuilder::toolset(). يحصل كل مستخدم على جلسة متصفح معزولة يتم حلها من المجمع في وقت التشغيل:

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

تبدأ جلسات المتصفح تلقائيًا وتستعيد نفسها تلقائيًا من اتصالات WebDriver القديمة. لم تعد بحاجة إلى استدعاء browser.start() قبل استخدام الأدوات — تبدأ الجلسة بشفافية عند الاستخدام الأول.

الأدوات المتاحة (46 إجمالاً)

التنقل (4 أدوات)

استخراج (5 أدوات)

تفاعل (5 أدوات)

انتظار (4 أدوات)

لقطات الشاشة (1 Tool)

JavaScript (4 أدوات)

ملفات تعريف الارتباط (5 أدوات)

النوافذ/علامات التبويب (8 أدوات)

إطارات (3 Tool)

الإجراءات (7 أدوات)

محددات العناصر

تقبل الأدوات التي تستهدف العناصر محددات 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)"

مثال: وكيل بحث الويب

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

مثال: أتمتة النماذج

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

التكوين

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

خيارات WebDriver

يعمل مع أي خادم متوافق مع WebDriver:

معالجة الأخطاء

تُرجع أدوات المتصفح أخطاءً منظمة:

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

أمثلة

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

أفضل الممارسات

1. استخدام الانتظار: استخدم دائمًا أدوات browser_wait_* قبل التفاعل مع المحتوى الديناميكي
2. تقليل لقطات الشاشة: لقطات الشاشة مكلفة؛ استخدمها بشكل استراتيجي
3. إغلاق الجلسات: أغلق دائمًا جلسات المتصفح عند الانتهاء
4. معالجة الأخطاء: قد تفشل أتمتة المتصفح؛ تعامل مع مهلات الوقت بلطف
5. تصفية الأدوات: امنح الوكلاء الأدوات التي يحتاجونها فقط لتقليل التعقيد

---

السابق: ← الأدوات المدمجة | التالي: أدوات واجهة المستخدم →