AgentTriage

AgentTriage ist ein agentenübergreifendes Tracing- und Sicherheitsdiagnosesystem für werkzeugnutzende LLM-Agenten. Es beobachtet Quell-Eingänge, Planungs- und Werkzeug-Lebenszyklen, normalisiert sie in einen kanonischen Ereignisvertrag, rekonstruiert einen Simplified Typed Provenance Graph (STPG), extrahiert eine Source-to-Sink-Kette, ordnet die wahrscheinliche Verteidigungslücke zu und erzeugt eine Defense-Gap Card.

Dieses Repository enthält die aktuelle AgentTriage-Laufzeitimplementierung, fünf leichtgewichtige Ziel-Overlays, gepinnte Quell-Snapshots der entsprechenden Open-Source-Agenten, eine vollständige Verhaltenswiederholung mit 53 Fällen und einen Satz von 40 label-freien Diagnose-Evidenzseiten.

Enthaltene Komponenten

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

Die fünf Ziele sind TaskWeaver, Agent Zero, LangGraph, Goose und Microsoft Agent Framework. Ziel-spezifische Informationen müssen unter metadata.<target> bleiben; alle Top-Level-Trace-Events verwenden agenttriage.trace.v0.2 und alle Ziel-Treiber verwenden die gemeinsame v0.2-Schnittstelle.

Die fünf Overlay-Definitionen und der TaskWeaver-Runtime-Wrapper entsprechen der neuesten Implementierung, die für diesen öffentlichen Quellbaum ausgewählt wurde. Timing-, Annotations- und Evaluator-spezifischer Code liegt bewusst außerhalb dieses Releases. Ziel-spezifische Upstream-Revisionen und Dependency-Locks bleiben in der version-lock.json und der Container-Konfiguration jedes Ziels verfügbar.

Sicherheitsgrenze

Die Ziel-Agenten können Code ausführen und Dateien schreiben. Verwenden Sie ausschließlich wegwerfbare Docker- Container, reine Test-API-Schlüssel, die bereitgestellten lokalen Fixtures und Loopback- Endpunkte. Binden Sie keine sensiblen Host-Verzeichnisse ein und richten Sie die Beispiele nicht auf Produktionssysteme aus. Siehe SECURITY.md.

Anforderungen

• macOS oder Linux;
• Python 3.10 oder neuer;
• Docker Desktop/Engine für Ziel-Agenten-Läufe;
• Git ist nach dem Klonen optional;
• ein Provider-Schlüssel nur für Echtmodell-Ziele/-Fälle.

Das Host-Paket hat eine Laufzeitabhängigkeit, jsonschema. Ziel-Abhängigkeiten sind in den digest-gepinnten Docker-Images isoliert.

Installation des Host-Controllers

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

Überprüfen Sie den schlüsselfreien Pfad:

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

Der Offline-Befehl schreibt:

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

Modell-Anmeldedaten konfigurieren

Bearbeite niemals eine versionierte Konfiguration mit einem echten Schlüssel. Erstelle nur die lokalen Env-Dateien, die von den Targets benötigt werden, die du ausführen möchtest:

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

Befülle DEEPSEEK_API_KEY für die Echtmodus-Modi von Agent Zero, LangGraph, Goose und Microsoft Agent Framework. Befülle LLM_API_KEY für TaskWeaver. Die Beispiel-Smoke-Fixtures für Goose/LangGraph/MAF sind deterministisch und können ohne Modellschlüssel ausgeführt werden, aber der Runner verlangt dennoch, dass die konfigurierte Env-Datei existiert; eine leere kopierte Vorlage reicht für diese Fixtures aus.

Ein Ziel-Image erstellen

Der Batch-Runner erstellt ein fehlendes Image automatisch. Um es explizit zu erstellen:

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 .

Image-Basis und Upstream-Revisionen sind in jeder targets/<target>/version-lock.json festgelegt. Wenn dockerproxy.net in Ihrer Region nicht verfügbar ist, ersetzen Sie nur den Registry-Host, während der gepinnte Digest beibehalten wird.

Einen sicheren Smoke-Testfall für ein Ziel ausführen

Jedes Ziel hat ein separates Prompt-/Policy-Verzeichnis unter examples/smoke/. Die Befehlsform ist bei allen fünf Zielen identisch:

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

Ersetze langgraph durch taskweaver, agentzero, goose oder microsoft_agent_framework und verwende das passende Smoke-Verzeichnis. Verwende immer ein neues Ausgabeverzeichnis. Ein Fallverzeichnis enthält die Treiberausgabe und den semantischen Trace sowie vom Runner verwaltete normalisierte Artefakte:

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

Verwenden Sie --instrumentation-mode off mit denselben Eingaben für eine nicht nachverfolgte Verhaltensprüfung. Dieser Modus erzeugt absichtlich keine semantic_trace.jsonl.

Ziel-Overlay-Vertrag

Jeder Treiber erhält:

• prompt.json;
• policy_oracle.json;
• einen Ausgabepfad für den semantischen Trace;
• Instrumentierungsmodus (semantic oder off);
• safe_test_assets.json und ein isoliertes materialisiertes Asset-Root;
• eine optionale System-Policy-Datei mit hoher Priorität.

Jeder Treiber besitzt ausschließlich driver_result.json und semantic_trace.jsonl. Der gemeinsame Runner validiert den Trace, erstellt raw_trace.json und case.json, führt AgentTriage aus und schreibt STPG/Card-Artefakte. Aufruf- und Ergebnisereignisse teilen sich eine explizite call_id; chronologische Nachbarschaft allein wird nicht als kausaler Nachweis behandelt.

TaskWeaver verwendet dasselbe leichtgewichtige Runtime-Overlay-Modell wie die anderen vier Ziele: Die gepinnte Upstream-Quelle wird nicht gepatcht. Runtime-Wrapper werden beim Prozessstart installiert und beim Beenden wiederhergestellt. Diese Version enthält bewusst weder das frühere generische Hook-Plan/Instrumentation-Modul von AgentTriage noch einen gepatchten TaskWeaver-Quellbaum; semantische Ereignisse werden ausschließlich von den fünf ziel-lokalen Runtime-Overlays ausgegeben.

Einen weiteren Agenten hinzufügen