📚 编程进阶教程站

第 23 章 · 可观测性与调试 ​

本章目标：学会用 metrics 读懂每次运行的 token 与耗时账单，用 debug_mode 排查工具调用链，并用 OpenTelemetry 追踪搭建生产级监控。

23.1 Metrics：每次运行的账单 ​

RunOutput.metrics 记录本次运行的 token 用量、成本、耗时和按模型的分解。它回答的是"这次调用花了多少钱、慢在哪"：

python
import os
from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    model=OpenAIChat(
        id="deepseek-chat",
        api_key=os.getenv("DEEPSEEK_API_KEY"),
        base_url="https://api.deepseek.com/v1",
    ),
    markdown=True,
)

response = agent.run("用三句话解释什么是向量检索")

m = response.metrics
print("输入 token:", m.input_tokens)
print("输出 token:", m.output_tokens)
print("总 token:", m.total_tokens)
print("耗时:", m.duration)

Agent、Team、Workflow 三层都有 metrics：Team 会细分到成员级，Workflow 细分到步骤级——这正是定位"哪个环节最烧钱/最慢"的依据。

23.2 Debug Mode：看清执行流程 ​

调试的核心诉求是三件事：发给模型了什么消息、模型回了什么、工具调用链长什么样。debug_mode 一次给全：

python
agent = Agent(
    model=model,
    tools=[DuckDuckGoTools()],
    instructions="写一份关于主题的报告，只输出报告本身。",
    markdown=True,
    debug_mode=True,     # 打印模型请求/响应、工具调用与结果、中间步骤
    # debug_level=2,     # 需要更详细日志时打开
)

agent.print_response("Trending startups and products.")

三种开启方式，作用域从小到大：

  1. agent.run(..., debug_mode=True)——单次运行；
  2. Agent(debug_mode=True)——该 Agent 的所有运行；
  3. 环境变量 AGNO_DEBUG=True——全局开启。

排查工具调用链时，debug 日志会按顺序展示：模型决定调用哪个工具 → 工具入参 → 工具返回 → 结果如何进入下一轮模型请求。绝大多数"工具没生效"的问题都出在第二、三环（入参不符合预期、返回内容太长被截断）。

23.3 交互式 CLI：多轮对话快速验证 ​

调试多轮行为（记忆、历史注入）时反复写脚本很痛苦，Agno 内置了 CLI 应用模式：

python
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=model,
    db=SqliteDb(db_file="tmp/debug.db"),
    add_history_to_context=True,
    num_history_runs=3,
    markdown=True,
)

agent.cli_app(stream=True)   # 在终端里以交互式多轮对话运行

23.4 生产追踪：OpenTelemetry 与 AgentOS Tracing ​

debug 日志适合开发期，生产期需要的是结构化追踪。AgentOS 内置基于 OpenTelemetry 的追踪，开启一个开关即可：

python
from agno.os import AgentOS

agent_os = AgentOS(
    agents=[agent],
    db=db,            # 追踪数据写入该数据库
    tracing=True,     # 为 agent/team/workflow 运行插桩
)

开启后每次运行会产生：

  • span：模型调用、工具执行、Team 协调、Workflow 步骤各一个，含父子关系、状态、时间戳、时长和 attributes JSON，写入 agno_spans 表；
  • trace：一次运行的聚合记录（run/session/user/component ID、起止时间、总时长），写入 agno_traces 表。

追踪遵循 OpenInference 语义规范，可以直接用 SQL 分析：

sql
-- 最慢的 10 类 span
SELECT name, AVG(duration_ms) AS avg_ms, COUNT(*) AS calls
FROM ai.agno_spans
GROUP BY name
ORDER BY avg_ms DESC
LIMIT 10;

追踪库要独立

追踪数据写入频繁、量大，与业务会话数据的访问模式完全不同。官方建议给 AgentOS 的 db 单独指一个专用追踪数据库，把追踪写入量与会话数据隔离，各自设置保留策略。

同样的 trace 树也会渲染在 Agno Control Plane（os.agno.com）中：点开一次运行可以看到完整的 LLM 跳数、带输入输出的工具调用和子 Agent 追踪，并按用户/会话/时间过滤。

23.5 设计你的生产监控指标 ​

结合 Agno 提供的三层数据，一套实用的监控基线是：

维度指标来源
成本每会话/每用户 total_tokens、按模型分解metrics
延迟P50/P95 运行时长、步骤级耗时metrics + agno_spans
质量工具调用失败率、重试次数spans + debug 日志
行为会话长度分布、成员委派频率traces + sessions

隐私提醒

trace 的 attributes 里可能包含提示词、工具参数和模型输出。对追踪数据要套用与业务敏感数据相同的访问控制和保留策略，不要把生产追踪库当成无权限的日志库。

23.6 本章小结 ​

  • RunOutput.metrics 提供 token/成本/耗时/模型分解，Team 与 Workflow 还有成员级、步骤级细分；
  • debug_mode 三个作用域（单次运行/Agent/全局环境变量）+ debug_level=2 是排查工具链的利器；
  • cli_app() 适合快速验证多轮会话行为；
  • 生产追踪 = AgentOS(tracing=True) + 专用追踪库，span 落在 agno_spans、聚合在 agno_traces，遵循 OpenInference 可直接 SQL 分析；
  • 监控基线覆盖成本、延迟、质量、行为四个维度。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 想临时查看某一次运行的模型请求与工具调用细节，最轻量的方式是？

2. AgentOS 开启 tracing 后，单个 span（如一次模型调用）存储在？

3. 生产环境给追踪数据配置独立数据库的主要原因是？

4. 关于 trace 数据中的 attributes 字段，正确的态度是？

🛠️ 动手实践 ​

  1. 对同一个带工具的 Agent 分别关闭/开启 debug_mode 跑一次搜索任务，把工具调用链日志整理成时序表。
  2. 用 SQL（或 SQLite 命令行）查询本地 agno_spans 表，找出你最慢的 span 类型并分析原因。
  3. 为你的 Agent 设计并记录"单次会话 token 预算"，用 metrics.total_tokens 写一个小脚本统计超预算的会话。

最后一章：把前面所有能力拧成一股绳——性能优化与生产实践。