AgentTriage

AgentTriage è un sistema di tracciamento e diagnosi di sicurezza cross-agent per agenti LLM che utilizzano strumenti. Osserva l'ingresso delle sorgenti, la pianificazione e i cicli di vita degli strumenti, li normalizza in un unico contratto di eventi canonico, ricostruisce un Simplified Typed Provenance Graph (STPG), estrae una catena source-to-sink, attribuisce la probabile lacuna difensiva e genera una Defense-Gap Card.

Questo repository contiene l'implementazione runtime corrente di AgentTriage, cinque overlay target leggeri, snapshot delle sorgenti fissati dei corrispondenti agenti open-source, una ripetizione completa del comportamento su 53 casi e un set di 40 pagine di evidenza diagnostica senza etichette.

Componenti inclusi

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

I cinque target sono TaskWeaver, Agent Zero, LangGraph, Goose e Microsoft Agent Framework. Le informazioni specifiche dei target devono rimanere sotto metadata.<target>; tutti gli eventi di trace di primo livello usano agenttriage.trace.v0.2 e tutti i driver dei target usano l'interfaccia comune v0.2.

Le cinque definizioni di overlay e il wrapper runtime di TaskWeaver corrispondono all'ultima implementazione selezionata per questo albero sorgente pubblico. Il codice di timing, annotazione e solo per il valutatore è intenzionalmente escluso da questa release. Le revisioni upstream specifiche dei target e i lock delle dipendenze restano disponibili nel version-lock.json di ciascun target e nella configurazione del container.

Confine di sicurezza

Gli agenti target possono eseguire codice e scrivere file. Usare solo container Docker usa e getta, chiavi API solo per test, i fixture locali forniti e endpoint di loopback. Non montare directory host sensibili né puntare gli esempi a sistemi di produzione. Vedere SECURITY.md.

Requisiti

• macOS o Linux;
• Python 3.10 o superiore;
• Docker Desktop/Engine per l'esecuzione degli agenti target;
• Git è opzionale dopo la clonazione;
• una chiave del provider solo per target/casi con modelli reali.

Il pacchetto host ha una sola dipendenza runtime, jsonschema. Le dipendenze dei target sono isolate nelle loro immagini Docker con digest bloccato.

Installare il controller host

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

Verifica il percorso senza chiave:

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

Il comando offline scrive:

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

Configurare le credenziali del modello

Non modificare mai una configurazione tracciata con una chiave reale. Crea solo i file env locali necessari per i target che intendi eseguire:

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

Popolare DEEPSEEK_API_KEY per le modalità con modello reale di Agent Zero, LangGraph, Goose e Microsoft Agent Framework. Popolare LLM_API_KEY per TaskWeaver. I fixture di smoke test di esempio Goose/LangGraph/MAF sono deterministici e possono essere eseguiti senza una chiave del modello, ma il runner richiede comunque che il file env configurato esista; un template copiato vuoto è sufficiente per quei fixture.

Costruire un'immagine target

Il batch runner costruisce automaticamente un'immagine assente. Per costruirla esplicitamente:

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 .

Le basi delle immagini e le revisioni upstream sono fissate in ciascun targets/<target>/version-lock.json. Se dockerproxy.net non è disponibile nella tua regione, sostituisci solo l'host del registry mantenendo il digest fissato.

Esegui un caso di smoke test sicuro per un target

Ogni target ha una directory separata per prompt/policy sotto examples/smoke/. La forma del comando è identica per tutti e cinque i target:

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

Sostituisci langgraph con taskweaver, agentzero, goose o microsoft_agent_framework e usa la directory smoke corrispondente. Usa sempre una nuova directory di output. Una directory di caso contiene l'output del driver e la traccia semantica più gli artefatti normalizzati di proprietà del 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

Usa --instrumentation-mode off con gli stessi input per un controllo del comportamento non tracciato. Tale modalità intenzionalmente non produce semantic_trace.jsonl.

Contratto dell'overlay di destinazione

Ogni driver riceve:

• prompt.json;
• policy_oracle.json;
• un percorso di output della traccia semantica;
• la modalità di strumentazione (semantic o off);
• safe_test_assets.json e una radice di asset materializzata isolata;
• un file opzionale di policy di sistema ad alta priorità.

Ogni driver possiede solo driver_result.json e semantic_trace.jsonl. Il runner comune valida la traccia, crea raw_trace.json e case.json, esegue AgentTriage e scrive gli artefatti STPG/Card. Gli eventi di invocazione e di risultato condividono un call_id esplicito; la sola adiacenza cronologica non è considerata una prova causale.

TaskWeaver utilizza lo stesso modello leggero di runtime-overlay degli altri quattro target: il sorgente upstream bloccato non viene modificato. I wrapper di runtime vengono installati all'avvio del processo e ripristinati all'uscita. Questa release deliberatamente non contiene il precedente modulo generico hook-plan/Instrumentation di AgentTriage né un albero sorgente TaskWeaver modificato; gli eventi semantici sono emessi solo dai cinque overlay di runtime locali ai target.

Aggiungere un altro agente