Claude Code 意外开源：我们看到了每一个企业级 Agent 都需要行为分析

在2026年3月31日的时候，Anthropic的Claude Code由于一个npm source map打包方面出现的失误，使得大约51.2万行TypeScript源码被完整地暴露在了公网上。存在着1906个文件、59.8MB的source map，这把当前最为复杂的AI编程Agent的内部架构全部展现在了阳光下。

多数剖析着重于记忆系统、卧底模式、反蒸馏这般引人瞩目的功能方面。然而，将主流 Agent runtime 的源码翻阅查遍，我们觉得 Claude Code 最被看轻的部分之处，乃是其针对自身行为的观测架构。此架构展现出一个正逐渐形成的全新领域：ABA，也就是 Agent Behavior Analysis，即 Agent 行为分析。

一、51 万行代码里，藏着一套完整的 Agent 可观测性工程

Claude Code压根就绝对不会是，那种仅仅只是套了个壳子的所谓LLM。The Neuron的分析，简直是一针见血：它实际上更加接近于，一个专门面向软件工程范畴的操作系统，权限层、记忆层、后台任务、IDE桥接、MCP管道、多Agent编排，这些内容全部都是堆叠于模型的周围。依据The Neuron跟alex000kim的独立分析结果来看，在51.2万行TypeScript里面，直接去调用AI模型接口的代码，仅仅只有大约8000行，占比为1.6%。剩下的百分之九十八点四，具体涵盖了四万六千行的QueryEngine，两万九千行的工具系统，两万行的安全与权限控制，一万八千行的多Agent编排，这些全都是围绕模型构建的工程基础设施。

透露源码里 INTERNAL_MODEL_REPOS 这个常量，不但将 Anthropic 的内部仓库清单给泄露出来了，而且还把 Undercover 模式存在这事揭示了出来，此模式是专门用来防止代号被泄露的。

然而，切实能使我们激动不已的并非是这些功能自身，而是名为services/analytics/ 以及utils/telemetry/ 的这两个目录。

Claude Code 在可观测性方面所投入的精力，远远不只是局限于“记录日志以及统计接口运行所耗费的时间”这种程度。它针对 Agent 运作期间的语义开展了系统性建模工作，进而形成了直至目前最为完备的 Agent 可观测工程范例。以下存在四件事情，其中每一件都能够直接予以采用。

1.1 三层分离：不要一锅端

可观测性被Claude Code拆分成了三个独立层次，这三个层次各管各的事。

第一层：产品分析事件。

入口处于services/analytics/index.ts这个位置，不存在依赖模块，它提供logEvent()作为统一入口，当sink未进行挂载的时候就先进入队列。然而后端路由是在sink.ts那里，会被分流到Datadog以及1P（也就是first - party）event logging。此刻回答的问题正是：究竟发生了什么样的产品事件呢？——tengu_oauth_flow_start，tengu_plugin_install_command，tengu_session_resumed，这些是产品经理以及运营所关注的内容之物存在的表现形式，是产品经理和运营关注的东西。

第二层：标准化 telemetry。

以 OpenTelemetry 的 metrics、logs、traces 为依据使用的主入口所处位置为 utils/telemetry/instrumentation.ts，其是按照 exporter 配置而被引导至 OTLP、Prometheus、console 或者内部导出器的。所回答的问题是：指标以及标准 traces 要怎样接入后端呢？——此为基础设施观测层，着重突出标准生态兼容。

第三层：会话级 Tracing。

核心模块utils/telemetry/sessionTracing.ts，不对网络请求进行追踪，而是直接针对Claude Code的业务语义建模，这些业务语义包括interaction、LLM request、tool调用、hook、被用户阻塞的时间。所回答的问题是：在runtime里，一个Agent turn是如何展开的？

为何不可以掺和到一块去呢？是由于一开始便试图达成“全部都记住”，很快就会踏入三个陷阱之中：

1.2 统一关联键：先把同一个实体串起来

在Agent系统当中，真正具有难度的并非是“生成一条事件”，而是“使得不同的事件能够被关联起来”。

Claude Code，于关联键方面所做之事，呈现出克制之态，且具备精准之质，其集中于两处展开管理。

为什么会如此复杂呢？原因在于，在同一个系统当中，Agent 存在多种情况，它有可能是同进程的 subagent，还有可能是 swarm teammate，另外也有可能是 standalone agent。可观测性层没办法假定仅有单一的身份来源，它必须自行进行统一归并。归并完成之后，后端所获取到的是一个最小可关联图，这个图包含这些信息：当前 session 是谁，当前 agent 是谁，上游 parent session 是谁，它属于哪个 team。排查多代理问题时，这是关键。

1.在3 Agent语义级 Span中，所进行的是trace一个turn，而非trace一个函数。

包含 sessionTracing.ts 的这个整体架构里，sessionTracing.ts 属于其中最具价值的部分，它将 Claude Code 的业务语义直接编码成了 span 类型。

根节点的挑选极为能表明问题，可观测性的基本单元是“用户的一回交互轮次”，并非某一回网络请求，一回turn通常涵盖prompt处理、多次模型调用、多个工具执行、可能存在的人工确认、hook以及恢复逻辑，要是没有interaction作为根节点，后续所有span会碎成平铺开来的事件，在读取trace时根本没法看出这一轮究竟发生了啥。

更具精妙之处的是，名为tool.blocked_on_user的这个span，众多Agent平台之于做tracing，仅仅是去追踪模型延迟以及工具延迟，然而Claude Code尚还独立去追踪“等待用户批准的时间”，这等同于承认了这样一个事实，即Agent的真实耗时并非全然是机器耗时，权限审批以及人工中断本身便是主链路的一部分，在将这类时间独立出来以后，你才能够去回答，慢是由于模型慢还是审批慢？存在某类工具，其成功率处于较低水平，究竟是执行方面出现了问题，还是审批被拒绝的情况过多呢？有一个turn的时长很长，时间主要是耗费在Agent计算上，还是等待他人上呢？

这便是 Agent 行为观测的关键价值所在，并非向你揭示“Agent 调用了哪些 API”，而是告知你“Agent 的一回全程行为是怎样进行的、在何处出现卡顿、为何会出现卡顿”。

实际达成情况来看，sessionTracing.ts借助AsyncLocalStorage去保管interactionContext以及toolContext，往后的llm_request、tool.execution、hook会自动地挂载到准确的父节点之下。对于并发归因，也进行了相应处理，endLLMRequestSpan() 明确地向调用方发出提醒，在多请求并发的情况下，也就是 warmup、topic classifier、主线程请求同时处于进行状态时，必须传回原始的 span 实例，不然的话，响应将会被错误地归因。悬挂，span，清理，采用WeakRef加上30分钟的TTL，以及60秒的扫描间隔，源码注释写得极为直白：这是“针对那些从未结束的spans的安全网”，——中止的流，未捕获的异常，查询中途的中断，在Agent runtime里并非边缘情况，而是常态。

1.4 信号各归各位，Taxonomy 即治理

没有将全部信号都压缩成“事件”的是 Claude Code。Event 关注离散行为，也就是某类行为是否出现 ，Trace 关注因果链，即一个 turn 是如何开展的 ，Metric 关注趋势，像是 session 数、token 统计以及成本。若不进行分层，那么要么把所有内容都塞进 trace 从而致使 trace 出现爆炸情况，要么把所有东西都标记为 event ，之后就只能通过写 SQL 来拼凑执行过程了。

更值得注意的是隐私治理前置到了采集阶段：

分类学并非单纯分类之事，而是关乎治理问题；可观测性在起始阶段便需与隐私、基数以及后端能力伴同设计。

小结：得先对ABA那四个能够直接带走的结论去做目标分层，产品事件、标准telemetry、会话tracing这三层各自管各自的事务，统一关联键相较于多打一条日志更为重要，sessionId、agentId、parentSessionId、teamName决定了多代理系统的动作能否串联起来，业务语义级tracing才是真正具有效用的。Function耗时相较于interaction、llm_request、tool.blocked_on_user，更难以就Agent为何慢、卡于何处给出解释。Taxonomy属于治理问题。针对metadata、字符串、MCP名称以及字段粒度的约束，表明可观测性自起始便需与隐私、基数、后端能力共同展开设计。二、工程美学：为何观测云天然契合于成为Agent可观测。

在观测云和Claude Code的可观测架构设计方面，存在着一些趋同之处。当AI Agent踏入企业生产环境时，问题会愈发尖锐：你并非在观测自身的Agent，而是在观测他人的Agent——并且它正在操控你的生产系统。观测云的架构，从本质上来说，就是解决这类问题的最佳方案。

2.1 数据模型不应该是预设的：Schemaless 的力量

Claude Code的metadata.ts做出了一个极为工程化的决定，这个决定是，Agent的身份来源并非是预设好的。在同一个系统当中，Agent有可能是subagent，有可能是teammate，也有可能是standalone，可观测性层必须要自己去做统一归并，而不是假定仅仅只有一种身份模型。

对云进行观测的 GuanceDB，做出了同样的抉择，不过处于更为底层：Schemaless。它准许写入随便哪个字段，能够实时对数据的字段实施增加或删除操作，无需人工去维护数据模型。这并非是偷懒行径，而是对现实状况怀揣的尊重——于可观测性场景当中，你始终没办法预先知晓接下来要去观测的维度究竟是什么。Agent 系统更是这般：今日你所需的是 sessionId，明日或许所需的是 parentSessionId，而后天说不定所需的是 teamName。要是每增添一个字段，就得去修改 schema，还得运行 migration，那么可观测性就会始终赶不上业务变化所具有的速度。

Claude Code于应用层面化解了“Agent身份不可预先设定”这一问题，观测云于存储层面解决了“观测维度不可预先设定”的问题，以同一思路，在不同层次，观测云去除了解决问题时的摩擦成本。

2.2 采集和处理必须分离，且处理必须可编程

Claude Code的可观测性链路存在着颇为明晰的分层：analytics/index.ts承担着事件入口（采集）的职责与功能，sink.ts负责后端路由以及脱敏（处理）的相关事宜，二者借助队列实现解耦。logEvent()的调用方并不清楚后端究竟是Datadog还是1P，sink能够进行延迟装配，启动早期的事件不会出现丢失的情况。

DataKit，一个处在目标环境里的独立数据采集器，干了和观测云同样的事，而且做得更彻底。它采集的数据，经由运行于自身的轻量级可编程脚本语言Pipeline，也就是Pipeline，进行自定义解析、切割、过滤以及结构化转换，之后通过统一的Dataway接口上报。

关键词儿是可编程的情况。在 Claude Code 的 sink.ts 这个其中呢，脱敏逻辑也就是 stripProtoFields() 这个东西，还，还有采样配置也就是 tengu_event_sampling_config ，以及字段约束也就是 marker type ，这些通通都是硬生生被编码在 TypeScript 里头的。就针对一个单一产品来讲的话，这样子是够用的。然而，对于一个需要去为千差万别的 Agent 系统提供服务的可观测性平台而言，其处理逻辑必然得是能够让用户自己去进行定义的。

管道便是这个答案。你能够借由它对OpenClaw的非结构化日志予以切割，使其成为结构化字段时，你能够凭借它将不需要的数据过滤掉，你能够运用它于采集之际便达成脱敏——并非等到数据抵达平台再去处置。这跟Claude Code的_PROTO_*分层脱敏是同样的设计直觉：治理需前置至采集阶段，只是观测云把这种能力开放给了用户。

2.3 查询语言必须是自研的、统一的

Claude Code内部存在着一个行数为4.6万行的QueryEngine，该QueryEngine在Agent运行之际，会针对上下文、记忆以及代码库去开展检索以及推理的工作。它并非是以简单的方式将所有东西都塞入上下文窗口，而是构建起了按需检索的机制，其中记忆所充当的角色是索引，并非仓库。

由观测云自主研发的 DQL（Debug Query Language），是专门针对时序数据、日志数据以及事件数据的高效查询与分析所设计的。它具备这样的特性，即一条 DQL 能够实现跨数据源的关联查询，具体而言，trace_id 存在于链路数据之中，token 用量处于指标数据里面，错误详情则在日志当中，通过这样一条查询就实现了串联，无需在三个界面之间来回跳转，如此这般。

这背后存在着同一个执念，当你所面对的数据具备足够的复杂性、足够的异构性时，通用查询语言无法满足需求，此时你需要一种专为你的领域特意设计的查询语言，Claude Code的QueryEngine是针对Agent认知状态设计的，DQL是为可观测性数据设计的，两者都摒弃了“用现成的就行”这一诱惑。

2.4 对高基数的敬畏与治理

Claude Code 的 telemetryAttributes.ts 文件里头，session.id、版本号、还有 account UUID 这些字段带或者不带，是受 OTEL_METRICS_INCLUDE_* 环境变量所控制的。作者在主动进行 cardinality 的管理，高基数字段并非默认全部塞进指标系统当中的。MCP 工具名默认收敛成为 mcp_tool，只有在白名单之内的 server 才会把更细致的名字放出去的。

GuanceDB，对高基数指标予以了写入上的优化，还进行了查询方面的优化，以此来确保，高基数不会对数据库稳定性造成影响。

这绝非巧合。任何有过可观测性相关经历的人都清楚，高基数属于可观测性系统最为致命的杀手。Claude Code于客户端一侧借助环境变量以及白名单对其予以管理；观测云却是在存储引擎层面针对它进行解决。面对的是同一个敌人，分布于不同的处理领域之中。

2.5 总结一下这种设计趋同

在四个地方独立地走向了相同的工程结论。

你认真去面对，关于“如何让复杂系统的内部状态变得可理解”的这个问题之际，工程上的最优解呈现出收敛的状态，原因就在于此。

三、场景驱动：企业级 Agent 行为监控的真实价值

Agent 逐渐开始接管企业核心业务流程，在此情形下，让我们来瞧瞧，于实际企业环境当中，Agent 可观测究竟是怎样发挥其作用的。

场景一：成本刺客的精准定位（Token 消耗归因）

在某企业，其上线了基于大模型的智能客服 Agent 之后，月底账单出现了暴涨情况，涨幅达到了 300%。对此，研发团队把应用日志都仔细查看了一遍，虽然知道总 Token 消耗数量十分巨大，可为：是哪一个技能（Skill）消耗 Token 最多？是 Prompt 的哪个版本致使上下文出现了膨胀？却没办法给出答案。

Agent观测价值：借助通过观测如云，这般的Agent去调用那般的分析看板，企业能够以应用、模型、甚或具体的sessionId来展开聚合分析。团队快速定位到：乃是一个全新增加的“历史订单查询”技能，于多轮此等对话里未实施上下文截断操作，最终致使每次请求过程中皆携裹着数百条历史记录去作请求大模型之举。精准归因之后，仅仅经过只需三行代码的修复进程，就把每天数目达数千元的API浪费给成功挽回了。

场景二：失控 Agent 的紧急熔断（实时告警与行为追踪）

难点在于：有一个用于自动化运维的 Agent，此 Agent 被赋予了执行数据库清理任务的权限，然而呢，因为在某种边界条件方面出现了判断错误的情况，于是这个 Agent 就开始在生产库当中执行大规模的 DELETE 操作了，而传统的监控系统仅仅关注并查看 CPU 和内存，对于这种处于“业务逻辑层面”的破坏完全没有察觉到。

代理商观测价值方面，代理商的每一回工具使用，像是执行 SQL 的情况，都被记作语义级跨度。观测云的实时告警策略察觉到，这个代理商在一分钟之内持续调用了五十次的高危工具，也就是 execute_sql_delete ，马上就触发了网络钩子告警，还联动自动化脚本吊销了这个代理商的数据库权限。随后，借助完整的Trace链路，研发的团队清楚地重新审视了Agent是怎样一步步得出错误结论的，是这样的情况。

场景三：针对多 Agent 协同展开死锁排查，此排查涉及对统一关联键进行分析，还涉及对拓扑进行分析。

存在这样一个痛点，在那种复杂的研发场景当中，企业部署了由“需求分析Agent”、“代码编写Agent”、以及“测试Agent”共同组成的Swarm。然而最近系统却频繁地出现卡死的状况，需求分析Agent认定任务已然进行了交接，可测试Agent却一直在无限期地等待代码产出。

Agent观测价值在于，凭借parentSessionId与agentId的统一关联，观测云把离散的Agent动作串联起来，进而形成了一张完整的服务拓扑图。凭借拓扑分析，团队直观察觉到，代码编写 Agent 调用 git_commit 工具之际，因权限缺失而被阻塞，此情况对应 Claude Code 里的 tool.blocked_on_user 状态，然而它却没能正确地向上游抛出异常，从而致使整个 Swarm 陷入死锁状态。Agent 行为分析使得这种跨 Agent 的“暗流”清晰显现出来。

场景四：合规审计与越权监测（隐私治理前置）

在金融企业引入财务分析 Agent具有痛点，此情况下，财务分析 Agent被要求只能访问脱敏后的报表数据，那么怎么向审计部门去证明，这个具备极高自主性的 Agent没有偷偷去读取包含客户隐私的原始数据库呢？

要是 Agent 去尝试调用那个不在白名单里的 MCP Server，比如说试图连接外界网络呀，甚或是去访问原始库，而一旦被 Agent 瞧见这种情况，系统立马就会去进行记录，紧接着还会加以阻断，这可不就只是单纯的技术方面开展相关监控了，实际上它更是为契合监管要求而构造出的合规根基呀。

四、趋势：每个进入生产环境的 Agent，都需要行为分析

Claude Code的泄露，给全行业上了一课。这课并非关乎安全，虽说安全也很重要。而是关乎复杂自治系统的可治理性。

Claude Code每日耗费二十五万次API调用之事（autoCompact.ts里的注释表明，在1279个会话里出现50次以上连续失败，最多达到3272次）究其实质乃是一个欠缺可观测性的事。修补方略为一行是声明（或赋值）MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3这样的三行程序的某语言写。

当Agent从开发者工具迈向企业生产系统时，这类问题将会变得愈发繁多，愈发隐蔽，且代价愈发高昂。

Claude Code的架构向我们传递出这样的信息，即对于一个处于生产级别的AI Agent而言，其可观测性代码所具备的复杂度，并不亚于它的核心功能代码，是这样的情况。services/analytics/ 这个目录之下的设计精度，utils/telemetry/ 这个目录之下的工程治理水平，表明 Anthropic 将 Agent 行为分析视作一等公民，包含三层可观测性架构、语义级 span 模型、统一关联键、隐私治理前置、失败补偿链路[磁盘缓冲 + quadratic backoff + span TTL cleanup]，这不是事后补充的“日志系统”，而是与 Agent 核心逻辑同步设计的基础设施。

可是，Claude Code 自我进行观测，它无需去考量，“别人的 Agent 呈现出什么样的样子”。

针对观测云这块，需要去实行更具难度之事，那就是促使每一个Agent，无论它是白盒的Claude Code，还是灰盒的OpenClaw，亦或是企业自行研发的闭箱Agent，使其每一次的interaction，每一个tool call，以及每一段的blocked_on_user等待，统统都转化为能够进行查询、关联以及治理的遥测数据。

期盼着，我们能够将它转变为基础设施，此基础设施是每个Agent都能够运用的，进而为每个企业供应那种开箱之后就能够使用的Agent可观测能力。

参考资料：

相关标签： # AgentBehaviorAnalysis # ObservabilityEngineering # Telemetry # CloudMonitoring # AIAgents