作者：来自 Elastic Meghan Murphy 及 Pablo Neves Machado
你的 Agent Builder agents 已经将每次 LLM 调用记录为 OTel traces，而这些 agent tracing 数据可以用于生成 token 成本仪表板和预算告警，从而避免一次失控的对话悄悄消耗掉你整个月的预算。
Agent Builder 现在已经正式发布。开始使用 Elastic Cloud 试用版，并查看 Agent Builder 的文档。
每一次 Elastic Agent Builder 对话都会生成完整的 OpenTelemetry trace。LLM 调用、工具执行、token 计数，默认都会记录到 Elasticsearch data streams 中，你可以使用 ES|QL 对其进行查询 。大多数团队通常会在出现问题之后才查看这些数据，这意味着他们错过了本可以更早发现的使用趋势、延迟 瓶颈和成本信号。本文将介绍如何在 Kibana 中构建 token 成本仪表板，如何设置当一次对话超过 256,000 个 token 时触发的告警，以及如何使用瀑布时间线准确查看 agent 在哪里花费了时间。
什么是 Agent Builder OTel trace，以及它记录了什么？
当你的 agent 运行时，Agent Builder 会将发生的一切记录为一个 OpenTelemetry (OTel) trace。你可以将 trace 理解为一次对话轮次的记录凭证。每一次 LLM 请求、工具调用和 agent 操作都会作为一个独立的 span 记录在 Elasticsearch 中，span 是一个工作单元或操作单元。启用后，额外的详细信息（例如用户提示词、LLM 响应、工具输出和对话 ID）会作为结构化 span 属性记录在聊天 span 中。所有这些数据都限定在你的 Kibana space 范围内。
如何在 Kibana 中启用 agent tracing 和隐私控制
要开始采集 trace 数据，请确保环境中的 Gen AI 设置下 Agent Traces 中的以下开关已启用：
agentBuilder:tracing:enabled--- 此 gen AI 设置用于管理 trace 的采集，默认已启用。
位于默认 trace 开关下方的高级隐私控制还允许你采集消息内容。虽然提示词和工具输出默认会被屏蔽，但你可以选择启用它们，以支持更完整的 trace：
-
agentBuilder:tracing:includeUserPrompts -
agentBuilder:tracing:includeLlmResponses -
agentBuilder:tracing:includeToolDetails -
agentBuilder:tracing:includeSystemPrompt -
agentBuilder:tracing:includeRealNames：保留真实的 agent/工具名称，而不是匿名化为自定义名称 -
agentBuilder:tracing:includeRealIds：保留实际的对话标识符，而不是默认的哈希版本。这意味着 trace 数据会收集原始 ID，从而可以将 trace 与特定用户会话关联起来（PII）。
只有在你了解你的 agents 处理的数据类型，并且已经建立适当的数据治理机制后，才应启用这些选项。
Agent Builder 如何在 Elasticsearch 中存储 OTel trace 数据
Agent Builder 使用 OpenTelemetry 语义约定。这会生成一个结构化的 span 层级结构，从而提供对 agent 内部逻辑的细粒度视图：
| Span | 类型 | 捕获内容 |
|---|---|---|
invoke_agent <name> |
CHAIN | 完整的一次运行生命周期，从用户输入到最终回复 |
invoke_agent <name> |
AGENT | 单次 agent 执行：推理、工具调用、回复 |
chat <model> |
LLM | 一次 LLM 请求：模型、延迟、token 数量 |
execute_tool <toolName> |
TOOL | 工具调用：参数、耗时、结果 |
Trace 数据会被写入每个 Kibana space 专用的 data stream 中，从而保持对话数据清晰隔离。要在 Discover 中查询你的 trace，可以直接指定对应 space 的索引：
css
`FROM traces-agent_builder.otel-<space-id>` AI写代码对于默认 space，对应的是 traces-agent_builder.otel-default。如果启用了高级隐私控制，那么这些 span 属性也会随着原始 span 一起发送到 trace data stream 中。这个索引允许你查询原始消息内容，从而查看对话中实际说了什么。最佳实践是避免使用通配符，以防止混合来自不同 space 的数据。
Agent Builder 自带一个名为 agent-builder-traces 的内置 skill，当 agentBuilder:tracing:enabled 开启时会自动安装。你可以使用它直接询问关于 trace 数据的问题，从而无需从头编写 ES|QL 就可以轻松探索 agent 行为。
如何使用 OTel trace 瀑布视图调试 agent 行为
trace 瀑布视图会将 Agent Builder 会话中的每个步骤以时间线形式展示。要打开它，请在对话界面中导航到特定的一次运行，并选择 trace 图标。
这会启动一个瀑布时间线，将 agent 执行过程中的每个步骤进行拆解展示。在顶部层级，你会看到 invoke_agent 父 span，其中包含 agent 运行的完整端到端耗时。在其下方嵌套的是 chat spans，每个 span 代表一次独立的 LLM 请求，并显示模型响应所花费的准确时间。与此同时，还有 execute_tool spans，每次工具调用对应一个 span，你可以查看调用了哪个工具、接收了哪些参数以及运行了多长时间。这使你能够追踪 agent 遵循的完整执行顺序，定位时间瓶颈，并查看错误发生的位置。
如何基于 trace 数据构建 token 成本仪表板
Discover 会提供原始 trace 数据，但大多数团队希望获得运营层面的问题答案，例如"我们今天消耗了多少 token？"、"哪个工具被调用次数最多？"以及"本周有多少不同的用户与 agent 进行了交互？"。这些问题需要直接基于 trace 数据构建仪表板。
Elastic 提供了一个由 Elastic 管理的开箱即用仪表板，名为 Elastic Agent Builder Overview ，你可以在 GenAI Settings 中 Agent Traces 部分的右上角点击安装该仪表板。
它包含多个基础指标，涵盖 token 使用量与成本、对话数量与延迟、agent 执行情况，以及工具调用频率和错误。
不过，自定义仪表板通常会更加高效。如果你希望获得更符合自身需求的仪表板，可以直接基于 OTel trace 索引构建 Lens 面板。以下是几个值得首先创建的面板：
1）按 token 消耗排序的最活跃对话
针对 traces-agent_builder.otel-<space-id> 创建一个水平条形图。将 x 轴设置为 gen_ai.conversation.id，按降序排序，并限制为前 10 个。将 y 轴设置为 gen_ai.usage.input_tokens 与 gen_ai.usage.output_tokens 的总和。在公式中输入：
scss
`sum(gen_ai.usage.input_tokens) + sum(gen_ai.usage.output_tokens)`AI写代码LLM 往返次数最多的对话
你也可以选择使用一个简单的 ES|QL 查询来创建此可视化，大致如下：
perl
``
1. FROM traces-agent_builder.otel-<space-id>
2. | WHERE @timestamp >= ?_tstart AND @timestamp < ?_tend
3. | WHERE gen_ai.operation.name == "chat"
4. | STATS `Chat Span Count` = COUNT(*) BY `Conversation ID` = gen_ai.conversation.id, `Span Name` = span.name
5. | SORT `Chat Span Count` DESC
6. | LIMIT 100
``AI写代码此外，还有一个名为 dashboard-management 的内置 skill，可以帮助你使用自然语言创建 trace 可视化。
如何为 Agent Builder 对话设置 token 成本告警
对于基于 LLM 的 agents 来说，token 消耗是最直接影响成本的因素。一次失控的对话就可能在任何人注意到之前耗尽你整个月的预算。
Elastic 告警功能允许你直接基于 trace 数据定义阈值规则。导航至 Observability > Alerts > Manage Rules > Create Rule ，然后选择 Elasticsearch query 作为规则类型。
一个在任意单次对话超过 256,000 个 token 时触发的 ES|QL 告警规则如下所示：
sql
`
1. FROM traces-agent_builder.otel-<space-id>
2. WHERE @timestamp > NOW() - 15 minutes
3. | STATS total_tokens = SUM(gen_ai.usage.input_tokens) + SUM(gen_ai.usage.output_tokens)
4. BY gen_ai.conversation.id
5. | WHERE total_tokens > 256000
6. | KEEP gen_ai.conversation.id, total_tokens
`AI写代码将调度周期设置为每 15 分钟运行一次，并将触发动作配置为发送 Slack 通知或创建 PagerDuty incident。告警负载中的 gen_ai.conversation.id 值会提供需要检查的具体对话。
Agent Builder 可观测性的未来发展方向
agent trace 提供的可见性远远超出了调试用途。一旦你基于 Agent Builder trace 数据构建了仪表板并配置了告警，你就能够实时掌握 agents 在生产环境中的运行情况。如果你还没有开始使用，不妨在你的 Kibana space 中启动 Agent Builder，确保已启用 tracing，然后运行几次对话。查看 Discover，打开瀑布视图，看看你的 agent 在底层到底做了什么。
这是 Agent Builder 可观测性系列文章的第一篇。接下来，我们将深入介绍如何使用 agent-builder-traces skill 以对话方式查询你的数据，如何基于 trace 数据构建自定义评估流水线，以及如何利用 trace 将对话历史重新馈送给你的 agents。你的 agents 一直在保存着这些记录，现在是时候让它们开口说话了。