AgentTriage

AgentTriage एक क्रॉस-एजेंट ट्रेसिंग और सुरक्षा-निदान प्रणाली है जो टूल-उपयोग करने वाले LLM एजेंट्स के लिए है। यह स्रोत इनग्रेस, प्लानिंग और टूल जीवनचक्रों का अवलोकन करता है, उन्हें एक कैनोनिकल इवेंट कॉन्ट्रैक्ट में सामान्यीकृत करता है, एक सरलीकृत टाइप्ड प्रोवेनेंस ग्राफ (STPG) का पुनर्निर्माण करता है, एक स्रोत-से-सिंक श्रृंखला निकालता है, संभावित डिफेंस गैप का श्रेय देता है, और एक डिफेंस-गैप कार्ड प्रस्तुत करता है।

इस रिपॉजिटरी में वर्तमान 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 कुंजियाँ, प्रदान किए गए स्थानीय फ़िक्स्चर, और लूपबैक एंडपॉइंट का उपयोग करें। संवेदनशील होस्ट निर्देशिकाएँ माउंट न करें या उदाहरणों को प्रोडक्शन सिस्टम की ओर इंगित न करें। देखें SECURITY.md।

आवश्यकताएँ

• macOS या Linux;
• Python 3.10 या नया;
• लक्ष्य-एजेंट रन के लिए Docker Desktop/Engine;
• क्लोन करने के बाद Git वैकल्पिक है;
• प्रदाता कुंजी केवल वास्तविक-मॉडल लक्ष्यों/केसों के लिए।

होस्ट पैकेज की एक रनटाइम निर्भरता है, jsonschema। लक्ष्य निर्भरताएँ उनके डाइजेस्ट-पिन किए गए Docker इमेज में पृथक हैं।

होस्ट कंट्रोलर इंस्टॉल करें

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

The offline command writes:

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

Agent Zero, LangGraph, Goose, और Microsoft Agent Framework के रियल-मॉडल मोड्स के लिए DEEPSEEK_API_KEY भरें। TaskWeaver के लिए LLM_API_KEY भरें। नमूना 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 उत्पन्न नहीं करता है।

लक्ष्य ओवरले अनुबंध

प्रत्येक ड्राइवर प्राप्त करता है:

• 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 अन्य चार लक्ष्यों के समान हल्के रनटाइम-ओवरले मॉडल का उपयोग करता है: पिन किए गए अपस्ट्रीम स्रोत को पैच नहीं किया जाता है। रनटाइम रैपर प्रोसेस स्टार्टअप पर इंस्टॉल होते हैं और एग्ज़िट पर पुनर्स्थापित होते हैं। यह रिलीज़ जानबूझकर AgentTriage के पूर्व सामान्य हुक-प्लान/Instrumentation मॉड्यूल या पैच किए गए TaskWeaver स्रोत ट्री को शामिल नहीं करती है; सेमांटिक इवेंट केवल पाँच लक्ष्य-स्थानीय रनटाइम ओवरले द्वारा उत्सर्जित होते हैं।

एक और एजेंट जोड़ें

targets/<id>/target.yaml, driver.py, Dockerfile, overlay.json, और version-lock.json बनाएँ। सार्वजनिक स्कीमाओं का पुनः उपयोग करें; लक्ष्य-विशिष्ट फ़ील्ड केवल metadata.<id> में रखें। स्रोत इनग्रेस, साझा call_id के साथ टूल इनवोकेशन/परिणाम, टर्मिनल स्थिति, आर्ग्युमेंट फ़ील्ड, और स्पष्ट फ़ील्ड वंशावली कैप्चर करें। लक्ष्य-विशिष्ट शीर्ष-स्तरीय इवेंट फ़ील्ड न जोड़ें।

सार्वजनिक केस डेटा