Agent Lens

追踪每一次 AI API 调用，分析 Token 使用量，并优化成本。

适用场景

当用户出现以下情况时，启用该能力：

• 提到“我花了多少钱”、“Token 使用量”、“API 成本”
• 想了解哪个模型最昂贵
• 需要优化 Prompt 成本
• 希望追踪 API 调用延迟或错误率
• 提及“预算”、“成本优化”或“Token 统计”
• 提问“为什么我的 API 账单这么高”

快速开始

# 安装
pip install git+https://github.com/lrg913427-dot/agent-lens.git

# 生成演示数据并立即查看效果
agent-lens demo

# 查看统计信息
agent-lens stats
agent-lens cost
agent-lens recent

三种追踪方式

1. 装饰器（最简单）

from agent_lens import AgentLens

lens = AgentLens(agent_name="my-agent")

@lens.track(model="gpt-4o")
def call_api(prompt):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )

# Token 使用量会自动从 OpenAI 风格的响应中提取
result = call_api("Hello")

2. 上下文管理器（灵活）

from agent_lens import AgentLens

lens = AgentLens(agent_name="my-agent")

with lens.trace(model="claude-3.5-sonnet") as t:
    result = client.chat.completions.create(...)
    t.input_tokens = result.usage.prompt_tokens
    t.output_tokens = result.usage.completion_tokens

3. 直接记录（手动）

from agent_lens import AgentLens

lens = AgentLens(agent_name="my-agent")
lens.record(
    model="gpt-4o",
    input_tokens=1500,
    output_tokens=800,
    latency_ms=2300,
)

全局快捷方式

from agent_lens import record, trace, track

record(model="gpt-4o", input_tokens=100, output_tokens=50)

with trace(model="gpt-4o") as t:
    ...

@track(model="gpt-4o")
def my_func():
    ...

CLI 命令

成本优化工作流

当用户询问“我该如何省钱”时：

1. 运行成本报告：agent-lens cost
2. 识别高成本模型：哪些模型花费最多？
3. 检查 Token 利用效率：Prompt 是否过长？
4. 推荐更经济的替代方案：
   • gpt-4o → gpt-4o-mini（便宜 10 倍）
   • claude-3.5-sonnet → claude-3.5-haiku（便宜 4 倍）
   • gpt-4 → gpt-4o（便宜 2 倍）
5. 检查缓存使用：是否存在重复的 Prompt？
6. 检查错误率：agent-lens report --by status

Token 统计

import tiktoken

def count_tokens(text: str, model: str = "gpt-4o") -> int:
    """统计指定模型下的 Token 数量。"""
    try:
        enc = tiktoken.encoding_for_model(model)
    except KeyError:
        enc = tiktoken.get_encoding("cl100k_base")
    return len(enc.encode(text))

# 发送前校验
prompt = "Your long prompt here..."
tokens = count_tokens(prompt)
print(f"Prompt: {tokens} tokens")
print(f"Estimated cost: ${tokens * 2.50 / 1_000_000:.4f}")

支持的模型

已内置定价数据的模型：OpenAI（GPT-4o、o1、o3）、Anthropic（Claude 3.5/4）、Google（Gemini 2.x）、DeepSeek、Mistral、Qwen、GLM、MiMo。

未知模型仍可被追踪，但成本显示为“—”。

与 Hermes 的集成

# 追踪 Hermes Agent 的 API 调用
from agent_lens import AgentLens

lens = AgentLens(agent_name="hermes-main")

# 在你的 Agent 循环中：
with lens.trace(model=config.model) as t:
    response = agent.run_conversation(message)
    t.input_tokens = response.get("input_tokens", 0)
    t.output_tokens = response.get("output_tokens", 0)

数据存储

使用 SQLite 存储于 ~/.agent-lens/traces.db。完全本地化，无需任何云服务。

常见陷阱

• Token 自动提取仅适用于 OpenAI 兼容格式的响应
• 对于非 OpenAI 提供商，需手动设置 t.input_tokens 和 t.output_tokens
• 成本估算基于官方标价；实际费用可能因折扣而不同
• 数据库随时间增长；建议定期执行 agent-lens clean

验证步骤

agent-lens demo        # 生成 20 条示例记录
agent-lens stats       # 应显示共 20 次调用
agent-lens cost        # 应显示按模型划分的成本分布