HelloAgents 可观测性指南TraceLogger 追踪系统如何透视 Agent 每一步决策【免费下载链接】HelloAgentsA agent framework based on the tutorial hello-agents项目地址: https://gitcode.com/gh_mirrors/he/HelloAgentsHelloAgents是一款生产级多智能体框架其内置的TraceLogger可观测性模块能自动记录 Agent 的每一步决策——从 LLM 请求到工具调用、从 Token 消耗到错误发生全部以 JSONL HTML 双格式实时落盘让你无需改一行业务代码就能完整复盘智能体的执行轨迹。为什么 Agent 需要可观测性Agent 的本质是一个不断循环的决策系统思考 → 调工具 → 观察结果 → 再思考。当它表现不佳时你面对的往往只有一句模糊的失败回复而真正的线索藏在中间过程里 它第几步开始跑偏️ 哪个工具连续失败、触发了熔断 一次会话到底烧掉了多少 Token 和成本没有追踪数据这些问题只能靠猜。TraceLogger源码位于 hello_agents/observability/trace_logger.py就是 HelloAgents 给出的答案为每次会话生成带唯一 ID 的完整审计轨迹性能开销小于 1%。TraceLogger 双格式输出机器能查人类能看TraceLogger 最巧妙的设计是一份事件流两种呈现格式文件特点适用场景JSONLtrace-{session_id}.jsonl每行一个事件、流式追加、可用jq过滤自动化分析、日志聚合、CI 流水线HTMLtrace-{session_id}.html可视化审计界面、内置统计面板、事件可折叠浏览器直接打开问题排查、可视化复盘两种文件都实时增量写入——会话还在跑你刷新浏览器就能看到最新的事件时间线不必等待结束。每次会话的 ID 采用s-YYYYMMDD-HHMMSS-xxxx格式如s-20250118-143052-a3f2时间戳即会话开始时间天然支持按时间排序归档。内置统计面板一眼看穿成本与性能会话结束时HTML 文件尾部会自动渲染统计面板总步骤数与会话时长总 Token 消耗与总成本美元工具调用统计表每个工具被调用了多少次❌错误列表哪一步、什么类型、什么信息自动脱敏敏感信息不落盘生产环境最怕把 API Key 写进日志。TraceLogger 默认开启脱敏sanitizeTrue用正则递归替换事件中的所有敏感内容sk-1234567890abcdef → sk-*** Bearer token123 → Bearer *** /Users/john/projects/ → /Users/***/projects/脱敏对字典、列表、字符串递归生效无需你手动清理任何字段。三步开启 Trace 追踪第一步零配置自动集成默认已开启HelloAgents 的基类 Agent 在构造时会自动创建 TraceLogger见 hello_agents/core/agent.py而 hello_agents/core/config.py 中所有追踪配置默认开启from hello_agents import ReActAgent, HelloAgentsLLM, Config config Config( trace_enabledTrue, # 默认 True trace_dirmemory/traces, # 输出目录 trace_sanitizeTrue, # 自动脱敏 trace_html_include_raw_responseFalse # HTML 是否含原始响应 ) agent ReActAgent(assistant, HelloAgentsLLM(), configconfig) agent.run(分析项目结构并生成报告)运行结束后memory/traces/目录下会自动生成一对trace-xxx.jsonltrace-xxx.html文件。第二步独立使用 TraceLogger不经过 Agent任何 Python 代码也能手动记录事件流且支持with上下文管理器——异常发生时会自动记录错误事件并完成收尾from hello_agents.observability import TraceLogger logger TraceLogger(output_dirmemory/traces) logger.log_event(session_start, {agent_name: MyAgent}) logger.log_event(tool_call, {tool_name: Calculator}, step1) logger.finalize() # 生成统计面板与最终 HTML完整的独立使用演示可参考 examples/observability_demo.py涵盖事件记录、脱敏验证、错误追踪和统计四个场景。第三步查看与筛选 TraceJSONL 文件配合jq就是最轻量的分析工具# 过滤所有工具调用事件 cat memory/traces/trace-xxx.jsonl | jq select(.eventtool_call)HTML 文件直接用浏览器打开事件按类型着色工具调用/结果/错误/模型输出各有标识色点击即可展开完整 payload。ReAct 循环中的事件流每一步都被记录TraceLogger 与 ReAct Agent 的深度集成在 hello_agents/agents/react_agent.py 中完成——主循环的每个关键节点都会写入事件事件类型记录时机关键字段message_written收到用户输入role, contentmodel_output每次 LLM 响应content, tool_calls, usageTokentool_call模型发起工具调用tool_name, argstool_result工具执行完毕status, resulterrorLLM 调用或工具异常error_type, messagesession_end会话结束duration, statussuccess/timeout每个事件都遵循统一结构并携带 ReAct 循环的步骤序号step方便按步骤对齐{ ts: 2026-02-21T10:30:45.123Z, session_id: s-20250220-a3f2d8e1, step: 3, event: tool_call, payload: { tool_name: Read, args: { path: config.py } } }实战复盘Trace 数据能回答哪些问题场景一问题排查— Agent 失败后打开 HTML 报告统计面板显示 3 个错误点开错误列表定位到某个工具连续失败再展开对应tool_result事件的详情即可看到错误码与根因。场景二成本分析— 用jq汇总model_output事件的usage.total_tokens即可精确核算单次会话的 Token 账单工具调用耗时同理可统计。场景三审计合规— 生产环境建议trace_html_include_raw_responseTrue保存完整 LLM 请求与响应配合脱敏满足审计要求详见 docs/observability-guide.md 中的最佳实践。常见问题 FAQQTraceLogger 会影响性能吗A影响极小 1%。JSONL 流式写入、HTML 增量渲染、脱敏只是正则替换均无阻塞。Q如何彻底关闭追踪AConfig(trace_enabledFalse)Agent 将不创建任何 TraceLogger 实例。QJSONL 和 HTML 有什么区别AJSONL 面向机器自动化分析、日志聚合HTML 面向人类浏览器可视化排查。二者同源同时生成按需取用。QTrace 文件会无限增长吗A建议定期清理例如保留 7 天find memory/traces -name trace-* -mtime 7 -delete相关文件导航文件说明hello_agents/observability/trace_logger.pyTraceLogger 核心实现双格式写入、脱敏、统计hello_agents/core/config.pytrace_*配置项定义hello_agents/agents/react_agent.pyReAct 主循环中的事件埋点docs/observability-guide.md官方可观测性指南examples/observability_demo.py四个可运行示例记录、脱敏、错误、统计tests/test_observability.pyTraceLogger 单元测试tests/test_trace_integration.pyTraceLogger 与 Agent 的端到端集成测试从只能看到最终答案到透视每一步决策TraceLogger 让 HelloAgents 的每次会话都变成一份可审计、可统计、可回放的完整档案——这正是生产级 Agent 框架的底座能力。【免费下载链接】HelloAgentsA agent framework based on the tutorial hello-agents项目地址: https://gitcode.com/gh_mirrors/he/HelloAgents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
