跳转到内容
Telemetry
结构化事件 SQL查询示例

查询嵌套 AI 工具调用事件

过滤点嵌套字段并对失败的工具进行排名,而无需展平原始事件负载。

中级agent_events已审核 2026-07-27测试用 阿帕奇 DataFusion 45.2.0

审阅者 Telemetry产品团队 . SQL 兼容性、事件契约、合成输出和操作注意事项. 审查标准和所有权

问题已回答

哪些人工智能工具和参数与失败次数最多的调用相关?

结构化智能体事件通常带有嵌套的工具上下文。 Telemetry 将嵌套值公开为稳定的点列,这使 SQL 保持可读性,同时保留摄取时的自然事件形状。

活动合约

查询期望的字段

字段类型为什么存在
timestamp_utcTimestamp当工具调用完成时。
event_nameUtf8agent_tool_called 用于这些事件。
data.tool_nameUtf8嵌套工具标识符显示为虚线列。
data.statusUtf8嵌套成功或失败状态。
data.args.operationUtf8安全、分类的操作而不是原始参数。
data.latency_msFloat64嵌套工具调用延迟。
DataFusion SQL

复制查询

sql
SELECT
  "data.tool_name" AS tool_name,
  "data.args.operation" AS operation,
  COUNT(*) AS calls,
  SUM(CASE
    WHEN "data.status" = 'failed' THEN 1 ELSE 0
  END) AS failures,
  100.0 * SUM(CASE
    WHEN "data.status" = 'failed' THEN 1 ELSE 0
  END) / NULLIF(COUNT(*), 0) AS failure_rate_pct,
  approx_percentile_cont("data.latency_ms", 0.95) AS p95_latency_ms
FROM agent_events
WHERE event_name = 'agent_tool_called'
  AND timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY "data.tool_name", "data.args.operation"
HAVING COUNT(*) >= 20
ORDER BY failure_rate_pct DESC, calls DESC;

此只读查询是针对空类型表计划和执行的 阿帕奇 DataFusion 45.2.0。确定性样本输出是综合的并单独审查;根据您自己的数据验证字段类型、阈值和业务定义。 阅读测试方法。

查询结果

工具调用失败率

CRM 查找是最不可靠的工具操作,而且在 p95 上也是最慢的。

tool_nameoperationcallsfailuresfailure_rate_pctp95_latency_ms
crm_lookupsearch_contact842617.242,180
order_apifetch_order2,210441.99940
knowledge_searchsemantic_search4,510190.42720

综合示例输出。在将其用于操作决策之前,针对您自己的事件架构和阈值运行查询。

Tool-call failure rate:来自 Query Nested AI Tool-Call Events 示例结果的合成 failure_rate_pct 值的静态图表
确定性示例输出的可索引 SVG。下载它以获取带有归属的文章、操作手册或设计评论。

重现示例

下载公共装置

JSON 包包含类型化事件契约, illustrative 输入行、确切的 SQL、预期输出、审阅注释和引擎版本。 CSV 包含显示的结果。

SQL 是如何工作的

  1. 1点式字段名称用双引号引起来,因为点是推断的列名称的一部分。
  2. 2查询按工具和分类操作进行分组,保留足够的上下文来区分一种工具的不同行为。
  3. 3默认情况下不应记录原始工具参数。而是存储安全类别、标识符和结果字段。

需要决定的边缘情况

  • 随着架构的发展,保持嵌套字段类型稳定。
  • 不同的工具可能有不同的成功语义;在检测时标准化状态值。
  • 高基数原始参数可能会产生隐私、成本和可用性问题。

推荐仪表板

  • 条形图:failure_rate_pct by tool_name
  • 折线图:p95_latency_ms 随着时间的推移按工具划分
  • 表:error_type 和智能体工作流程的最近故障

警报指导

当生产工具的故障率在有意义的数量上超过其阈值时发出警报,并将警报路由到所属集成。

读取警报设置

让查询示例发挥作用

相关埋点和指南

定义源数据

此分析的事件模式

继续分析

在真实事件中运行它

创建表,调整字段并保存结果

免费开始,发送结构化事件,并将查询结果用作图表、共享仪表板小部件或警报输入。

获取 API 密钥