DefenseClaw Agent360可观测性实战:为每个AI Agent建立360度安全画像
DefenseClaw Agent360可观测性实战:为每个AI Agent建立360度安全画像
AI Agent 正在替你写代码、执行命令、访问网络,但"它到底做了什么、谁派了谁、哪些动作被安全拦截"往往是黑盒。DefenseClaw Agent360 是 DefenseClaw 内置的 AI Agent 可观测性仪表盘,基于 Grafana 为每一个 Agent 建立 360 度安全画像:身份、生命周期、模型与工具调用、Token 与成本、安全决策、拦截与恢复路径,一屏尽览。
为什么 AI Agent 需要 360 度安全画像?
传统监控盯的是"进程",而 Agent 时代的威胁面完全不同:
- 行为不可预测:一次提示词注入就可能让 Agent 连续调用危险工具;
- 委派链复杂:根 Agent 会派生子 Agent,问题可能发生在任何一层;
- 安全决策分散:拦截(block)、仅观察(observe)、放行散落在各处日志里。
Agent360 把这些问题收敛成三个核心问题:这个 Agent 现在在做什么?它调用了什么?时间、Token、成本或失败堆积在哪里? 新的根 Agent 和子 Agent 会随着 Hook 事件自动出现,无需为每个 Agent 单独生成仪表盘。
一键起步:本地可观测性栈快速部署
Agent360 运行在 DefenseClaw 内置的本地可观测性栈上(OpenTelemetry + Loki + Tempo + Prometheus + Grafana),一条命令即可拉起:
defenseclaw setup local-observability up
随后按这三步完成验证:
- 打开浏览器访问
http://localhost:3000进入 Grafana(新生成的栈使用 admin 登录,密码保存在~/.defenseclaw/observability-stack/.grafana-admin-password); - 执行目的地握手测试,确认遥测链路畅通:
defenseclaw observability destination test local-observability
- 让 Agent 真实跑一轮对话或工具调用,面板即开始填充数据。
📌 栈的完整服务定义见 bundles/local_observability_stack/docker-compose.yml,CLI 管理逻辑见 cli/defenseclaw/observability/local_stack.py。
打开 Agent360:从 Agent 目录一键下钻
推荐路径是"先找人,再看画像":
- 打开 DefenseClaw → Agent identity 仪表盘;
- 在 Runtime Agent Directory 表格中选中一个 Agent ID;
- 链接自动跳转至 DefenseClaw → Agent360,并携带连接器、稳定 Agent 身份和时间范围。
也可以直接打开 Agent360,用顶部变量过滤:
| 变量 | 作用 |
|---|---|
| Connector | 区分 Codex、Claude Code 等不同连接器 |
| Agent or root ID regex | 按稳定 Agent 身份过滤,默认 .+ 显示全部 |
| Scope | This agent 只看单个 Agent;Agent tree 包含全部关联子 Agent |
| Lifecycle / Execution (drilldown) | 把执行明细面板聚焦到某个生命周期或某次执行 |
| Trace ID | 将下方面板联动到某一条 Tempo 调用链 |
读懂 Agent360 概览:从身份到健康度
仪表盘顶部刻意按"身份 → 健康 → 执行细节"排序,KPI 条一眼可读:
| 指标 | 含义 | 排查价值 |
|---|---|---|
| Agent Directory | 选定时段内观察到的所有 Agent 及根/父关系 | 确认发现情况,一键下钻到其他 Agent |
| Last seen | 最近一次关联信号的年龄 | 找出静默、失联或异常空闲的 Agent |
| Turns / Model calls / Tool calls | 去重后的逻辑轮次、模型操作、工具操作数 | 衡量自动化强度,避免镜像记录虚增 |
| Input/output tokens & Reported cost | 仅统计连接器或提供方上报的值 | 跟踪上下文增长与成本,不做臆测 |
| Terminal event success rate | 正常结束的执行占比 | 区分"完成"与"失败/中断" |
| Enforced hook blocks | 真正以 block 返回给连接器的拦截数 |
区分"真实拦截"与"仅观察"结果 |
| Observe-mode would-blocks | 因未启用强制而变成建议的拦截 | 切换强制模式前先看"本应拦住"的位置 |
下方的 Execution phase timeline、吞吐量和 p95 延迟曲线则回答"活动是否在增加、哪类操作变慢了"。
💡 Agent360 不伪造遥测:0 表示信号支持但未观察到;No data 表示该操作从未发生;Not reported 表示连接器没有上报该字段(例如 Claude Code 可能只上报模型调用而不带 Token 与成本)。
生命周期 DAG:谁生成了谁、干了什么,一图看清
Lifecycle DAG — prompt → agents → work → outcomes 是 Agent360 的灵魂面板。它回答"谁生成了谁、哪个 Agent 拥有每项工作和结果":
- Prompt inputs 分组节点统计根 Agent 收到的提示词提交;
- 父 Agent 指向每个由
parent_of/delegated_by关系确认的子 Agent,深度从0(根)开始,最深可到 64 层; - 每个 Agent 指向一组工具族摘要节点(Bash、MCP、Skills、Collaboration、File edits、Web/browser 等)和一组模型摘要节点(每个 provider/model 对一个);
- 重复调用只累加计数、不扩散节点;点击任意节点可看到背后的原始记录,并联动到日志与 Tempo 调用链。
值得注意的是:血缘关系只来自"可证明"的关系证据(reported 或显式 derived),conflicted、unresolved 等状态都会保留展示,绝不用共享 trace ID 臆造父子边。配套的 Ordered lifecycle and work sequence 面板则按时间戳把提示词、子 Agent 启停、工具调用、审批、拦截决策、终态结果串成因果时间线。
安全决策追踪:拦截之后发生了什么?
"Blocked Events"回答"拦了什么",而 Agent360 的 Hook enforcement and recovery paths 回答更深的问题:DefenseClaw 实际返回给 Agent 的是什么?Agent 下一步做了什么?
每条 Hook 投递都会产生一条持久的 hook_decision 记录:
| 字段 | 含义 |
|---|---|
| Action | 最终返回给连接器的动作,block 即已被强制拦截 |
| Raw action | 连接器/模式映射前的护栏原始结果 |
| Enforced | 仅当连接器确实被叫停时为 true |
| Would block | 原始 block 因观察模式降级为建议时为 true |
排查技巧:先看 Hook action outcomes over time 的尖峰,再自上而下读 Decision → recovery path——决策行之后的新工具调用说明 Agent 尝试了替代工具,新的模型响应说明它在"反思",终态事件说明会话结束。若拦截后没有任何新行,说明 DefenseClaw 没有再观察到该执行中的 Hook 事件,它不会凭空推断一次重试。
常见排查路径速查
| 你想知道什么 | 先看哪里 | 再钻取 |
|---|---|---|
| 为什么 Agent 还在跑? | Last seen + 执行阶段时间线 | 生命周期日志与最新 Tempo trace |
| 哪个工具拖慢了执行? | Top tools + 工具 p95 | 选定 trace 瀑布图与有序时序 |
| 是子 Agent 导致失败吗? | Agent 树 + 生命周期 DAG | 子 Agent 拥有的工作/结果节点、错误与决策 |
| Token 或成本为什么飙升? | Token/成本随时间变化 | 按 provider/model 拆分与 LLM 轮次详情 |
| 动作被拦截还是建议?之后呢? | Hook enforcement and recovery paths | 决策 → 恢复路径、判决/发现详情、对应 trace |
三个本地后端各司其职:Prometheus 提供目录、计数、吞吐与延迟;Loki 承载 DAG、有序时序与各类明细日志;Tempo 保存单次请求有界的调用链瀑布图。
去哪里看更多?
- 官方 Agent360 指南:docs-site/content/docs/observability/agent360.mdx
- Grafana 仪表盘目录:docs-site/content/docs/observability/grafana-dashboards.mdx
- Agent360 仪表盘定义:bundles/local_observability_stack/grafana/dashboards/defenseclaw-agent-360.json
- 本地可观测性栈总览:docs/OBSERVABILITY.md
⚠️ 一个安全提醒:仪表盘展示的是 DefenseClaw 导出前的"准 OTEL 投影"。默认 v8 脱敏策略为 none(不脱敏),在共享或多租户环境中启用 Agent360 前,建议先配置 sensitive、content 或 strict 脱敏配置,保护提示词与工具载荷。


