التقييم المباشر للوكلاء

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

يتيح التقييم المباشر للوكلاء أن يشاهد المعلّقون وكيل ذكاء اصطناعي يتصفح الويب في الوقت الفعلي وأن يعلّقوا على سلوكه أثناء تشغيله لا بعد انتهائه. يلتقط الوكيل لقطات شاشة، ويرسلها إلى نموذج لغوي بصري، ويتلقى إجراءات، وينفذها في متصفح بلا واجهة. وتُبَث كل خطوة مباشرةً إلى شاشة المعلّق.

المتطلبات

pip install playwright anthropic
playwright install chromium
export ANTHROPIC_API_KEY=your_key_here

التهيئة

live_agent:
  endpoint_type: anthropic_vision
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
  system_prompt: |
    You are a web browsing agent. Complete the given task efficiently.
    At each step, describe your thought, then output an action.
  max_steps: 30
  step_delay: 1.0
  viewport:
    width: 1280
    height: 720
  allow_takeover: true
  allow_instructions: true
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: agent_trace
      type: live_agent
      label: "Live Agent Session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_controls: true

مرجع التهيئة

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

يوفر كل عنصر المهمة ورابط البداية:

{
  "id": "task_001",
  "task_description": "Search for climate change on Wikipedia and find the year it was first described",
  "start_url": "https://en.wikipedia.org"
}

سير عمل المعلّق

1. يقرأ المعلّق وصف المهمة وينقر على Start Agent
2. يُشغَّل متصفح Chromium بلا واجهة ويتصل بالنموذج اللغوي
3. تُبَث لقطات الشاشة مباشرةً إلى العارض أثناء تنقل الوكيل، وتعرض كل خطوة اللقطة وفكرة الوكيل والإجراء المتخذ
4. يستطيع المعلّق التفاعل عبر لوحة التحكم:
   • Pause / Resume -- إيقاف الوكيل بين الخطوات
   • Send Instructions -- حقن رسالة في سياق الوكيل أثناء التشغيل
   • Take Over -- التحول إلى التصفح اليدوي
   • Stop -- إنهاء الجلسة مبكراً
5. حين تنتهي الجلسة (نجاحاً أو فشلاً أو ببلوغ max_steps)، يُحفظ التتبع ويتحول العرض إلى وضع المراجعة
6. يملأ المعلّق مخططات التعليق لتقييم أداء الوكيل

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

إضافة مخططات التعليق

اجمع بين عرض الوكيل المباشر وأي مخططات تعليق في Potato:

annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task?"
    labels:
      - name: "Yes, fully"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    question: "How efficiently did the agent work?"
    min_label: "Very inefficient"
    max_label: "Very efficient"
    scale: 5
  - annotation_type: text
    name: errors_observed
    question: "Describe any errors or unnecessary steps"
  - annotation_type: span
    name: error_steps
    question: "Mark any steps where the agent made an error"
    labels:
      - name: hallucination
      - name: wrong_target
      - name: unnecessary_action

مثال كامل

task_name: "Live Agent Evaluation Study"
task_dir: "."
 
live_agent:
  endpoint_type: anthropic_vision
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 4096
    temperature: 0.3
  max_steps: 25
  step_delay: 1.5
  viewport:
    width: 1280
    height: 720
  allow_takeover: true
  allow_instructions: true
  history_window: 5
 
data_files:
  - "tasks.jsonl"
 
instance_display:
  fields:
    - key: task_description
      type: text
      label: "Task"
    - key: agent_trace
      type: live_agent
      label: "Live Session"
      display_options:
        show_overlays: true
        show_filmstrip: true
        show_thought: true
        show_controls: true
 
annotation_schemes:
  - annotation_type: radio
    name: task_success
    question: "Did the agent complete the task?"
    labels:
      - name: "Yes"
      - name: "Partially"
      - name: "No"
  - annotation_type: likert
    name: efficiency
    question: "Rate the agent's efficiency"
    scale: 5
    min_label: "Very inefficient"
    max_label: "Very efficient"
  - annotation_type: text
    name: notes
    question: "Notes on agent behavior"
 
output_annotation_dir: "output/"
output_annotation_format: "jsonl"

البنية

يعمل الوكيل المباشر بوصفه خيط تنفيذ خلفياً في Flask. وتُبَث لقطات الشاشة وتغيّرات الحالة إلى المتصفح عبر Server-Sent Events (SSE). أما أدوات تحكم المعلّق (الإيقاف والتوجيه وتولّي الزمام والإنهاء) فتنادي نقاط نهاية REST تتزامن مع الخيط الخلفي.

Annotator (browser)  <── SSE stream ──  Flask Server  ── Playwright ──► Headless Browser
                     ──► REST control ─►              ◄── LLM API ────► Claude Vision

وتُحفظ لقطات الشاشة في {task_dir}/live_sessions/ وتُقدَّم عبر الـ API لعرض شريط الصور.

تصدير التتبعات

حين تكتمل الجلسة، يصدّر Potato تلقائياً التتبع الكامل بصيغة JSON متوافقة مع web_agent_trace، وتشمل:

• كل الخطوات مع لقطات الشاشة والإجراءات والأفكار والملاحظات
• أي تعليمات أرسلها المعلّق أثناء التشغيل
• الطوابع الزمنية وبيانات تهيئة الوكيل الوصفية
• أحداث تولّي المعلّق للزمام

وهذا يعني أن الجلسات المباشرة المكتملة يمكن مراجعتها لاحقاً بالعارض القياسي في تعليق وكلاء الويب.

حل المشكلات

«Playwright is not installed» -- شغّل pip install playwright && playwright install chromium.

«Anthropic API key required» -- اضبط متغير البيئة ANTHROPIC_API_KEY أو استخدم api_key: ${ANTHROPIC_API_KEY} في تهيئتك.

الوكيل يبدو بطيئاً -- تتطلب كل خطوة نداء API لنموذج لغوي (عادةً من 3 إلى 10 ثوانٍ). ويظهر مؤشر التفكير أثناء معالجة النموذج. قلّل history_window لتسريع الجلسات الطويلة.

لقطات الشاشة لا تُحمَّل -- تحقق من أن task_dir قابل للكتابة وأن للخادم مساحة قرص متاحة.

واجهات وكلاء البرمجة الخلفية

إلى جانب وكلاء تصفح الويب، يدعم Potato المراقبة المباشرة لوكلاء البرمجة. وتتوفر ثلاث واجهات خلفية:

Ollama (محلي، بلا مفتاح API)

شغّل تقييم وكلاء البرمجة بنماذج محلية بالكامل، من دون حاجة إلى مفتاح API.

live_agent:
  endpoint_type: coding_agent
  backend: ollama
  ai_config:
    model: qwen2.5-coder:7b
    host: "http://localhost:11434"
  max_steps: 50
  project_dir: "./workspace"

Anthropic API

استخدم Claude مع استخدام الأدوات لتقييم وكلاء البرمجة.

live_agent:
  endpoint_type: coding_agent
  backend: anthropic
  ai_config:
    model: claude-sonnet-4-20250514
    api_key: ${ANTHROPIC_API_KEY}
    max_tokens: 8192
  max_steps: 50
  project_dir: "./workspace"

Claude Agent SDK

قدرات Claude Code الكاملة لجلسات وكلاء البرمجة المتقدمة.

live_agent:
  endpoint_type: coding_agent
  backend: claude_agent_sdk
  ai_config:
    max_turns: 50
  project_dir: "./workspace"

انظر وكيل البرمجة المباشر للمرجع الكامل، بما فيه التراجع والتفريع وتصدير المسارات.

التراجع ونقاط التحقق

في جلسات وكلاء البرمجة، ينشئ Potato commit في git بعد كل تغيير في الملفات. وهذا يتيح:

• التراجع بنقرة واحدة إلى أي نقطة تحقق سابقة
• التفريع وإعادة التشغيل -- جرّب مقاربة مختلفة من أي نقطة تحقق
• سجلاً كاملاً لكل حالة ملف بغرض المراجعة

وتُدار نقاط التحقق تلقائياً عبر فرع git مخصص لكل جلسة.

المسارات المتفرعة

حين يتراجع المعلّق ويجرب مقاربة مختلفة، ينشئ Potato مساراً متفرعاً. ويُحفظ الفرعان كلاهما في المخرجات، فينتج بيانات تدريب من أجل:

• نماذج مكافأة العملية -- وسوم صحة لكل خطوة عبر الفروع
• تعلّم التفضيل -- أي الفرعين أنتج نتائج أفضل
• مجموعات بيانات مراجعة الكود -- قارن جودة الكود عبر المقاربات

قراءات إضافية

• وكيل البرمجة المباشر -- مراقبة وكلاء البرمجة مع Ollama وAnthropic وClaude SDK
• تعليق وكلاء الويب -- مراجعة تتبعات الوكلاء المسجلة مسبقاً
• التعليق على الوكلاء -- نظرة عامة على صيغ تتبعات الوكلاء ومحوّلاتها
• تعليق مكافأة العملية -- جمع بيانات تدريب PRM
• دعم الذكاء الاصطناعي -- تكامل النماذج اللغوية للمساعدة في التعليق

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