AI Agent日志系统设计与实践：从黑盒记录到数据洞察

1. 为什么你的多技能 Agent 需要黑盒记录仪？

作为一位长期奋战在 AI 应用开发一线的工程师，我见过太多团队在 Agent 开发过程中陷入"盲人摸象"的困境。当你的 Agent 开始具备多项技能后，你会发现一个残酷的现实：你根本不知道用户实际是怎么使用它的。

上周我接手了一个内部客服 Agent 的优化项目。这个 Agent 已经接入了 7 个技能模块，包括 FAQ 查询、工单生成、排班咨询等。产品经理信誓旦旦地说："用户最需要的是排班功能，我们应该优先优化这个模块。"但当我们加上日志系统运行一周后，数据却显示：排班功能的使用率只有 3%，而 78% 的请求都集中在 FAQ 查询上。

这就是为什么我们需要给 Agent 装上"黑盒记录仪"——就像飞机上的黑匣子一样，它能忠实记录 Agent 的每一次"飞行"细节。没有这些数据，我们就像在黑暗中摸索，所有的优化决策都只能靠猜测。

2. 日志系统设计思路：轻量但够用

2.1 核心设计原则

在设计日志系统时，我遵循了三个核心原则：

1. 非侵入式：不改动现有业务逻辑，只在最外层加"埋点"
2. 结构化：记录的数据要方便后续分析
3. 轻量级：不引入复杂依赖，用 Python 标准库就能实现

2.2 日志字段设计

经过多次迭代，我确定了以下必录字段：

python复制{
    "time": "2024-03-15T09:30:00Z",  # ISO 8601 格式时间戳
    "question": "年假怎么计算？",     # 用户原始问题
    "skill": "faq_rag",             # 调用的技能ID
    "duration_ms": 845,             # 处理耗时(毫秒)
    "tokens": 142,                  # Token 估算值
    "success": True,                # 是否成功
    "answer_length": 56             # 回答长度(字符数)
}

这些字段的选取经过了深思熟虑：

• duration_ms 和 tokens 用于性能监控和成本估算
• skill 和 success 用于使用模式分析
• answer_length 可以间接反映回答质量

提示：在实际项目中，你可能还需要记录用户ID、会话ID等字段，但本文为简化示例暂不包含这些信息。

3. 实现细节：代码级解析

3.1 日志初始化

python复制import os
import json
import logging
from datetime import datetime

LOG_DIR = "logs"
os.makedirs(LOG_DIR, exist_ok=True)

LOG_FILE = os.path.join(LOG_DIR, "agent_log.jsonl")

logging.basicConfig(
    level=logging.INFO,
    format='%(message)s',  # 禁用默认格式，我们自己构造JSON
    handlers=[
        logging.Fil