Skip to content

تعليق وكلاء الويب

راجع تتبعات وكلاء تصفح الويب في Potato مع التنقل بشريط اللقطات، وطبقات SVG (النقرات والمربعات المحيطة ومسارات الفأرة)، وأدوات تعليق لكل خطوة.

جديد في الإصدار v2.4.0

يتطلب تقييم وكلاء الذكاء الاصطناعي التي تتصفح الويب رؤية ما رآه الوكيل بالضبط، وأين نقر، وما إذا كانت كل خطوة منطقية. يوفر Potato عارض تتبعات وكلاء الويب بوضعين: مراجعة تتبعات مسجلة مسبقاً، وإنشاء تتبعات جديدة بتصفح مواقع حية.

نظرة عامة

الوضعمتى تستخدمه
وضع المراجعةلديك تتبعات مسجلة مسبقاً من WebArena أو Mind2Web أو Anthropic Computer Use أو من مسجّل Potato نفسه
وضع الإنشاءتريد من المعلّقين تصفح مواقع الويب وتسجيل تتبعات تفاعل جديدة

وضع المراجعة

يتنقل المعلّقون خطوةً بخطوة بين لقطات شاشة جلسة تصفح الوكيل. وترسم طبقات SVG علامات النقر والمربعات المحيطة ومسارات الفأرة ومؤشرات التمرير فوق كل لقطة.

التهيئة

yaml
instance_display:
  fields:
    - key: steps
      type: web_agent_trace
      label: "Agent Browsing Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_observation: true
        show_element_info: true
        screenshot_max_width: 800
        screenshot_max_height: 600
        filmstrip_size: 80

صيغة البيانات

يحتاج كل عنصر إلى مصفوفة steps تحتوي بيانات كل خطوة:

json
{
  "id": "trace_001",
  "task_description": "Find and add a blue wool sweater to cart",
  "site": "amazon.com",
  "steps": [
    {
      "step_index": 0,
      "screenshot_url": "screenshots/step_000.png",
      "action_type": "click",
      "element": {
        "tag": "input",
        "text": "Search",
        "bbox": [340, 45, 680, 75]
      },
      "coordinates": {"x": 510, "y": 60},
      "mouse_path": [[200, 300], [350, 200], [510, 60]],
      "thought": "I need to search for blue wool sweaters",
      "observation": "Search box is focused",
      "timestamp": 1.2,
      "viewport": {"width": 1280, "height": 720}
    }
  ]
}

أنواع الإجراءات المدعومة

الإجراءالطبقة
clickدائرة حمراء مع تقاطع شعري وحركة نبض
typeإبراز أصفر على العنصر الهدف
scrollسهم أخضر يشير إلى الاتجاه
hoverدائرة بنفسجية
selectمربع محيط أزرق
navigateبلا طبقة
waitبلا طبقة
doneبلا طبقة

اختصارات لوحة المفاتيح

المفتاحالإجراء
/ الخطوة السابقة / التالية
1تبديل طبقات علامات النقر
2تبديل طبقات المربعات المحيطة
3تبديل طبقات مسارات الفأرة
4تبديل مؤشرات التمرير
Aإظهار كل الطبقات
Nإخفاء كل الطبقات

التعليقات لكل خطوة

أضف per_step: true إلى أي مخطط توسيم لإنشاء أدوات تعليق تظهر مضمّنة مع كل خطوة:

yaml
annotation_schemes:
  - annotation_type: radio
    name: step_correctness
    per_step: true
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: step_notes
    per_step: true
    label: "Notes on this step"

تُخزَّن تعليقات كل خطوة بالصيغة {scheme_name}_step_{index} (مثل step_correctness_step_0).

وضع الإنشاء

يتصفح المعلّقون موقعاً حياً داخل واجهة Potato، وتُسجَّل التفاعلات تلقائياً على هيئة تتبع جاهز للتعليق.

التهيئة

yaml
instance_display:
  fields:
    - key: browsing_session
      type: web_agent_recorder
      display_options:
        start_url: "https://www.google.com"
        proxy_mode: auto
        record_mouse_path: true
        record_viewport: true
        screenshot_method: server
        max_steps: 50

أوضاع الوسيط

الوضعالوصف
auto (الافتراضي)يكتشف ما إذا كان الموقع الهدف يسمح بالتضمين داخل iframe ويختار الوضع الأنسب تلقائياً
iframeيفرض وسيط iframe — يعمل مع نحو 90% من المواقع بزمن إضافي أقل من 100 مللي ثانية
playwrightيفرض Playwright من جهة الخادم — يعمل مع 100% من المواقع، ويتطلب حزمة playwright

لتفعيل وضع Playwright:

bash
pip install playwright
playwright install chromium

تحويل التتبعات الموجودة

استخدم أداة تحويل التتبعات في سطر الأوامر لتوحيد تتبعات الأطر الأخرى إلى صيغة Potato:

bash
# Convert from a specific format
python -m potato.trace_converter -i traces.json -f web_agent -o output.jsonl
 
# Auto-detect format
python -m potato.trace_converter -i traces.json --auto-detect -o output.jsonl

صيغ الإدخال المدعومة: WebArena وVisualWebArena وMind2Web وAnthropic Computer Use وتسجيلات Potato الخام.

مثال كامل

yaml
task_name: "Web Agent Evaluation"
task_dir: "."
 
data_files:
  - "traces.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: steps
      type: web_agent_trace
      label: "Agent Trace"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task successfully?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: radio
    name: step_correctness
    question: "Was this step correct?"
    per_step: true
    labels:
      - name: correct
      - name: incorrect
      - name: unnecessary
  - annotation_type: text
    name: error_description
    question: "Describe any errors in the agent's behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

تشغيل المشاريع النموذجية

bash
# Review Mode
python potato/flask_server.py start examples/agent-traces/web-agent-review/config.yaml -p 8000
 
# Creation Mode
python potato/flask_server.py start examples/agent-traces/web-agent-creation/config.yaml -p 8000

مرجع API

تتوفر نقاط نهاية REST التالية عند استخدام وضع الإنشاء:

نقطة النهايةالطريقةالوصف
/api/web_agent/start_sessionPOSTبدء جلسة تسجيل
/api/web_agent/save_stepPOSTحفظ خطوة تفاعل مسجلة
/api/web_agent/save_screenshotPOSTرفع لقطة شاشة لخطوة
/api/web_agent/end_sessionPOSTإنهاء الجلسة وحفظ التتبع
/api/web_agent/proxy/{url}GETتمرير رابط خارجي عبر الخادم
/api/web_agent/check_frameableGETاختبار ما إذا كان الرابط يسمح بالتضمين داخل iframe

قراءة إضافية

للاطلاع على تفاصيل التنفيذ، راجع الوثائق المصدرية.