智能体日志与执行轨迹

观测对象

日志领域同时记录：

对象	记录内容
Conversation Trace	一次会话运行的 trace、run、状态和时间线
Node execution	LangGraph 节点开始、结束、耗时、输入摘要和错误
LLM call	模型、供应商、请求/响应摘要、token、耗时和异常
Tool execution	工具 ID、参数摘要、结果、超时和权限错误
RAG execution	查询、检索器、候选数量、质量评估和修正循环
Streaming content	已经推送给客户端的增量内容和结束原因

采集方式

logging 包使用 AOP、LangChain4j listener、节点装饰器和 Spring 事件：

• ConversationLogAspect 包装带日志注解的服务方法。
• TrackedNodeAction 包装 LangGraph 节点动作。
• SmartLlmCallListener、SmartToolExecutionListener、SmartContentRetrieverListener 和 SmartEmbeddingModelListener 监听 AI 组件。
• RealtimeLogPersistenceListener 将事件写入持久化层。
• LoggingStreamingResponseHandler 和 StreamingContentLoggingListener 记录流式结果。

查询入口

ConversationLogController 的基础路径为 /v1/logs，支持按 session、trace 查询，分页查询调用明细、查看 Agent 统计和工具调用。轨迹控制器提供更细粒度的执行进度和事件分页。

脱敏与成本

日志应优先保存元数据和内容摘要；密钥、完整授权头和不必要的原始文件内容不能写入日志。模型调用量和 token 统计可用于计费与限流，新增模型或工具时要补齐 executor type 和计量字段。