SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-observability

agent-observability

部署与运维

查看项目

更新于 10-15 14:41

技能介绍

用途

Agent Observability 用于监控 AI 智能体的运行行为，通过日志、追踪、指标和成本遥测构建完整的可观测性栈。它面向 LLM 驱动的应用，从原始 Prometheus 计数器到 Grafana 仪表盘、OpenTelemetry 追踪、结构化日志、成本跟踪、SLO 定义和 PII 脱敏。

适用场景

当你在运行以下系统时，可以应用该技能：

  • 执行多步工具调用的自主 AI 智能体（如编码智能体、客服智能体、数据管道智能体）。
  • 在 REST 或 gRPC 网关后提供聊天补全、摘要或分类服务的 LLM 后端 API。
  • RAG 管道：检索器先从向量存储获取上下文，再提示模型。
  • 多智能体编排（crew 风格或基于图），多个智能体协作完成单一任务。
  • 批量推理任务：针对模型端点处理数千条提示。

需要该技能的关键信号：

  • 无法回答“本周智能体响应的 p95 延迟是多少？”
  • 没有按请求的成本归因。
  • 调试一次糟糕的智能体响应需要 grep 原始应用日志。
  • 没有针对 Token 用量激增或错误率上升的告警。

主要能力

核心指标

在应用层定义以下指标，示例使用 Prometheus 客户端库命名约定。

延迟：使用 Histogram 记录完整智能体回合的端到端延迟（agent_request_duration_seconds）、单次 LLM API 调用延迟（llm_call_duration_seconds）以及智能体执行的工具调用延迟（agent_tool_call_duration_seconds），均带标签区分模型、提供方、状态等。

Token 用量：使用 Counter 记录发送给模型的提示 Token 总数（llm_prompt_tokens_total）、从模型接收的补全 Token 总数（llm_completion_tokens_total）、由 KV 缓存提供的提示 Token（llm_cached_tokens_total），并用 Histogram 记录每请求总 Token 数（llm_tokens_per_request）。

成本：使用 Counter 记录 LLM 用量的估算美元成本（llm_cost_dollars_total），标签区分模型、智能体名称和成本类型（prompt | completion）。

工具调用：使用 Counter 记录智能体发起的工具调用总数（agent_tool_calls_total），标签区分工具名、智能体名和状态（success | error | timeout）。

错误与重试：使用 Counter 记录 LLM 提供方返回的错误（llm_errors_total，error_type 可为 rate_limit | timeout | 5xx | auth）和重试的 LLM API 调用（llm_retries_total），并用 Gauge 记录当前进行中的智能体请求数（agent_active_requests）。

OpenTelemetry 集成

使用 OpenTelemetry Python SDK 创建追踪，捕获智能体回合的每一步：顶层请求、每次 LLM 调用、每次工具执行和检索操作。

  • 初始化：通过 TracerProvider、OTLPSpanExporter 和 BatchSpanProcessor 配置追踪，设置 service.name、service.version、deployment.environment 等资源属性。
  • 追踪 LLM 调用：用 traced_llm_call 包装补全调用，在 Span 中记录模型、提供方、消息数、温度、最大 Token 数，以及响应后的提示 Token、补全 Token、总 Token、耗时和结束原因，同时更新 Prometheus 计数器。
  • 追踪工具执行：用 traced_tool 装饰器包装工具函数，记录工具名、参数数量、耗时和状态，并更新工具调用指标。
  • 跨服务传播 trace 上下文：使用 inject 将 traceparent 和 tracestate 头注入下游 HTTP 请求，使用 extract 从传入请求头提取上下文。

结构化日志

为每个智能体动作输出 JSON 日志，便于 Loki、Elasticsearch 或 Datadog 采集。

  • 配置 AgentJSONFormatter，输出 timestamp、level、logger、message、module、function、line 等基础字段，并合并 trace_id、span_id、agent_name、model、tool_name、request_id、user_id、prompt_tokens、completion_tokens、cost_usd、duration_seconds、status、error_type 等额外字段。
  • 提供 log_llm_call 和 log_tool_call 函数，从当前 Span 获取 trace_id 和 span_id 并写入日志。
  • 示例日志输出包含时间戳、级别、trace_id、span_id、模型、Token 数、耗时、成本、状态和智能体名称。

Grafana 仪表盘

提供可直接导入 Grafana 的仪表盘 JSON（agent-overview.json），包含：

  • 请求延迟面板：展示 p50 / p95 / p99 分位数，单位为秒，带绿/黄/红阈值。
  • Token 用量面板：按模型展示提示与补全 Token 的速率。
  • 每小时成本面板：以美元/小时展示成本。

使用方式

该技能以代码示例和配置片段的形式提供，涵盖 Python 代码（Prometheus 客户端、OpenTelemetry SDK、日志配置）和 Grafana 仪表盘 JSON。开发者需要将这些代码集成到自己的 LLM 应用中，并部署 Prometheus、OpenTelemetry Collector、Grafana 等基础设施来采集和展示数据。

限制

资料中未提供关于收费、价格、平台支持范围、具体效果保证或完整安装步骤的信息。该技能依赖 Prometheus、OpenTelemetry、Grafana 等外部系统，实际部署需自行配置。