AI代理审计日志需要12个字段：LangChain、CrewAI及其他四种工具记录的内容。
共有六种代理框架被纳入统计，包括LangChain、CrewAI以及OpenAI Agents SDK，针对12个字段的审计追踪草案，其平均覆盖率为12个中的5个。
来源: AI Agent Audit Logs Need 12 Fields. We Counted 6 Frameworks — the Median Records 5.
痕迹看似证据，实则不然
想象一下，某个代理调用了某个工具：进行资金转账、删除数据库中的某一行数据，或者发送一条消息。之后，就必须回答一个问题，即该代理的操作是否能够被证实。此时会查看相关痕迹，其中会显示包含名称、开始时间、输入内容及输出结果的记录片段。这看似证据，但实际上只是披着证据外衣的调试辅助工具而已。
为衡量这一差距，我们克隆了2026年9月4日最新提交版本的六个开源智能体框架及相关规范：OpenAI Agents SDK、LangChain、CrewAI、LlamaIndex、smolagents和OpenInference。提取了每个项目工具调用记录中的字段，并与最新智能体审计轨迹格式要求的十二个必填字段进行对比。结果显示：典型框架仅能覆盖审计记录所需的十二个字段中的五个，且这六个框架中没有一个具备用于证明数据未被篡改的专用字段。
哪些框架具备相关功能有助于调试工作，而审计记录则承担其他功能，两者之间的差距可通过数值体现。
统计得出的五项发现
- 在这五个框架中，十二个必填字段的平均覆盖率为5个：smolagents覆盖1个，LlamaIndex覆盖3个，OpenAI Agents SDK覆盖5个，CrewAI覆盖5个，LangChain覆盖6个。
trust_level这一字符串在所有六个代码库的文件中均未被发现。即便遍历每个仓库中的所有 Python 和 TypeScript 文件，也找不到相关记录。prev_hash、previous_hash和hash_chain同样没有对应任何文件。由于没有框架能将不同记录相互关联，因此后续可以修改追踪存储内容而不会留下痕迹。- 生态系统中功能最完善的监控规范 OpenInference 拥有 119 个命名空间级别的属性，但在 12 个需要监控的字段中仅能覆盖 8 个，且没有包含任何防篡改证据字段。
- 五个框架中仅有
timestamp这一个字段会被记录。agent_id、session_id和record_phase在五个框架中各有出现一次，而agent_version、outcome和trust_level则完全没有被记录。
框架在调试方面具备完善的工具支持，但在提供证据方面则工具较为薄弱。这两者极为相似，以至于在有人要求证据之前，这种替代现象根本不会被察觉。那些缺失的字段并非什么特别罕见的东西，它们能够表明是谁采取了行动、在何种授权下进行的，以及记录之后是否被修改过——这些都是调试跟踪本来就不需要回答的问题。
计数方式
各项目的提交记录已修复：OpenAI Agents SDK（openai-agents-python）的版本为89c02c8，LangChain为0d50cbd，CrewAI为92eb5f9，LlamaIndex为d2ac544，smolagents为30bb116，OpenInference为479d168。每个项目的字段列表均来自记录单次工具调用的类，即包含该调用范围及其特定工具的负载信息，这些字段是从类定义中获取的，而非文档。之后，这些字段会与当前审计追踪草案中的十二个必填字段进行比对。
若某个字段仅部分满足要求，则会被标记为“部分符合”，并附上原因说明。例如，LangChain的error字段会报告出现故障，但无法区分故障是源于超时、被拒绝还是其他原因。
该截图展示了运行过程：共有六个仓库处于领先位置，每个工具调用字段都被提取出来，并与十二个字段进行对比评分。trust_level和prev_hash在各处的数值均为零。
十二个字段
评判标准是CyberSecAI的Raza Sharif于2026年9月3日发布的互联网草案版本02中的代理审计追踪规范。这只是一个单独提交的方案，并非得到IETF认可的标准化规范，因此属于经过深思熟虑的提议而非既定法则。即便如此，它仍是目前最具体的公开解决方案，其十二个必填字段也无可争议：
record_id是该记录的唯一标识符。timestamp以RFC 3339格式标注事件发生时间。agent_id用于标识执行操作的代理实例，agent_version则用于标识其软件的版本。session_id将操作与特定会话关联起来。action_type采用标准化的词汇表而非自由文本，action_detail则存储与该类型操作相关的具体数据。outcome的可能值为成功、失败、超时、被拒绝或已升级。trust_level表示代理操作所依据的权限等级，范围从L0到L4。parent_record_id指向链中的前一条记录，prev_hash则存储该记录的SHA-256哈希值。record_phase用于说明该记录是在操作执行之前、期间还是之后创建的。
将那个列表放在span对象旁边，问题的概要就会显现出来。前八个字段是调试器可能需要的，而最后四个字段仅对审计人员重要，而这四个恰恰是缺失的字段。
按框架统计
工具调用记录中的字段数量及对十二种框架的覆盖率：
- CrewAI（
ToolUsageFinishedEvent加上BaseEvent）：25个字段，其中5个完整，3个部分完整，4个缺失。 - LangChain和LangSmith（
RunTree0.12.1版本）：20个字段，其中6个完整，1个部分完整，5个缺失。 - OpenAI Agents SDK 0.22.0（
SpanImpl加上FunctionSpanData）：13个字段，其中5个完整，2个部分完整，5个缺失。 - LlamaIndex（
SimpleSpan加上BaseEvent）：10个字段，其中3个完整，1个部分缺失，8个完全缺失。 - smolagents 1.26.0（
Timing加上TokenUsage）：6个字段，其中1个完整，没有部分缺失的，11个完全缺失。 - OpenInference语义规范定义了119个命名空间内的跨度属性（在commit 479d168时为不同的带点属性名常量，另有43个为枚举值未被包含），其中8个完整，1个部分缺失，3个完全缺失。
原始字段数量并不能预示审计能力。CrewAI记录的字段最多，但满足的要求却少于LangChain，因为它25个字段中的大部分都是与团队相关的上下文信息，如agent_role、from_task、plan_step_number和delegations。这些字段虽实用，却无法回答任何审计问题。工具的丰富程度与证据的相关性几乎不存在关联。
图表清楚地显示了这一点：CrewAI的字段数量虽多于其他任何框架，但满足的要求却少于LangChain，因为它的大部分额外字段都是团队上下文信息，而非证据。
CrewAI 的独特之处在于：它将 ToolUsageStartedEvent 和 ToolUsageFinishedEvent 作为独立的类来处理，因此它拥有真正的 record_phase，即在工具运行之前就已存在的记录。这一点的重要性超乎想象，因为仅事后记录的日志只能说明某件事发生了，却无法表明其事先已获得批准。
哪些内容未被框架记录
在五个框架中，十二个字段中有四个完全缺失，即便计入相关规范要求，仍有两个字段不存在。
trust_level在六个代码库的任何文件中都未出现。没有这一字段，就无法记录智能体执行操作的授权依据，因此也无法区分允许的操作与被禁止的操作。
prev_hash 未出现在任何文件中，previous_hash 和 hash_chain 也是如此。没有机制将记录串联起来，而追踪存储只是普通的数据库，其行内容可以被修改。agent_version。它仅存在于 OpenInference 中，作为 OpenTelemetry 的 gen_ai.agent.version 的对应项，虽然可以设置，但从现有情况来看，这些框架本身几乎从未设置过它。outcome 未能在任何框架中获得满分。所有框架都有错误字段，但却没有哪个框架能将“被拒绝”与“失败”区分开来，而这种区分正是审计人员最看重的。对 non_repudiation 和 pre_execution 的搜索同样没有找到任何文件。
为何这些字段缺失
这些工具原本是为另一个问题设计的。追踪信息有助于工程师找出某事物运行缓慢或出错的原因，而input、output、duration以及父节点指针几乎已足够实现这一目的。但这些证据必须能够抵御包括日志控制者在内的任何对手的质疑，而现有系统并非为应对此类威胁而构建的。这些缺失并非疏忽——直到今年之前，没人期望追踪信息还能充当证据。
最有力的反论
OpenTelemetry能否填补这一空白？部分可以。OpenInference涵盖了12个指标中的8个，也是其中表现最好的，而OpenTelemetry的GenAI规范定义了gen_ai.agent.id和gen_ai.agent.version，从理论上讲可以解决身份识别方面的问题。如果能够一致应用，仅靠采用这些工具就能解决12个指标中的4个，无需额外工作。
然而，两个最棘手的要求仍未解决。防篡改标记无法作为属性添加到某个元素中，因为它属于存储系统而非具体记录。哈希链只有在其被写入且无法被修改的位置时才有意义。而 record_phase 需要在操作执行之前先生成记录，这属于关于时序的架构设计选择，而非事后添加的字段。这两者均不符合语义规范。
测量的局限性
只有当相关数据的边界是可信的时，数字才有用，因此这些注意事项至关重要：
- 这属于静态分析，而非运行时捕获。仅统计了类所定义的字段。有六个代理程序并未运行并对比其生成的负载数据，而且某个框架可能会通过未被追踪的扩展机制来填充某些字段。
metadata、tags和extra属于应急替代方案，因此被判定为不存在。大多数框架都支持任意键名，因此有决心的团队可以在extra中存储哈希链。该统计数值反映的是默认情况，而非上限。message_content.signature，但其文档说明指出该值是按接收原样存储的、由供应商提供的不可见数据，类似于Gemini的thoughtSignature。它用于验证模型的推理内容而非记录的完整性，且只有数据提供方才能对其进行检查。故意将其视为不存在，正是为了作为防篡改的依据。trust_level的值提出异议。如果需求列表发生变化，覆盖率数值也会随之改变。timestamp都被视为符合要求，但实际上，一个没有时区信息或缺乏参照基准的普通datetime.now()，其可靠性远低于符合RFC 3161标准的时间戳。这种方法无法判断这些因素对特定系统而言是否重要。对于那些负责阅读文档并撰写文本的智能体来说，调试追踪功能已经足够，而审计级别的记录则显得过于冗余。只有当智能体的行为可能带来日后有人会质疑的后果时，这种差异才会造成问题。
按收益顺序排列的三个变更
- 在执行前记录日志。也就是说要在调用之前而非之后进行记录，需注明记录ID、时间戳、代理ID和版本、即将执行的操作以及其背后的权限。CrewAI的启动/结束分割结构可作为模板，其他系统则需要手动构建类似结构。
- 将记录链接到只读追加存储中。使用SHA-256对前一条记录进行哈希处理几乎不需要成本。重要的是记录的存储位置，而非哈希值本身。
- 为
outcome定义词汇表。通过设置五种值（成功、失败、超时、被拒绝、升级处理），可以将工具错误与拒绝情况区分开来，并便于查询，而不会仅以字符串形式存在。
无需新的框架，只需在现有框架基础上增加大约两百行代码即可。它反映了监控面板所忽略的“静默代理故障”模式——由于没有记录，这种缺失会被误认为是正常状态。
快速解答
代理追踪与审计日志有何不同？追踪记录是为那些希望事后解释行为情况的工程师准备的，其前提是记录者会如实记录。而审计日志则是为存在争议的各方准备的，必须明确记录者的身份、权限及诚信度，即谁进行了操作、拥有何种权限以及该记录此后是否被修改过。相比之下，这些框架每个包含6到25个追踪字段，但仅满足5项审计要求的中位数水平。
能否让 LangChain 的追踪记录具备审计准备状态？只能部分实现，且需要通过构建框架而非仅进行配置来完成。LangSmith 的 RunTree 直接提供了 12 个字段中的 6 个，包括 session_id 和 parent_run_id。仍需补充的内容包括智能体的身份、运行的版本、固定的一组结果值、信任等级、执行前写入的记录，以及存储在只读追加存储中的哈希链。自定义数据可以放在 extra 字段中，但该字段不会自动被填充。
OpenTelemetry 能解决这个问题吗？它能处理身份识别相关的问题。至于防篡改证据和执行前记录的功能则仍有待完善，因为这些功能依赖于记录的写入时间和位置，而非 span 所包含的属性。
目前哪种框架最便于审计？LangChain通过LangSmith在12项功能中覆盖了6项，而CrewAI则独特地提供了真实的执行前记录以及一流的agent_id。不过二者目前都尚未达到可直接用于审计的程度。如果审计性是不可或缺的要求，那就需要单独构建证据层，并将框架的追踪信息视为原始输入。
对于内部工具而言，哈希链是否过于复杂？通常来说是的。关键判断标准在于是否有团队之外的其他人可能依赖这些日志，比如客户、交易对手、保险公司，或是涉及重大利益的事件审查人员。如果没有，普通的追踪信息就足够了；如果有，现在添加哈希链的成本远低于日后重新构建它。
关于代理监控的争论已持续数月。通过计数可以解决部分问题，因为字段名要么属于该类，要么不属于。
相关阅读
- 当控制面板显示正常而代理的追踪有误时：状态追踪：代理故障如何隐藏在正常步骤之间传递的状态中，以及需要通过何种追踪、运行时约束、路由记录和评估来发现这些问题。
- 实用笔记：编写代理程序——破解代理循环：针对采用该模式的团队，提供了关于合同定义、检查机制以及可直接插入的代码片段的详细操作指南。