AgentTriage

AgentTriage est un système de traçage inter-agents et de diagnostic de sécurité pour les agents LLM utilisant des outils. Il observe l'ingress source, la planification et les cycles de vie des outils, les normalise en un contrat d'événement canonique unique, reconstruit un graphe de provenance typé simplifié (STPG, Simplified Typed Provenance Graph), extrait une chaîne source-à-puits, attribue la lacune de défense probable et génère une Defense-Gap Card.

Ce dépôt contient l'implémentation actuelle du runtime d'AgentTriage, cinq overlays cibles légers, des instantanés figés des sources des agents open-source correspondants, une répétition complète de comportement sur 53 cas, et un ensemble de 40 pages de preuves de diagnostic sans étiquettes.

Composants inclus

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

Les cinq cibles sont TaskWeaver, Agent Zero, LangGraph, Goose et Microsoft Agent Framework. Les informations propres aux cibles doivent rester sous metadata.<target> ; tous les événements de trace de niveau supérieur utilisent agenttriage.trace.v0.2 et tous les pilotes de cible utilisent l'interface commune v0.2.

Les cinq définitions d'overlay et le wrapper d'exécution TaskWeaver correspondent à la dernière implémentation sélectionnée pour cette arborescence source publique. Le chronométrage, l'annotation et le code réservé à l'évaluateur sont volontairement exclus de cette version. Les révisions amont propres aux cibles et les verrouillages de dépendances restent disponibles dans le version-lock.json et la configuration de conteneur de chaque cible.

Périmètre de sécurité

Les agents cibles peuvent exécuter du code et écrire des fichiers. Utilisez uniquement des conteneurs Docker jetables, des clés API réservées aux tests, les fixtures locales fournies et des points de terminaison en boucle locale. Ne montez pas de répertoires hôtes sensibles et ne pointez pas les exemples vers des systèmes de production. Voir SECURITY.md.

Prérequis

• macOS ou Linux ;
• Python 3.10 ou plus récent ;
• Docker Desktop/Engine pour les exécutions d'agents cibles ;
• Git est facultatif après le clonage ;
• une clé de fournisseur uniquement pour les cibles/cas à modèle réel.

Le paquet hôte a une seule dépendance d'exécution, jsonschema. Les dépendances des cibles sont isolées dans leurs images Docker épinglées par digest.

Installer le contrôleur hôte

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

Vérifiez le chemin sans clé :

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

La commande hors ligne écrit :

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

Configurer les identifiants du modèle

Ne modifiez jamais une configuration suivie avec une vraie clé. Créez uniquement les fichiers d'environnement locaux nécessaires aux cibles que vous avez l'intention d'exécuter :

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

Renseignez DEEPSEEK_API_KEY pour les modes à modèle réel d'Agent Zero, LangGraph, Goose et Microsoft Agent Framework. Renseignez LLM_API_KEY pour TaskWeaver. Les fixtures de test Goose/LangGraph/MAF fournies sont déterministes et peuvent être exécutées sans clé de modèle, mais le runner exige toujours que le fichier d'environnement configuré existe ; un modèle copié vide suffit pour ces fixtures.

Construire une image cible

Le runner par lots construit automatiquement une image absente. Pour construire explicitement :

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 .

Les images de base et les révisions amont sont fixées dans chaque targets/<target>/version-lock.json. Si dockerproxy.net n'est pas disponible dans votre région, remplacez uniquement l'hôte du registre tout en conservant le digest épinglé.

Exécuter un cas de test de fumée sécurisé pour une cible

Chaque cible dispose d'un répertoire prompt/policy distinct sous examples/smoke/. La forme de la commande est identique pour les cinq cibles :

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

Remplacez langgraph par taskweaver, agentzero, goose ou microsoft_agent_framework et utilisez le répertoire smoke correspondant. Utilisez toujours un nouveau répertoire de sortie. Un répertoire de cas contient la sortie du pilote et la trace sémantique, ainsi que les artefacts normalisés gérés par le runner :

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

Utilisez --instrumentation-mode off avec les mêmes entrées pour une vérification de comportement non tracé. Ce mode ne produit intentionnellement pas de semantic_trace.jsonl.

Contrat de superposition cible

Chaque driver reçoit :

• prompt.json ;
• policy_oracle.json ;
• un chemin de sortie de trace sémantique ;
• le mode d'instrumentation (semantic ou off) ;
• safe_test_assets.json et une racine d'actifs matérialisés isolée ;
• un fichier de politique système à haute priorité facultatif.

Chaque driver ne possède que driver_result.json et semantic_trace.jsonl. Le runner commun valide la trace, crée raw_trace.json et case.json, exécute AgentTriage et écrit les artefacts STPG/Card. Les événements d'invocation et de résultat partagent un call_id explicite ; la seule adjacence chronologique n'est pas traitée comme une preuve causale.