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

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

نظرة عامة

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

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

البدء السريع

أضف إلى Cargo.toml:

[dependencies]
adk-browser = "2.1.0"
adk-agent = "2.1.0"
adk-model = "2.1.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-3.7-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 أدوات)

لقطات الشاشة (أداة واحدة)

JavaScript (4 أدوات)

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

Windows/Tabs (8 أدوات)

الإطارات (3 أدوات)

الإجراءات (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. رشّح الأدوات: امنح الوكلاء الأدوات التي يحتاجون إليها فقط لتقليل التعقيد

---

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