AgentTriage

AgentTriage es un sistema de trazado y diagnóstico de seguridad entre agentes para agentes LLM que utilizan herramientas. Observa el ingreso de origen, la planificación y los ciclos de vida de las herramientas, los normaliza en un contrato de eventos canónico, reconstruye un Grafo de Procedencia Tipado Simplificado (STPG), extrae una cadena de origen a destino, atribuye la probable brecha de defensa y genera una Tarjeta de Brecha de Defensa.

Este repositorio contiene la implementación actual del runtime de AgentTriage, cinco superposiciones de destino ligeras, instantáneas de código fuente fijadas de los agentes de código abierto correspondientes, una repetición completa de comportamiento de 53 casos y un conjunto de 40 páginas de evidencia de diagnóstico sin etiquetas.

Componentes incluidos

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

Los cinco objetivos son TaskWeaver, Agent Zero, LangGraph, Goose y Microsoft Agent Framework. La información exclusiva de cada objetivo debe permanecer bajo metadata.<target>; todos los eventos de traza de nivel superior usan agenttriage.trace.v0.2 y todos los controladores de objetivo usan la interfaz común v0.2.

Las cinco definiciones de superposición y el envoltorio de tiempo de ejecución de TaskWeaver corresponden a la última implementación seleccionada para este árbol de código fuente público. El código de temporización, anotación y exclusivo del evaluador queda intencionalmente fuera de esta versión. Las revisiones upstream específicas de cada objetivo y los bloqueos de dependencias permanecen disponibles en el version-lock.json y la configuración de contenedor de cada objetivo.

Límite de seguridad

Los agentes objetivo pueden ejecutar código y escribir archivos. Use únicamente contenedores Docker desechables, claves de API solo para pruebas, los fixtures locales proporcionados y endpoints de loopback. No monte directorios sensibles del host ni apunte los ejemplos a sistemas de producción. Consulte SECURITY.md.

Requisitos

• macOS o Linux;
• Python 3.10 o superior;
• Docker Desktop/Engine para ejecuciones de agentes objetivo;
• Git es opcional después de clonar;
• una clave de proveedor solo para objetivos/casos con modelos reales.

El paquete host tiene una única dependencia de tiempo de ejecución, jsonschema. Las dependencias de los objetivos están aisladas en sus imágenes Docker fijadas por digest.

Instalar el controlador 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

Verifique la ruta sin clave:

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

El comando offline escribe:

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

Configurar las credenciales del modelo

Nunca edites una configuración rastreada con una clave real. Crea únicamente los archivos env locales que necesiten los objetivos que pretendas ejecutar:

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

Rellena DEEPSEEK_API_KEY para los modos de modelo real de Agent Zero, LangGraph, Goose y Microsoft Agent Framework. Rellena LLM_API_KEY para TaskWeaver. Los fixtures de prueba deterministas de Goose/LangGraph/MAF se pueden ejecutar sin una clave de modelo, pero el runner sigue requiriendo que exista el archivo de entorno configurado; una plantilla copiada vacía es suficiente para esos fixtures.

Construir una imagen de destino

El runner por lotes construye automáticamente una imagen ausente. Para construir explícitamente:

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 .

Las bases de imágenes y las revisiones upstream están fijadas en cada targets/<target>/version-lock.json. Si dockerproxy.net no está disponible en tu región, reemplaza únicamente el host del registro manteniendo el digest fijado.

Ejecutar un caso de prueba seguro para un target

Cada target tiene un directorio separado de prompt/policy bajo examples/smoke/. La forma del comando es idéntica en los cinco targets:

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

Reemplace langgraph con taskweaver, agentzero, goose o microsoft_agent_framework y use el directorio smoke correspondiente. Utilice siempre un nuevo directorio de salida. Un directorio de caso contiene la salida del driver y la traza semántica, además de los artefactos normalizados propiedad 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

Use --instrumentation-mode off con las mismas entradas para una comprobación de comportamiento sin trazas. Ese modo intencionalmente no produce semantic_trace.jsonl.

Contrato de superposición del objetivo

Cada driver recibe:

• prompt.json;
• policy_oracle.json;
• una ruta de salida de traza semántica;
• modo de instrumentación (semantic u off);
• safe_test_assets.json y una raíz de activos materializados aislada;
• un archivo opcional de política del sistema de alta prioridad.

Cada driver es propietario únicamente de driver_result.json y semantic_trace.jsonl. El runner común valida la traza, crea raw_trace.json y case.json, ejecuta AgentTriage y escribe los artefactos STPG/Card. Los eventos de invocación y de resultado comparten un call_id explícito; la adyacencia cronológica por sí sola no se trata como evidencia causal.