BKN Foundry BKN Trace:如何让AI智能体的每一步行动都可追溯——证据链与可观测性落地详解
BKN Foundry BKN Trace:如何让AI智能体的每一步行动都可追溯——证据链与可观测性落地详解
BKN Trace 是 OpenBKN 本体平台(BKN Foundry)的社区版 Trace Core。它记录 AI 智能体、SDK 与 MCP 调用的一手执行事实,提供受访问控制的 Trace 查询 API 与平台日志的精确关联能力,把"智能体到底做了什么"变成一条可审计、可回放的证据链,让 AI 智能体可观测性落地不再依赖猜测。
🧭 为什么 AI 智能体的每一步行动需要可追溯
当你让一个 AI 智能体去查数据、跑代码、调用业务工具时,通常只能看到最终答案,看不到中间发生了什么:
- 它调用了哪些工具?传了什么参数?工具返回了什么?
- 哪一步耗时最长?哪一步失败了?错误是如何传播的?
- 它引用的"事实"来自哪次查询?证据是否齐全?
- 出了问题后,如何向团队和审计方证明执行过程是可信的?
大模型的输出天然具有不确定性,"能跑通"并不等于"过程正确"。BKN Trace 就是为回答这些问题而生的 AI Agent 行为追溯服务:它为每一次受管执行建立完整链路,覆盖从用户输入到最终回复的每一步决策与操作。
📝 BKN Trace 记录什么:只记一手事实,不做猜测
理解 BKN Trace 的关键是它的核心原则:只记录一手事实,不从最终回答反推执行信息。未记录的信息会被明确标记为"未记录",而不是由读取端或界面悄悄补全——这正是"证据链"可信的基础。
三层执行数据模型
BKN Trace 以 Operation 的一次 attempt(尝试) 作为权威执行单元,向上组织为三层结构:
| 层级 | 含义 | 保留的关键事实 |
|---|---|---|
| Conversation | 一次完整对话 | 会话标识、参与者、起止状态 |
| Interaction | 对话中的一轮交互 | 问题与答案、执行状态、证据状态 |
| Operation (attempt) | 一次工具/服务调用尝试 | 请求标识、调用身份、协议与工具信息、调用边界实际收到的输入、输出或错误、耗时与状态 |
两个容易忽略但非常重要的保证:
- 记录不改业务:采集 Trace 不会改变业务工具的原始返回结果,观测链路对业务是"无感"的;
- 缺失即缺失:证据缺失时会在完整性检查中给出明确的
drop_reason(如publisher_unavailable、queue_full),而不是含糊地"看起来完整"。
整体架构一图看懂
受管 MCP / SDK 调用
|
v
Trace 生产者采集一手执行事实
|
v
BKN Trace Core
- 生命周期与 Operation 调用事实
- Evidence 与技术关联
- 访问控制读取 API
|
+--> 技术 Trace 分析
+--> 精确日志下钻
BKN Trace Core 刻意保持"技术事实服务"的定位:它不从最终回答推导业务语义,也不建立第二套权威 Trace 存储。架构说明详见 bkn-trace/README.zh.md。
🔗 证据链如何落地:从采集到查询的完整路径
一条证据链的成型要经过"采集 → 持久化 → 投影 → 查询"四个环节,BKN Trace 在 Foundry 仓库中由几个模块协作完成:
第一步:采集——生产者记录一手事实
各受管服务(BKN Agent、Context Loader、ontology-query 等)在调用边界记录生命周期事件与工具回执。共享的证据发布库位于 comm-go/bkntrace/evidencepublisher/,统一处理采集策略(capture policy)校验、队列闭合确认与去重,保证"发了什么、丢了什么"都有账可查。
第二步:传输——OTLP 与 Kafka 双通道
- 技术 Trace(Span 数据):各服务按 OpenTelemetry 标准上报 OTLP,由 otelcol-contrib Chart 部署的 OpenTelemetry Collector 接收(gRPC
4317/ HTTP4318),并写入 OpenSearch 的ss4o_traces-*索引; - 证据事件(Evidence Events):经 Kafka topic
openbkn.evidence.v1进入 Trace Core 的 Ledger,权威事实持久化在 MariaDBbkn_trace库中,相关迁移脚本见 migrations/bkn-backend-trace-outbox/。
第三步:投影——把事实变成可检索的文档
Trace Core(agent-observability 服务)内置投影 worker,把 MariaDB 中的回执与证据事件可靠地投影到 OpenSearch,支持重试、死信与显式恢复——即"数据晚到"不会导致证据链断裂,只会如实标记状态。
第四步:查询——受保护的技术读取 API
服务启动后,最常用的三个入口(前缀均为 /api/agent-observability/v1):
GET /traces:类型化 Trace 列表,支持按状态、错误关键词、根服务、根工具、关键词筛选与游标分页;GET /traces/{trace_id}:单条 Trace 技术详情,包含 Span 图、Operation 调用事实(单次最多 1000 个 Span 节点,超限会明确标记截断);GET /interactions/{id}/operations:该轮交互中已记录调用的输入、输出与错误事实。
完整的接口契约可查阅 OpenAPI 定义。
🕵️ 5个每个Agent运维者都会用到的Trace分析场景
Trace 数据不只是"存起来",更在于"查得出"。以下是官方手册中最典型的使用场景(详见 BKN Trace 使用手册):
| 场景 | 怎么看 |
|---|---|
| 性能瓶颈定位 | 比较同层级 Span 的 duration_ms,找到耗时最长的环节 |
| 错误溯源 | 从 status=error 的 Span 沿父子关系回溯到根因 |
| Token 用量审计 | 通过 events 中的 token_usage 事件统计模型调用成本 |
| 决策路径回放 | 按 Span 父子树重建智能体完整的思考与执行路径 |
| 工具调用审计 | 逐个检查工具调用的输入参数与返回结果 |
每个 Span 的关键字段一目了然:
| 字段 | 说明 |
|---|---|
span_id / parent_span_id |
Span 标识与父子关系(根 Span 父 ID 为空) |
operation |
操作名称,如 planning、tool:web_search |
start_time / duration_ms |
起止时间与耗时 |
status |
ok、error、timeout |
attributes / events |
键值属性(模型名、查询词)与事件(token 用量、错误详情) |
日常排障可以直接用命令行,以树形结构展示整条链路:
openbkn agent trace agt_001 conv_20250115_001 --pretty
输出会按树状展示每层 Span 的耗时与状态,哪个环节慢了、哪一步失败了,一眼可见。
🚀 BKN Trace 快速部署:两个 Chart 打通全链路
如果想在自己的环境体验完整的 Trace 采集链路,整个流程只涉及两个 Helm Chart。先获取仓库:
git clone https://gitcode.com/openbkn-ai/bkn-foundry
cd bkn-foundry/bkn-trace
1. 部署 Collector(OTLP 入口 + OpenSearch 出口):
helm upgrade --install otelcol-contrib otelcol-contribute-chart/charts/otelcol-contrib \
-n observability --create-namespace
2. 部署 Trace Core 服务(启用 MariaDB 持久化与投影):
helm upgrade --install agent-observability agent-observability/charts/agent-observability \
-n observability \
--set core.store=mariadb \
--set core.projection.enabled=true
部署前需准备好 MariaDB 连接 Secret(
bkn-trace-core-mariadb)与 OpenSearch 地址;Chart 默认值为内存存储,生产启用受管事实时必须显式切换为上述配置。详细参数与验证步骤见 agent-observability 服务 README。
部署完成后,可用一条简单命令验证链路是否打通:查询 OpenSearch 的索引列表,看到 ss4o_traces-* 索引即表示 Collector 已成功写入。
🔐 权限与安全:谁能看到哪条 Trace
可追溯的前提是"可控的可见"。BKN Trace 在每次返回数据前都会执行 Access Profile + 记录范围双重校验:
- 身份来自服务端:公开写入的 owner 由服务端根据 OAuth 与 BKN Safe 身份派生,客户端不能自报或伪造身份;
- 跨归属一律 404:查询不属于当前授权范围的 Trace 统一返回 404,不泄露该记录是否存在;
resource_not_disclosed则表示记录存在但当前范围不可披露; - 敏感数据分级:原始 Span 图仅
admin/super_admin可读,普通授权用户获得作用域内的摘要与 Operation 详情; - 内部控制面隔离:采集策略、心跳与确认接口仅挂载在集群内部 8081 端口,不通过 Ingress 暴露;证据写入另需独立 ingest token。
这套机制保证了同一套 Trace 数据,管理员看到全貌、应用方看到自己的一份,互不越界。
📊 容量与留存:生产环境的实用建议
上线前值得花十分钟想清楚两个问题:任务流速与数据留存。
- 任务流入估算:活跃 Agent 数 × 每 Agent 轮次频率 × 每轮实测投影任务数(含生命周期、回执、答案持久化),完整公式见 资源与容量参考;
- 服务端容量配额:单个 Interaction 默认限制 256 个 Operation、32 个 Claim、4096 个 evidence ref,第三方 Agent 无法在请求中覆盖,避免单条对话拖垮整条链路;
- 自动归档:一次
POST /api/observability/v1/log-archive-jobs调用即可自动按批(每批最多 10,000 条)归档与清理历史日志,每批独立保存任务、manifest 与进度,失败可安全重试,无需自建调度。
Trace 不是越多越好,留存策略应该基于实测的日增量来定,而不是拍脑袋。
❓ 常见问题速查
Q:记录 Trace 会影响业务工具的返回结果吗? 不会。BKN Trace 明确承诺"记录 Trace 不得改变业务工具原本的返回结果",观测链路对业务透明。
Q:Community 版和 EE(企业版)有什么区别? Community 提供受授权的基础事实、技术 Trace 读取与证据事件接收;企业原生业务溯源(business-provenance 路由与解释生成)需要实际装配 EE 实现并通过运行时许可,Community 不会挂载这些路由。
Q:查询别人的 Trace 为什么总是 404?
这是设计行为:跨归属查询统一返回 404,不泄露记录是否存在;若返回结构化的 resource_not_disclosed,则说明记录存在但当前授权范围不可披露。
Q:大范围搜索报错 SUMMARY_QUERY_BUDGET_EXCEEDED 或 SUMMARY_QUERY_TIMEOUT 怎么办?
说明查询超出了 30 秒期限或候选数量预算。缩小时间窗口或增加筛选条件,并使用返回的 cursor 游标分页,而不是深页码偏移。
Q:证据一直显示"不完整",是采集丢数据了吗?
不一定是。完整性检查会给出具体原因:可能是发布器不可用(publisher_unavailable)或队列已满(queue_full)。业务调用可以是 completed 的同时结果证据仍缺失——两者是相互独立的事实,请优先检查对应生产者的运行日志。
📚 延伸阅读与模块速查
| 资料 | 说明 |
|---|---|
| bkn-trace/README.zh.md | 模块总览:记录范围、能力边界与筛选规则 |
| bkn-trace/agent-observability/README.md | 服务开发、配置、部署与本地验收 |
| bkn-trace/otelcol-contribute-chart/README.md | Collector Chart 部署与 telemetrygen 验证 |
| help/zh/manual/bkn-trace.md | 使用手册:数据结构、CLI、SDK 与 curl 示例 |
| help/zh/manual/bkn-trace-evidence-enablement.md | Evidence 启用配置与原生归因验收流程 |
| help/zh/manual/bkn-trace-resources.md | 资源预算、留存与 backlog 恢复规划 |
| docs/api/agent-observability/agent-observability.yaml | 统一发布的 OpenAPI 契约 |
| bkn-trace/CHANGELOG.zh.md | 版本更新日志 |
| comm-go/bkntrace/evidencepublisher/ | 共享证据发布库源码 |
✍️ 小结
BKN Trace 用一套清晰的原则解决了"AI 智能体黑盒"问题:只记一手事实、缺失即标注、查询受权限约束、归档可安全重试。它不试图替你解释业务语义,而是把证据链完整地交到你的手上——无论是定位一次失败的工具调用,还是向审计方回放一次智能体决策,你都能拿到"发生了什么"的确定性答案。对于正在落地智能体可观测性的团队,这是 OpenBKN 生态中最值得先跑通的一环。



