AgentTriage

AgentTriage 是一个面向使用工具的 LLM 智能体的跨智能体追踪与安全诊断系统。它观测源入口、规划与工具生命周期，将其归一化为统一的事件契约，重建简化类型化溯源图（STPG），提取从源到汇的链路，归因可能的防御缺口，并渲染防御缺口卡片。

本仓库包含当前的 AgentTriage 运行时实现、五个轻量级目标覆盖层、对应开源智能体的固定源快照、一次完整的 53 用例行为重复，以及一组 40 个无标签诊断证据页面。

包含的组件

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

五个目标分别是 TaskWeaver、Agent Zero、LangGraph、Goose 和 Microsoft Agent Framework。仅属于目标的信息必须保留在 metadata.<target> 下；所有顶层 trace 事件均使用 agenttriage.trace.v0.2，所有目标驱动均使用通用的 v0.2 接口。

五个 overlay 定义和 TaskWeaver 运行时封装对应于为此公共源码树选定的最新实现。计时、标注和仅用于评估器的代码被有意排除在此版本之外。目标特定的上游修订版本和依赖锁定仍保留在各目标的 version-lock.json 和容器配置中。

安全边界

目标 agent 可以执行代码并写入文件。请仅使用一次性 Docker 容器、仅用于测试的 API 密钥、提供的本地 fixtures 和回环端点。不要挂载敏感的主机目录，也不要将示例指向生产系统。参见 SECURITY.md。

要求

• macOS 或 Linux；
• Python 3.10 或更高版本；
• 用于运行目标 agent 的 Docker Desktop/Engine；
• 克隆后 Git 为可选；
• 仅真实模型目标/用例需要提供商密钥。

宿主包有一个运行时依赖：jsonschema。目标依赖被隔离在按摘要固定的 Docker 镜像中。

安装宿主控制器

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

验证无密钥路径：

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

离线命令会写入：

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

配置模型凭据

切勿使用真实密钥编辑受跟踪的配置文件。仅创建你打算运行的目标所需的本地环境文件：

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

为 Agent Zero、LangGraph、Goose 和 Microsoft Agent Framework 的真实模型模式填充 DEEPSEEK_API_KEY。为 TaskWeaver 填充 LLM_API_KEY。示例 Goose/LangGraph/MAF 冒烟测试夹具是确定性的，无需模型密钥即可运行，但运行器仍要求所配置的环境文件存在；对于这些夹具，复制一份空模板即可满足要求。

构建目标镜像

批处理运行器会自动构建缺失的镜像。如需显式构建：

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 .

镜像基础与上游修订版本固定在每个 targets/<target>/version-lock.json 中。如果 dockerproxy.net 在你所在地区不可用， 只需替换 registry 主机，同时保留固定的 digest。

运行一个安全的 target 冒烟测试用例

每个 target 在 examples/smoke/ 下都有独立的 prompt/policy 目录。 所有五个 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

将 langgraph 替换为 taskweaver、agentzero、goose 或 microsoft_agent_framework，并使用对应的 smoke 目录。始终使用 新的输出目录。用例目录包含驱动输出和语义 追踪，以及运行器拥有的规范化产物：

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

使用 --instrumentation-mode off 并传入相同输入，以进行无追踪的行为检查。该模式有意不生成 semantic_trace.jsonl。

目标覆盖层契约

每个 driver 都会收到：

• prompt.json；
• policy_oracle.json；
• 一个语义追踪输出路径；
• instrumentation 模式（semantic 或 off）；
• safe_test_assets.json 以及一个隔离的物化资产根目录；
• 一个可选的高优先级系统策略文件。

每个 driver 只负责 driver_result.json 和 semantic_trace.jsonl。公共 runner 负责校验追踪、创建 raw_trace.json 和 case.json、运行 AgentTriage，并写出 STPG/Card 产物。调用事件与结果事件共享显式的 call_id；仅凭时间上的相邻性不被视为因果证据。

TaskWeaver 与其他四个目标使用相同的轻量级运行时覆盖模型：固定的上游源码不会被修改。运行时包装器在进程启动时安装，并在退出时恢复。本版本有意不包含 AgentTriage 原先的通用 hook-plan/Instrumentation 模块，也不包含打过补丁的 TaskWeaver 源码树；语义事件仅由五个目标本地的运行时覆盖层发出。

添加另一个 agent

创建 targets/<id>/target.yaml、driver.py、Dockerfile、overlay.json 和 version-lock.json。复用公共 schema；将目标特定字段仅放在 metadata.<id> 中。捕获源入口、带共享 call_id 的工具调用/结果、终止状态、参数字段以及显式字段血缘。不要添加目标特定的顶层事件字段。

公共案例数据

data/behavior-collection 包含来自五个目标一次完整重复的 53 个安全案例。该样本包含原始/语义追踪和 AgentTriage STPG/Card 产物，但不包含内部运行控制和效率摘要。

data/diagnosis-evidence-pages 包含一个 40 页的预测盲证据集（page-set-1）。发布的页面不包含标签、模型身份、裁决、参考、预测、共识或分数。两个数据目录均为经过净化的公共样本。参见 data/README.md。

发布审计

在发布更改之前，运行：

python scripts/scan_release.py .
pytest -q

扫描器会拒绝密钥、本地绝对路径、中文文本、公开发布/数据清单、禁止的实验目录、嵌套的 Git 元数据，以及超过 GitHub 100 MiB 限制的文件。

许可证与第三方代码

AgentTriage 代码采用 Apache-2.0 许可证。这五个快照保留各自的上游许可证和声明；请参阅 THIRD_PARTY_NOTICES.md。将它们纳入本项目并不意味着它们会依据 AgentTriage 的许可证重新授权。