AgentTriage

AgentTriage هو نظام تتبّع وتشخيص أمني عابر للوكلاء (cross-agent) للوكلاء LLM التي تستخدم الأدوات. يراقب مدخلات المصدر ودورات حياة التخطيط والأدوات، ويطبّعها إلى عقد أحداث قانوني واحد، ويعيد بناء رسم بياني مبسّط لنشأة البيانات المطبوعة (Simplified Typed Provenance Graph - STPG)، ويستخرج سلسلة من المصدر إلى المصب (source-to-sink chain)، وينسب فجوة الدفاع المحتملة، ويعرض بطاقة فجوة الدفاع (Defense-Gap Card).

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

المكوّنات المضمّنة

agenttriage/
  canonicalize/        target-neutral event normalization and parent linking
  stpg/                STPG construction, slicing, labeling, and compaction
  chain/               source-to-terminal chain extraction
  attribution/         outcome-aware defense-gap attribution
  render/              JSON/Markdown Defense-Gap Card rendering
  batch/               target launcher, trace validation, and artifact pipeline
targets/               five target-specific runtime overlays
open-source-agents/     pinned source snapshots governed by upstream licenses
schemas/                trace, canonical-event, and target schemas
contracts/              public acquisition/diagnosis contract
examples/               offline diagnosis examples and safe smoke inputs
data/                   sanitized collected cases and label-free evidence pages

الأهداف الخمسة هي TaskWeaver وAgent Zero وLangGraph وGoose وMicrosoft Agent Framework. يجب أن تبقى المعلومات الخاصة بكل هدف ضمن metadata.<target>؛ تستخدم جميع أحداث التتبع العلوية agenttriage.trace.v0.2 وتستخدم جميع مشغّلات الأهداف الواجهة المشتركة v0.2.

تتوافق تعريفات الطبقات الخمس وأداة التغليف الزمني لـ TaskWeaver مع أحدث تنفيذ تم اختياره لشجرة المصدر العامة هذه. الكود الخاص بالتوقيت والتعليقات والكود الخاص بالمُقيّم فقط خارج هذا الإصدار عمدًا. تبقى المراجعات الخاصة بكل هدف والتبعيات المثبّتة متاحة في ملف version-lock.json الخاص بكل هدف وفي إعدادات الحاوية.

حدود الأمان

يمكن لوكلاء الأهداف تنفيذ الكود وكتابة الملفات. استخدم فقط حاويات Docker القابلة للتخلص منها، ومفاتيح API للاختبار فقط، والبيانات المحلية المرفقة، ونقاط النهاية على واجهة الاسترجاع المحلية (loopback). لا تُركّب أدلة مضيف حساسة ولا توجّه الأمثلة إلى أنظمة الإنتاج. راجع SECURITY.md.

المتطلبات

• macOS أو Linux؛
• Python 3.10 أو أحدث؛
• Docker Desktop/Engine لتشغيل وكلاء الأهداف؛
• Git اختياري بعد الاستنساخ؛
• مفتاح مزوّد فقط للأهداف/الحالات التي تستخدم النماذج الحقيقية.

تحتوي حزمة المضيف على تبعية وقت تشغيل واحدة، وهي jsonschema. تبعيات الأهداف معزولة في صور Docker المثبّتة ببصماتها (digest-pinned).

تثبيت وحدة التحكم في المضيف

cd agenttriage-open-source
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
python -m pip install pytest

تحقق من المسار الخالي من المفاتيح:

pytest -q
agenttriage \
  --case examples/sample_case.json \
  --output /tmp/agenttriage-offline-demo \
  --print-markdown

يكتب الأمر دون اتصال:

raw_events.json
canonical_events.json
executed_chain.json
stpg.json
stpg_slice.json
assessment.json
card.json
card.md

إعداد بيانات اعتماد النموذج

لا تقم أبدًا بتعديل إعدادات متتبَّعة بمفتاح حقيقي. أنشئ فقط ملفات env المحلية التي تحتاجها الأهداف التي تنوي تشغيلها:

cp .env.example targets/agentzero/.env.local
cp .env.example targets/langgraph/.env.local
cp .env.example targets/goose/.env.local
cp .env.example targets/microsoft_agent_framework/.env.local
cp .env.example targets/taskweaver/.env.local

املأ DEEPSEEK_API_KEY لأوضاع النماذج الحقيقية في Agent Zero وLangGraph وGoose وMicrosoft Agent Framework. املأ LLM_API_KEY لـ TaskWeaver. عينات Goose/LangGraph/MAF التجريبية للاختبار السريع حتمية ويمكن تشغيلها دون مفتاح نموذج، لكن المشغّل لا يزال يتطلب وجود ملف env المُهيأ؛ يكفي قالب منسوخ فارغ لتلك العينات.

بناء صورة هدف

يبني مشغّل الدفعات الصورة الغائبة تلقائيًا. للبناء صراحةً:

docker build -f targets/taskweaver/Dockerfile -t agenttriage-taskweaver:runtime-overlay-v0.3 .
docker build -f targets/agentzero/Dockerfile -t agenttriage-agentzero:v2.4-overlay-v0.2 .
docker build -f targets/langgraph/Dockerfile -t agenttriage-langgraph:1.2.9-overlay-v0.4 .
docker build -f targets/goose/Dockerfile -t agenttriage-goose:1.43.0-overlay-v0.3 .
docker build -f targets/microsoft_agent_framework/Dockerfile -t agenttriage-microsoft-agent-framework:1.11.0-overlay-v0.3 .

تُثبَّت صور الأساس والمراجعات الأولية في كل ملف targets/<target>/version-lock.json. إذا كان dockerproxy.net غير متاح في منطقتك، فاستبدل مضيف السجل فقط مع الاحتفاظ بالبصمة المثبّتة.

تشغيل حالة اختبار دخاني آمنة واحدة للهدف

لكل هدف دليل خاص بالموجّه/السياسة تحت examples/smoke/. شكل الأمر متطابق عبر الأهداف الخمسة جميعها:

agenttriage-batch \
  --target langgraph \
  --prompts examples/smoke/langgraph/prompts.jsonl \
  --policy-oracles examples/smoke/langgraph/policy_oracles.jsonl \
  --output runs/langgraph-smoke-01 \
  --runtime docker \
  --instrumentation-mode semantic \
  --build \
  --timeout-seconds 300

استبدل langgraph بـ taskweaver أو agentzero أو goose أو microsoft_agent_framework واستخدم دليل smoke المطابق. استخدم دائمًا دليل إخراج جديدًا. يحتوي دليل الحالة على مخرجات المشغّل والتتبع الدلالي إضافةً إلى العناصر المعيارية المملوكة للمشغّل:

driver_result.json
semantic_trace.jsonl
raw_trace.json
trace_validation.json
case.json
driver.stdout.log
driver.stderr.log
artifacts/canonical_events.json
artifacts/executed_chain.json
artifacts/stpg.json
artifacts/stpg_slice.json
artifacts/card.json
artifacts/card.md

استخدم --instrumentation-mode off مع المدخلات نفسها لإجراء فحص سلوكي غير متتبَّع. لا يُنتج هذا الوضع semantic_trace.jsonl عمدًا.

عقد طبقة التراكب الهدفية

يتلقى كل مشغّل (driver) ما يلي:

• prompt.json؛
• policy_oracle.json؛
• مسار إخراج التتبع الدلالي؛
• وضع القياس (semantic أو off)؛
• safe_test_assets.json وجذر أصول مُجسَّد معزول؛
• ملف سياسة نظام اختياري عالي الأولوية.

يملك كل مشغّل فقط driver_result.json وsemantic_trace.jsonl. يتحقق المشغّل المشترك من التتبع، وينشئ raw_trace.json وcase.json، ويشغّل AgentTriage، ويكتب مخرجات STPG/Card. تتشارك أحداث الاستدعاء والنتيجة معرّف call_id صريحًا؛ ولا يُعامَل التجاور الزمني وحده كدليل سببي.

يستخدم TaskWeaver نموذج طبقة التراكب الخفيفة نفسه الذي تستخدمه الأهداف الأربعة الأخرى: لا يتم تعديل المصدر الأصلي المثبَّت. تُثبَّت أغلفة وقت التشغيل عند بدء العملية وتُستعاد عند الخروج. لا يحتوي هذا الإصدار عمدًا على وحدة hook-plan/Instrumentation العامة السابقة الخاصة بـ AgentTriage ولا على شجرة مصدر TaskWeaver معدَّلة؛ إذ تُصدر الأحداث الدلالية فقط عبر طبقات التراكب الخمس المحلية للأهداف.

إضافة وكيل آخر

أنشئ targets/<id>/target.yaml وdriver.py وDockerfile وoverlay.json وversion-lock.json. أعد استخدام المخططات العامة؛ وضع الحقول الخاصة بالهدف فقط في metadata.<id>. التقط دخول المصدر، واستدعاء الأداة/نتيجتها بمعرّف call_id مشترك، والحالة النهائية، وحقول الوسائط، وتتبّع الحقول الصريح. لا تُضف حقول أحداث من المستوى الأعلى خاصة بالهدف.

بيانات الحالات العامة

يحتوي data/behavior-collection على 53 حالة آمنة من تكرار كامل واحد عبر الأهداف الخمسة. تتضمن العينة تتبعات خام/دلالية ومخرجات AgentTriage STPG/Card، لكنها تستبعد ملخصات التحكم الداخلي في التشغيل والكفاءة.