Hub documentation

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

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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

Agent trace preview on a dataset page in light mode.

تُدعَّم مسارات الوكلاء (Agent traces) من Claude Code وCodex وPi وHermes Agent وFactory Droid بشكل أصلي على Hugging Face Hub. ارفع جلسات JSONL الخام إلى Dataset أو Storage Bucket لفتحها في عارض مسارات مخصص. تعرض مجموعات البيانات المسارات في Data Studio؛ بينما تتيح لك الدلاء فتح ملفات .jsonl الفردية مباشرة.

يمكن أيضًا تصدير الطلبات المُوجَّهة عبر OpenRouter مباشرةً إلى دلو (bucket) وفتحها في نفس العارض، راجع OpenRouter Broadcast traces.

This is a heading, so it should be translated as a noun phrase. "Traces" in the context of performance profiling or debugging refers to "تتبعات" or "سجلات التتبع". "سجلات التتبع" is more natural and precise in this technical context. "Find" is an imperative verb, so the translation should be an imperative noun phrase or a direct command. "ابحث عن" is a direct command. "سجلات التتبع الخاصة بك" means "your traces". ابحث عن سجلات التتبع الخاصة بك

تكتب معظم الوكلاء المدعومين جلسات JSONL إلى مجلدات محلية:

وكيلمجلد الجلسة المحلي
Claude Code~/.claude/projects
Codex~/.codex/sessions
أرشيف Codex~/.codex/archived_sessions
Factory/Droid~/.factory/sessions
Pi~/.pi/agent/sessions

تُؤيَّد ملفات التتبع هذه بشكل افتراضي، لذا يمكنك رفعها دون الحاجة إلى تعديلها أو تحويلها أولاً.

يخزّن Hermes Agent الجلسات الحالية في قاعدة بيانات الجلسات الخاصة به. صدّر الجلسات التي تريد مشاركتها بصيغة JSONL قبل رفعها:

hermes sessions export session.jsonl --session-id <session_id>

هل تقوم ببناء إطار عمل خاص بك؟ إذا لم يكن وكيلك مدرجًا أعلاه، يمكنك جعل جلساته تُعرض في عارض التتبع من خلال إصدار Session Traces Format.

قد تتضمن ملفات التتبع (Trace files) أوامر استدعاء (prompts) ومدخلات الأدوات ومخرجات الأوامر والمسارات المحلية ولقطات الشاشة والبيانات السرية والكود الخاص والبيانات الشخصية. راجع ملفات التتبع واحذف أي معلومات حساسة منها قبل نشرها علنًا، أو أبقِ مجموعة البيانات أو الدلو (bucket) خاصًا إذا لم تكن متأكدًا مما تحتويه.

في جلسات Pi Agent، يمكن لـ pi-share-hf المساعدة في جمع جلسات المشروع، وإخفاء الأسرار المعروفة، وتشغيل TruffleHog ومراجعة LLM، ورفع الجلسات التي تجتاز الفحوصات فقط.

أسهل طريقة للرفع هي أن تطلب من وكيلك نفسه: وجّهه إلى المجلد أو ملف JSONL المُصدَّر أعلاه وأخبره برفع ملفات .jsonl إلى مجموعة بيانات أو حاوية على Hub.

تُعدّ الدلاء مفيدة بشكل خاص إذا كنت ترغب في مواصلة مزامنة المسارات مع وصول جلسات جديدة.

ارفع مساراتك

بعد إنشاء مجموعة بيانات أو حاوية، ثبّت hf CLI باستخدام المثبّت المستقل الموصى به وسجّل الدخول. يقوم المثبّت أيضًا بإعداد Hugging Face CLI Skill، مما يتيح لوكيل البرمجة لديك تنفيذ أوامر hf نيابةً عنك.

curl -LsSf https://hf.co/cli/install.sh | bash
hf auth login

hf upload <username>/<dataset-name> ~/.codex/sessions . --repo-type dataset
hf buckets sync ~/.codex/sessions hf://buckets/<username>/<bucket-name>/codex

استبدل ~/.codex/sessions بمجلد الجلسة المطابق لوكيلك، أو بمجلد يحتوي على ملفات JSONL مُصدَّرة من Hermes Agent. استخدم hf upload للمجموعات البيانات وhf buckets sync للمحاويط التي تريد تحديثها مع كتابة مسارات جديدة. الأمر الأقصر hf sync هو مرادف لـhf buckets sync.

عرض مساراتك

بمجرد أن تصبح لديك مسارات (traces) في مجموعة بيانات، افتح Data Studio وانقر على صف. أما بالنسبة للمسارات الموجودة في Storage Bucket، فتوجّه إلى ملف .jsonl الذي تريد فحصه وافتحه. يعرض عارض المسارات خط زمني للجلسة، والموجّهات (prompts)، ورسائل المساعد، واستدعاءات الأدوات، ومخرجات shell، ومكاتب الاستدلال، والنتائج.

Agent trace session viewer showing user and assistant turns with expanded tool calls.

كمثال عام، افتح TeichAI/DeepSeek-v4-Pro-Agent. يمكنك أيضًا تصفح المزيد من مجموعات البيانات الموسومة بـ traces.

OpenRouter Broadcast تتبّع

يمكن لـ OpenRouter Broadcast إرسال سجلات الطلبات التي تُوجَّه عبر OpenRouter إلى Storage Bucket، ويفتح Hub تلك الملفات في عارض التتبع. لا يتغير شيء في تطبيقك أو وكيلك، لذا يعمل مع أي شيء يمر عبر OpenRouter: Claude Code أو Codex الموجَّه إلى OpenRouter، أو OpenCode، أو تطبيق chat-completions عادي.

لإعداد ذلك، أنشئ دلوًا، ثم أنشئ بيانات اعتماد S3 من رمز له صلاحية الكتابة فيه، وأضف Hugging Face Storage Buckets كوجهة تحت Settings > Observability في OpenRouter. يحتوي دليل Hugging Face Storage Buckets الخاص بـ OpenRouter على الخطوات الكاملة.

أنشئ الدلو كخاص:

hf buckets create <username>/openrouter-traces --private

تحتوي الملفات على أوامر كاملة، وأوامر نظام، ومخرجات أدوات مثل مسارات الملفات ومخرجات سطر الأوامر، إلى جانب معرفات حساب OpenRouter ومعرّفات المستخدمين واسم مفتاح API. ولا يتناول دليل OpenRouter مسألة ظهور الدلاء (buckets)، ويمكن لأي شخص قراءة الدلو العام.

يُحفظ كل مسار (trace) كملف JSON منفصل باسم {traceId}-{timestamp}.json. ومع قالب المسار الافتراضي openrouter-traces/{date}، تُحفظ الملفات في مجلد لكل يوم:

openrouter-traces/<date>/gen-<unix>-<id>-<timestamp>.json

التتبع (Trace) هو طلب نموذج واحد، وليس جلسة كاملة. عادةً ما يُصدر دور واحد للوكيل عدة طلبات للنموذج، لذا يمكن أن تنتج جلسة من ثلاثة أدوار حوالي عشرة ملفات. يحتوي كل ملف على المحادثة حتى ذلك الطلب، مما يعني أن الملف الأخير في الجلسة يحتوي على الجلسة بأكملها. تتشارك الملفات من نفس الجلسة نفس trace.sessionId.

افتح أيًا من ملفات .json هذه في الدلو لعرضها كـ تتبع OpenRouter، مع إمكانية التبديل بين عرض التتبع وJSON الخام. يعرض العارض الرسائل، واستدعاءات الأدوات ونتائجها، والنموذج، وعدد الرموز (بما في ذلك الرموز المخزنة مؤقتًا)، والتكلفة. التكلفة في التذييل تخص تلك الطلبية الواحدة، وليس الجلسة بأكملها.

شيئان يجب معرفتهما عند قراءة هذه التتبعات:

  • لا يتم تخزين الصور. يقوم OpenRouter بإزالة المحتوى متعدد الوسائط من الرسائل قبل التصدير، ويعرض العارض [image] مكانها.
  • قد تكون بعض الطلبات مفقودة أو خالية من المحتوى. تُقيّد نسبة العينة وفلاتر مفتاح واجهة برمجة التطبيقات الخاصة بـ OpenRouter الطلبات التي تُرسل إلى وجهة معينة، بينما يزيل وضع الخصوصية محتوى الاستدعاء (prompt) والإكمال (completion).
Update on GitHub