تعليق وكلاء الويب
راجع تتبعات وكلاء تصفح الويب في Potato مع التنقل بشريط اللقطات، وطبقات SVG (النقرات والمربعات المحيطة ومسارات الفأرة)، وأدوات تعليق لكل خطوة.
جديد في الإصدار v2.4.0
يتطلب تقييم وكلاء الذكاء الاصطناعي التي تتصفح الويب رؤية ما رآه الوكيل بالضبط، وأين نقر، وما إذا كانت كل خطوة منطقية. يوفر Potato عارض تتبعات وكلاء الويب بوضعين: مراجعة تتبعات مسجلة مسبقاً، وإنشاء تتبعات جديدة بتصفح مواقع حية.
نظرة عامة
| الوضع | متى تستخدمه |
|---|---|
| وضع المراجعة | لديك تتبعات مسجلة مسبقاً من WebArena أو Mind2Web أو Anthropic Computer Use أو من مسجّل Potato نفسه |
| وضع الإنشاء | تريد من المعلّقين تصفح مواقع الويب وتسجيل تتبعات تفاعل جديدة |
وضع المراجعة
يتنقل المعلّقون خطوةً بخطوة بين لقطات شاشة جلسة تصفح الوكيل. وترسم طبقات SVG علامات النقر والمربعات المحيطة ومسارات الفأرة ومؤشرات التمرير فوق كل لقطة.
التهيئة
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 تحتوي بيانات كل خطوة:
{
"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 إلى أي مخطط توسيم لإنشاء أدوات تعليق تظهر مضمّنة مع كل خطوة:
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، وتُسجَّل التفاعلات تلقائياً على هيئة تتبع جاهز للتعليق.
التهيئة
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:
pip install playwright
playwright install chromiumتحويل التتبعات الموجودة
استخدم أداة تحويل التتبعات في سطر الأوامر لتوحيد تتبعات الأطر الأخرى إلى صيغة Potato:
# 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 الخام.
مثال كامل
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"تشغيل المشاريع النموذجية
# 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_session | POST | بدء جلسة تسجيل |
/api/web_agent/save_step | POST | حفظ خطوة تفاعل مسجلة |
/api/web_agent/save_screenshot | POST | رفع لقطة شاشة لخطوة |
/api/web_agent/end_session | POST | إنهاء الجلسة وحفظ التتبع |
/api/web_agent/proxy/{url} | GET | تمرير رابط خارجي عبر الخادم |
/api/web_agent/check_frameable | GET | اختبار ما إذا كان الرابط يسمح بالتضمين داخل iframe |
قراءة إضافية
- التقييم المباشر للوكلاء — تقييم الوكلاء أثناء عملها في الوقت الفعلي
- التعليق التوضيحي للوكلاء — محوّلات صيغ التتبع ونظرة عامة على أنواع العرض
- التعلم النشط — إعطاء الأولوية للتتبعات الأكثر إفادة للتعليق
للاطلاع على تفاصيل التنفيذ، راجع الوثائق المصدرية.