监控和调试 Agent SDK 代理——让你的代理行为可观测。
为什么需要可观测性
代理应用比传统应用更难调试，因为：
- AI 的决策过程不透明
- 工具调用链路复杂
- 上下文窗口管理困难
- 性能和成本难以追踪
日志记录
import logging
import json
from datetime import datetime
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("claude-agent")
def log_interaction(messages, response, cost):
"""记录每次代理交互。"""
entry = {
"timestamp": datetime.now().isoformat(),
"messages": len(messages),
"response_tokens": response.usage.output_tokens,
"input_tokens": response.usage.input_tokens,
"cost": cost,
"model": response.model
}
logger.info(json.dumps(entry))
# 保存到文件
with open("agent-log.jsonl", "a") as f:
f.write(json.dumps(entry) + "\n")追踪工具调用
class ToolTracer:
def __init__(self):
self.traces = []
def trace_tool_call(self, name, input_data, result, duration):
self.traces.append({
"tool": name,
"input": str(input_data)[:100],
"result_size": len(str(result)),
"duration_ms": duration,
"timestamp": datetime.now().isoformat()
})
def get_summary(self):
"""获取工具使用摘要。"""
from collections import Counter
counts = Counter(t["tool"] for t in self.traces)
return dict(counts.most_common())集成可观测性平台
可以集成第三方可观测性服务：
- LangSmith：追踪和评估 LLM 应用
- OpenTelemetry：标准追踪框架
- PromptLayer：提示词管理和分析