可观测性差距：为何你无法调试看不见的 AI 代理系统

Source: Dev.to

请提供您希望翻译的完整文本（除代码块、URL 之外的内容），我将按照要求把它翻译成简体中文并保留原有的 Markdown 格式。谢谢！

可观测性缺口

当你的 AI 代理给出错误答案时，你会去哪里查找？
大多数人会检查提示词、工具或模型版本。
真正的罪魁祸首通常是看不见的：缺少可观测性层。
你不知道是哪一次对话导致了漂移，哪一次工具调用花费了 $0.40，或者代理是否读取了正确的文件版本。
你只知道输出是错误的。

这就是 可观测性缺口，也是大多数 AI‑agent 项目慢慢夭折的地方。

对于传统软件，可观测性意味着日志、指标和追踪。
对于 AI 代理，它意味着三件事：

1. 代理在每一步知道了什么？（上下文状态）
2. 它决定做什么？（动作日志）
3. 每个决策花费了多少？（每个动作的 token/API 成本）

没有这三项，你就像盲人一样飞行——无法改进你无法衡量的东西。

必需文件

current-task.json – 状态快照

在每个回合前写入当前状态：

{
  "task": "draft weekly newsletter",
  "step": "gathering_sources",
  "started": "2026-03-08T09:00:00Z",
  "last_updated": "2026-03-08T09:04:12Z",
  "sources_found": 3,
  "target_sources": 5
}

现在你可以准确知道代理出错时所在的位置。

action-log.jsonl – 决策追踪

为每个操作追加一行（JSON Lines 格式）：

{"ts":"2026-03-08T09:04:13Z","action":"web_search","query":"AI agent patterns 2026","result_count":8,"tokens":420,"cost_usd":0.003}
{"ts":"2026-03-08T09:04:28Z","action":"read_file","path":"memory/2026-03-07.md","tokens":1200,"cost_usd":0.008}

你可以看到精确的决策序列，回放它，并找出成本激增的地方。

memory/YYYY-MM-DD.md – 会话日志

对会话期间发生的事情进行人类可读的叙述。
它是散文而非结构化数据，对跨天的模式识别很有帮助。

调试工作流程

当出现问题时：

1. 读取 current-task.json – 代理当时处于什么状态？
2. 在 action-log.jsonl 中搜索相关的时间窗口 – 它执行了哪些操作？
3. 读取 memory/YYYY-MM-DD.md – 代理认为当时发生了什么？

三次快速阅读能为你提供的洞察，往往超过大多数团队数小时调试后得到的了解。

成本透明度

动作日志快速揭示成本模式：

• 一个“廉价”的网页搜索可能在每个循环中运行 12 次。
• 一个安全文件读取可能在每回合加载一个 4,000 令牌的文档，而实际只需要 40 令牌。
• 用于简单分类的推理模型每次调用可能花费 $0.15，每天 200 次调用。

一个团队在添加动作日志后，将 API 成本从 $180 / month 降至 $47 / month——没有更改任何代理逻辑，仅仅是通过观察实际行为实现的。

让它奏效的简单规则

在每个动作之前写入状态。
在每回合开始时读取状态——而不是在之后。如果代理在动作进行中崩溃，你仍然有它的意图记录。

好处

• 崩溃恢复 – 从最后已知状态恢复。
• 漂移检测 – 随时间比较预期状态与实际状态。
• 成本归属 – 将成本关联到具体任务。
• 可审计性 – 证明发生了什么以及原因。

最小化代理循环与可观测性

import json, datetime

def agent_turn(task_state, action):
    # 1. Write state BEFORE acting
    task_state['last_updated'] = datetime.datetime.utcnow().isoformat()
    task_state['current_action'] = action['name']
    with open('current-task.json', 'w') as f:
        json.dump(task_state, f)

    # 2. Execute action
    result = execute(action)

    # 3. Log the action
    log_entry = {
        'ts': datetime.datetime.utcnow().isoformat(),
        'action': action['name'],
        'tokens': result.get('tokens_used', 0),
        'cost_usd': result.get('cost', 0)
    }
    with open('action-log.jsonl', 'a') as f:
        f.write(json.dumps(log_entry) + '\n')

    return result

十五行代码。完整的可观测性。

生产清单

1. 向您的代理循环添加 current-task.json 写入（≈30 分钟）。
2. 添加 JSONL 行动日志记录（≈1 小时）。
3. 运行 24 小时并审查日志。

您很可能会发现至少一个意外：一个出乎意料频繁的操作、成本激增，或解释长期存在的错误的模式。

结论

你无法改进看不见的东西。通过为你的 AI 代理添加简单的状态快照、操作日志和会话叙述，你获得了调试、优化和审计系统所需的可视性。

Further Resources

完整的可观测性模式——包括文件模板、日志分析脚本和成本仪表板——可在 Ask Patrick Library 获得，地址为 。它每周更新，提供新的代理操作模式。