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

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

نظرة عامة

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

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

بدء سريع

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

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

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

ابدأ تشغيل خادم WebDriver:

# استخدام Docker (موصى به)
docker run -d -p 4444:4444 -p 7900:7900 --shm-size=2g selenium/standalone-chrome:latest

# أو استخدم ChromeDriver مباشرةً
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>> {
    // تهيئة جلسة المتصفح
    let config = BrowserConfig::new()
        .webdriver_url("http://localhost:4444")
        .headless(true)
        .viewport(1920, 1080);

    // إنشاء وبدء جلسة المتصفح
    let browser = Arc::new(BrowserSession::new(config));
    browser.start().await?;

    // إنشاء مجموعة الأدوات (toolset) مع جميع الأدوات الـ 46
    let toolset = BrowserToolset::new(browser.clone());
    let tools = toolset.all_tools();

    // إنشاء وكيل AI باستخدام أدوات المتصفح
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-2.0-flash")?);

    let mut builder = LlmAgentBuilder::new("web_agent")
        .model(model)
        .instruction("أنت مساعد لأتمتة الويب. استخدم أدوات المتصفح لمساعدة المستخدمين.");

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

    let agent = builder.build()?;

    // التنظيف عند الانتهاء
    browser.stop().await?;

    Ok(())
}

أدوات مفلترة

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

let toolset = BrowserToolset::new(browser)
    .with_navigation(true)   // التنقل، العودة، التقدم، التحديث
    .with_extraction(true)   // استخراج_النص، استخراج_السمة، استخراج_الروابط، معلومات_الصفحة، مصدر_الصفحة
    .with_interaction(true)  // النقر، النقر_المزدوج، الكتابة، المسح، التحديد
    .with_wait(true)         // انتظار_العنصر، انتظار، انتظار_تحميل_الصفحة، انتظار_النص
    .with_screenshot(true)   // لقطة_الشاشة
    .with_js(true)           // تقييم_js، التمرير، التحويم، التعامل_مع_التنبيه
    .with_cookies(false)     // تعطيل أدوات ملفات تعريف الارتباط
    .with_frames(false)      // تعطيل أدوات الإطارات
    .with_windows(false)     // تعطيل أدوات النوافذ
    .with_actions(false);    // تعطيل الإجراءات المتقدمة

let tools = toolset.all_tools();

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

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

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

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

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

لقطات الشاشة (1 أداة)

JavaScript (4 أدوات)

الكوكيز (5 أدوات)

النوافذ/علامات التبويب (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 run --example browser_basic

# وكيل ذكاء اصطناعي مزود بأدوات المتصفح
cargo run --example browser_agent

# مثال تفاعلي كامل بـ 46 أداة
cargo run --example browser_interactive

# وكيل متصفح مدعوم بـ OpenAI
cargo run --example browser_openai --features openai

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

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

---

السابق: ← Built-in Tools | التالي: UI Tools →