AgentTriage

AgentTriage é um sistema de rastreamento e diagnóstico de segurança entre agentes para agentes LLM que utilizam ferramentas. Ele observa a entrada de origem, o planejamento e os ciclos de vida das ferramentas, normaliza-os em um contrato de eventos canônico, reconstrói um Grafo de Proveniência Tipado Simplificado (STPG), extrai uma cadeia da origem ao destino, atribui a provável lacuna de defesa e gera um Cartão de Lacuna de Defesa.

Este repositório contém a implementação atual do runtime do AgentTriage, cinco sobreposições de destino leves, snapshots fixados do código-fonte dos agentes de código aberto correspondentes, uma repetição completa de comportamento com 53 casos e um conjunto de 40 páginas de evidências de diagnóstico sem rótulos.

Componentes incluídos

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

Os cinco alvos são TaskWeaver, Agent Zero, LangGraph, Goose e Microsoft Agent Framework. Informações específicas de cada alvo devem permanecer em metadata.<target>; todos os eventos de trace de nível superior usam agenttriage.trace.v0.2 e todos os drivers de alvo usam a interface comum v0.2.

As cinco definições de overlay e o wrapper de runtime do TaskWeaver correspondem à implementação mais recente selecionada para esta árvore de código-fonte pública. Código de temporização, anotação e exclusivo do avaliador está intencionalmente fora desta versão. Revisões upstream específicas de cada alvo e bloqueios de dependências permanecem disponíveis no version-lock.json e na configuração de container de cada alvo.

Limite de segurança

Os agentes alvo podem executar código e escrever arquivos. Use apenas containers Docker descartáveis, chaves de API exclusivas para testes, os fixtures locais fornecidos e endpoints de loopback. Não monte diretórios sensíveis do host nem aponte os exemplos para sistemas de produção. Consulte SECURITY.md.

Requisitos

• macOS ou Linux;
• Python 3.10 ou mais recente;
• Docker Desktop/Engine para execuções de agentes alvo;
• Git é opcional após a clonagem;
• uma chave de provedor apenas para alvos/casos com modelos reais.

O pacote host tem uma dependência de runtime, jsonschema. As dependências dos alvos são isoladas em suas imagens Docker fixadas por digest.

Instalar o 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 o caminho sem chave:

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

O comando offline grava:

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

Configurar credenciais de modelo

Nunca edite uma configuração rastreada com uma chave real. Crie apenas os arquivos env locais necessários para os alvos que você pretende executar:

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

Preencha DEEPSEEK_API_KEY para os modos de modelo real do Agent Zero, LangGraph, Goose e Microsoft Agent Framework. Preencha LLM_API_KEY para o TaskWeaver. Os fixtures de smoke de exemplo do Goose/LangGraph/MAF são determinísticos e podem ser executados sem uma chave de modelo, mas o runner ainda exige que o arquivo de ambiente configurado exista; um template copiado vazio é suficiente para esses fixtures.

Construir uma imagem de destino

O runner em lote constrói automaticamente uma imagem ausente. Para construir explicitamente:

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 .

As bases de imagens e as revisões upstream são fixadas em cada targets/<target>/version-lock.json. Se o dockerproxy.net não estiver disponível na sua região, substitua apenas o host do registry, mantendo o digest fixado.

Executar um caso de smoke seguro de um target

Cada target tem um diretório separado de prompt/policy em examples/smoke/. O formato do comando é idêntico nos 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

Substitua langgraph por taskweaver, agentzero, goose ou microsoft_agent_framework e use o diretório de smoke correspondente. Sempre use um novo diretório de saída. Um diretório de caso contém a saída do driver e o rastreamento semântico, além de artefatos normalizados de propriedade do 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 com as mesmas entradas para uma verificação de comportamento não rastreado. Esse modo intencionalmente não produz semantic_trace.jsonl.

Contrato de sobreposição de destino

Cada driver recebe:

• prompt.json;
• policy_oracle.json;
• um caminho de saída de rastreamento semântico;
• modo de instrumentação (semantic ou off);
• safe_test_assets.json e uma raiz de ativos materializados isolada;
• um arquivo opcional de política de sistema de alta prioridade.

Cada driver é responsável apenas por driver_result.json e semantic_trace.jsonl. O runner comum valida o rastreamento, cria raw_trace.json e case.json, executa o AgentTriage e grava artefatos STPG/Card. Eventos de invocação e resultado compartilham um call_id explícito; a adjacência cronológica por si só não é tratada como evidência causal.

O TaskWeaver usa o mesmo modelo leve de sobreposição de runtime que os outros quatro destinos: o código-fonte upstream fixado não é modificado. Wrappers de runtime são instalados na inicialização do processo e restaurados na saída. Esta versão deliberadamente não contém o antigo módulo genérico de hook-plan/Instrumentation do AgentTriage nem uma árvore de código-fonte do TaskWeaver modificada; eventos semânticos são emitidos apenas pelas cinco sobreposições de runtime locais ao destino.

Adicionar outro agente