作者:来自 Elastic Greg Crist

你的 Foundry agent 已发送到 Agent 365 的追踪片段也可以发送到 Elastic。在那里,一个 Kibana 仪表板就能展示各模型的成本、哪些工具调用运行缓慢、哪些追踪片段失败,以及谁的花费最多。
在你的数据所在之处构建并观测 人工智能 agent。从 Elastic Agent 构建器开始。你也可以立即开启免费云试用,或在你的本地计算机(local machine)上试用 Elastic。
Foundry 托管的 agent 所产生的 OpenTelemetry 追踪片段已经能够反映其运行成本。九条 ES|QL 查询和一个可导入的 Kibana 仪表板,将各模型的词元成本、工具延迟、失败的追踪片段以及每位调用者的花费集中呈现在一个屏幕上。同样的追踪片段也会发送到 Agent 365,用于另一项任务:确定 agent 的身份及其操作权限。
在示例数据中,一个工具的第95百分位延迟为10秒,将 agent 自身的第95百分位延迟拖慢至13.1秒;共有79个追踪片段失败,涉及五种错误类型。配套内容包括一个示例 agent 容器、一个可生成605次运行及约3,000个追踪片段的生成器,以及一条在 agent 调用此前从未调用过的工具时触发的 ES|QL 规则。
本文接续面向 Microsoft Foundry 的人工智能 agent 可观测性:两个环境变量,无需收集器一文,该文介绍了如何将 Foundry 的追踪片段接入 Elastic。

前提条件:将 Foundry agent 的追踪片段接入 Elastic
本文接续面向 Microsoft Foundry 的人工智能 agent 可观测性:两个环境变量,无需收集器一文。在那篇文章中,我们介绍了如何将 Foundry agent 的追踪片段发送到 Elastic 托管的开放遥测协议端点,并以应用性能监控瀑布图的形式查看单次运行。在使用以下各节的内容之前,你需要先获取那篇文章中提到的端点网址和应用程序编程接口密钥。追踪片段会写入 traces-generic.otel-default 数据流。
瀑布图适合查看单次运行。要回答诸如_本周哪个模型的成本最高?_、哪位调用者推高了花费?,或某个工具是否变慢之类的问题,就需要对所有运行进行聚合,而这正是仪表板的用途。在本文中,我们将构建这个仪表板,并补充前文未涉及的 Agent 365 相关背景。
Microsoft Foundry agent 的追踪数据会发送到哪里?
Foundry agent 会从三个来源生成追踪数据,并可将其发送到包括 Agent 365 在内的多个目标位置,但只有部分追踪数据会到达 Elastic:
- Foundry 生成服务端追踪数据(Foundry generates server-side traces),涵盖提示词 agent、托管 agent 以及工作流。Foundry 会将这些数据存储在与你的项目关联的应用程序洞察资源中,默认不会将其发送到 Elastic。
- 客户端追踪数据(Client-side traces)来自调用 agent 的应用程序。它们记录你的调用代码及其向 Foundry 发出的请求,追踪范围止于 agent 的边界。
- 容器内追踪数据(In-container traces)来自托管 agent,其容器运行着你自己的编排代码。对这些代码进行插桩,可以记录 agent 发起的每一次模型调用和工具调用。容器的遥测管道可以通过开放遥测协议将这些追踪片段发送到 Elastic;启用 Agent 365 导出后,也可以将其发送到 Agent 365。这些导出器各自独立,共用一条管道,并非单个通用的开放遥测协议导出器。本文后续内容将采用这条路径。
Agent 365 是数据的目标位置,而非来源。它是微软用于管理 agent 身份、治理和安全的控制平面。它接收追踪片段,为 Microsoft 365 管理中心的 agent 清单以及 Microsoft Purview 和 Microsoft Defender 提供数据。Agent 365 并不是用于存储完整原始追踪片段的通用存储系统。它支持通过 Microsoft Defender 高级搜寻等界面,查询经过处理的 agent 活动记录。
Agent 365 和 Elastic 各自保留哪些数据
这两个目标位置承担不同的任务,同一个追踪片段会同时发送到两者:
| 比较项 | Agent 365 | Elastic |
|---|---|---|
| 回答的问题 | 有哪些 agent?谁拥有它们?它们可以执行哪些操作? | agent 在成本、延迟、失败和用量方面表现如何? |
| 优势 | 在 Microsoft 365、Purview 和 Defender 中提供身份、治理、合规及安全视图。 | 对 agent 发出的每个追踪片段执行即席 ES|QL 查询,不限制追踪片段类型。你可以控制追踪片段的保留时长和读取权限,甚至对提示词内容实施字段级安全控制。仪表板、告警规则和检测功能(例如下文的新工具查询)均基于同一份数据运行。你还可以将 agent 的追踪数据与你技术栈中其他部分的日志、指标和应用性能监控数据关联起来。 |
| 保留的追踪片段 | 仅保留 invoke_agent、execute_tool、chat 和 output_messages。即使超文本传输协议导出请求返回200,也会丢弃缺少租户标识符或 agent 标识符的追踪片段。 |
agent 发出的所有追踪片段,包括 Agent 365 忽略的类型,例如 plan、invoke_workflow 和内存操作。 |
这两个目标位置保留的追踪片段不同,但它们共有的身份字段能让你将数据对应起来。在 Elastic 中按 gen_ai.agent.id 和 microsoft.tenant.id 筛选,可以单独查看某个租户中的一个 agent 实例,然后使用 gen_ai.conversation.id 和追踪标识符,从管理中心一路追踪到 Elastic 中的单次运行。
将 Foundry 托管 agent 的追踪数据发送到 Elastic 和 Agent 365
Foundry 托管 agent 在 Foundry agent 服务器宿主中运行,该宿主已经完成了大部分工作。在我测试的版本中(azure-ai-agentserver-core 2.2.0 和 microsoft-opentelemetry 1.3.9),它会为你配置微软的开放遥测发行版。它会将数据导出到 OTEL_EXPORTER_OTLP_ENDPOINT 指定的任意开放遥测协议端点,默认使用超文本传输协议和协议缓冲区格式。它会根据 FOUNDRY_AGENT_* 环境变量,为每个追踪片段附加 agent 标识符、蓝图标识符、租户标识符和会话标识符。当 Foundry 为该 agent 启用 Agent 365 导出时,它也会开启相应的导出功能。Foundry 通过账户级设置 a365LoggingEnabled 控制 Agent 365 导出。当该设置为真时,受支持的托管库会自动开启导出。因此,容器本身不会调用 use_microsoft_opentelemetry()。
容器_确实会_使用该发行版的作用域来描述运行中的每个步骤。InvokeAgentScope、InferenceScope 和 ExecuteToolScope 会分别生成 invoke_agent、chat 和 execute_tool 追踪片段,其格式既能被 Agent 365 接受,也能被仪表板查询读取。这个 agent 处理一个调用端点。每个请求都在一个根 invoke_agent 追踪片段内运行,并调用一个工具。它还会通过 Foundry 客户端调用一次模型。下面的代码在 AgentDetails 中统一描述 agent 的身份,然后将工具调用和模型调用分别封装在会生成 execute_tool 和 chat 追踪片段的作用域中。除非你设置 CAPTURE_MESSAGE_CONTENT,否则内容采集会保持关闭。
ini
`
1. import asyncio
2. import os
3. import uuid
4. from urllib.parse import urlparse
6. # The scopes below do nothing unless observability is switched on. The agent server host
7. # only does that itself when Foundry enables Agent 365 export, so opt in here to get spans
8. # in Elastic either way.
9. os.environ.setdefault("ENABLE_OBSERVABILITY", "true")
11. from azure.ai.agentserver.invocations import InvocationAgentServerHost
12. from azure.ai.projects import AIProjectClient
13. from azure.identity import DefaultAzureCredential
14. from microsoft.opentelemetry.a365.core import (
15. AgentDetails,
16. CallerDetails,
17. Channel,
18. ExecuteToolScope,
19. InferenceCallDetails,
20. InferenceOperationType,
21. InferenceScope,
22. InvokeAgentScope,
23. InvokeAgentScopeDetails,
24. Request,
25. ServiceEndpoint,
26. ToolCallDetails,
27. ToolType,
28. UserDetails,
29. )
30. from starlette.responses import JSONResponse
32. # The agent server host turns on OTLP export when OTEL_EXPORTER_OTLP_ENDPOINT is set.
33. app = InvocationAgentServerHost()
35. CAPTURE_CONTENT = os.environ.get("CAPTURE_MESSAGE_CONTENT", "false").lower() == "true"
36. MODEL = os.environ["FOUNDRY_MODEL_NAME"]
37. PROJECT_HOST = ServiceEndpoint(hostname=urlparse(os.environ["FOUNDRY_PROJECT_ENDPOINT"]).hostname)
39. # The instance ID goes in agent_id. Using the blueprint ID there makes Agent 365 reject
40. # the export with a 403 agent ID mismatch.
41. AGENT = AgentDetails(
42. agent_id=os.environ["FOUNDRY_AGENT_INSTANCE_CLIENT_ID"],
43. agent_),
44. agent_blueprint_id=os.environ["FOUNDRY_AGENT_BLUEPRINT_CLIENT_ID"],
45. tenant_id=os.environ["FOUNDRY_AGENT_TENANT_ID"],
46. )
48. project = AIProjectClient(
49. endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
50. credential=DefaultAzureCredential(),
51. )
52. openai = project.get_openai_client()
55. def lookup_order(request: Request, order_id: str) -> str:
56. """Stand-in for a real tool call, such as a database or MCP lookup."""
57. arguments = {"order_id": order_id}
58. details = ToolCallDetails(
59. tool_,
60. arguments=arguments if CAPTURE_CONTENT else None,
61. tool_call_id=str(uuid.uuid4()),
62. tool_type=ToolType.FUNCTION.value,
63. # Replace with the host your real tool calls.
64. endpoint=ServiceEndpoint(host),
65. )
66. with ExecuteToolScope.start(request=request, details=details, agent_details=AGENT) as scope:
67. result = f"Order {order_id} shipped and arrives Thursday."
68. if CAPTURE_CONTENT:
69. scope.record_response(result)
70. return result
73. def ask_model(request: Request, prompt: str) -> str:
74. """One model call, recorded as a chat span with token counts."""
75. details = InferenceCallDetails(
76. operationName=InferenceOperationType.CHAT,
77. model=MODEL,
78. provider,
79. endpoint=PROJECT_HOST,
80. )
81. with InferenceScope.start(request=request, details=details, agent_details=AGENT) as scope:
82. response = openai.responses.create(model=MODEL, input=prompt)
83. if CAPTURE_CONTENT:
84. scope.record_input_messages([prompt])
85. scope.record_output_messages([response.output_text])
86. scope.record_input_tokens(response.usage.input_tokens)
87. scope.record_output_tokens(response.usage.output_tokens)
88. return response.output_text
91. @app.invoke_handler
92. async def handle(request):
93. body = await request.json()
94. question = body.get("question", "")
96. # Content=None keeps the question out of the span. The conversation ID groups the runs
97. # in one thread. The host adds Foundry's session ID to every span for you.
98. agent_request = Request(
99. content=question if CAPTURE_CONTENT else None,
100. conversation_id=body.get("conversation_id"),
101. channel=Channel()),
102. )
103. caller = CallerDetails(
104. user_details=UserDetails(user_id=body.get("user_id"), user_client_ip=request.client.host)
105. )
107. # One root span per request keeps the model and tool calls in a single trace.
108. with InvokeAgentScope.start(
109. request=agent_request,
110. scope_details=InvokeAgentScopeDetails(endpoint=PROJECT_HOST),
111. agent_details=AGENT,
112. caller_details=caller,
113. ) as scope:
114. order_status = lookup_order(agent_request, body.get("order_id", "unknown"))
116. # The OpenAI client is synchronous, so run it off the event loop.
117. answer = await asyncio.to_thread(
118. ask_model,
119. agent_request,
120. "You are a support agent. Answer in two sentences.\n"
121. f"Order status: {order_status}\n"
122. f"Customer question: {question}",
123. )
124. if CAPTURE_CONTENT:
125. scope.record_output_messages([answer])
126. return JSONResponse({"answer": answer})
129. if __name__ == "__main__":
130. app.run()
`AI代码解释收起代码块
在容器镜像中安装这些软件包,并为托管 agent 设置开放遥测协议环境变量。Foundry 会在启动时将 FOUNDRY_* 变量注入每个托管 agent 容器。这些变量是保留的只读变量,因此你的代码应读取它们,但绝不能设置或覆盖它们:
ini
`
1. pip install azure-ai-agentserver-invocations azure-ai-projects azure-identity \
2. microsoft-opentelemetry
4. export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-motlp-endpoint>"
5. export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey <your-api-key>"
`AI代码解释
按照 Foundry 托管 agent 文档(Foundry hosted agents documentation)将容器部署为托管 agent,然后向其发送几个请求,并在请求体的对象表示法数据中包含 order_id、question、user_id 和 conversation_id。
会悄然阻止 Foundry agent 追踪片段到达的细节
该文件中的一些细节比看起来更重要:
- 开启可观测性。(Switch observability on.) 只有将
ENABLE_OBSERVABILITY设为true,这些作用域才会生效。宿主仅在 Foundry 启用 Agent 365 导出时才会自行完成此设置,因此文件中会显式设置它,确保无论是否启用该导出,Elastic 都能收到追踪片段。没有此设置,agent 会正常运行,但不会生成任何invoke_agent、chat或execute_tool追踪片段。 - 使用实例标识符,而非蓝图标识符。(Use the instance ID, not the blueprint ID.)
gen_ai.agent.id是 agent 实例的应用程序标识符。如果在此处使用蓝图标识符,Agent 365 会因 agent 标识符不匹配而拒绝导出,并返回403。请像示例一样保留两者:将实例标识符放在AgentDetails.agent_id中,将蓝图标识符放在agent_blueprint_id中,以便 Elastic 按蓝图汇总实例。 - 不要修改
gen_ai.agent.type。(Leavegen_ai.agent.typealone.) 微软保留Foundry等值供自身使用,Agent 365 会自行对已在 Microsoft Entra 中注册的 agent 进行分类。 - 宿主会设置服务名称。(The host sets the service name.)
service.name来自 Foundry 注入的FOUNDRY_AGENT_NAME,而非OTEL_SERVICE_NAME。缺少该变量时,到达的追踪片段会以azure.ai.agentserver作为服务名称。 - 操作名称为
Chat。(The operation name isChat.) 该发行版会将模型调用的gen_ai.operation.name写为Chat,其中的 C 为大写,而 Elastic 在比较关键字值时区分大小写。下文的每条查询都会使用TO_LOWER()处理该字段,以匹配两种大小写形式。 - 词元计数是数值。(Token counts are numbers.)
gen_ai.usage.input_tokens和gen_ai.usage.output_tokens通过开放遥测协议以整数形式传入,因此查询无需转换即可将它们相加。Agent 365 自身的传输格式会将所有值作为字符串发送,但发行版会在其内部处理这一差异。
如果你基于微软 agent 框架、语义内核、 LangChain 、LangGraph 或 OpenAI agent 软件开发工具包进行构建,该发行版可以通过 instrumentation_options 参数为它们插桩,这样你就可以省去手动作用域。自动插桩仅记录标准开放遥测属性,因此 Agent 365 仍需要由 BaggageBuilder 或宿主读取的 FOUNDRY_AGENT_* 变量提供微软身份属性。
宿主还会使用相同的开放遥测协议设置发送指标。本文仅基于追踪数据构建面板。在基于指标构建面板之前,请先检查你自己的数据中的指标名称。
要确认数据已到达,请以 ES|QL 模式打开探索页面并运行:
sql
`
1. FROM traces-generic.otel-*
2. | WHERE attributes.gen_ai.operation.name IS NOT NULL
3. | STATS spans = COUNT(*) BY operation = attributes.gen_ai.operation.name
`AI代码解释
你应该能看到 invoke_agent、Chat 和 execute_tool 对应的数据行。如果缺少某类数据行,请检查 ENABLE_OBSERVABILITY。如果所有数据行都没有出现,请检查应用程序编程接口密钥是否具有开放遥测协议端点的写入权限。

决定 Elastic 接收哪些 提示词 和响应内容
除了每次工具调用的参数和结果,这些作用域还可以记录提示词和响应。示例默认关闭内容采集,所有仪表板查询也都不需要这些内容。但 Agent 365 仅使用携带消息内容及工具参数和结果的追踪片段,并会过滤掉缺少这些内容的不合格追踪片段。你可以保持 Agent 365 导出开启,同时关闭内容采集,但 Agent 365 不会使用这些追踪片段。如果你开启内容采集,使其可供 Agent 365 使用,同样的追踪片段也会将这些内容发送到 Elastic。
你有三种处理方式:
| 选项(Option) | Agent 365 | Elastic | 所需配置(What it takes) |
|---|---|---|---|
| 关闭内容采集 | 不会使用这些追踪片段 | 获得仪表板所需的全部数据 | 无需额外配置 |
| 开启内容采集,在 Elastic 中限制访问 | 使用这些追踪片段 | 仅允许一个小范围角色读取 gen_ai.input.messages、`gen_ai.output.messages` 以及工具参数和结果属性 |
字段级安全控制 |
| 开启内容采集,在发送到 Elastic 前移除内容 | 使用这些追踪片段 | 不存储任何内容 | 在 agent 与 Elastic 之间部署一个带有属性处理器的开放遥测收集器 |
示例会读取 CAPTURE_MESSAGE_CONTENT 环境变量,默认关闭内容采集。请在首次生产部署前与你的隐私负责人共同做出这一决定,而不是部署后再决定。
Agent 365 导出的身份验证和许可要求
Elastic 端只需要一项凭据:具有托管开放遥测协议端点(managed OTLP (mOTLP) endpoint)写入权限的应用程序编程接口密钥。不要将其放入容器镜像。请将其存储在 Azure 密钥保管库中,并以机密形式提供给托管 agent。
Agent 365 端涉及更多配置,微软学习平台(Microsoft Learn)中均有说明:
- 租户中至少需要有一位用户获分配 Microsoft 365 E7 或 Microsoft Agent 365 许可证。否则,超文本传输协议导出请求会返回200成功,但响应会报告追踪片段被拒绝,原因为
tenant_not_licensed。403禁止访问则表示其他问题,即缺少必需的应用程序角色或委派权限范围,或者网址中的 agent 标识符与通过身份验证的身份不匹配。 - 已注册的 Agent 365 agent 实例通过服务间路径导出时,无需额外权限或管理员同意。委派路径和未注册的身份(例如标准应用注册)需要
Agent365.Observability.OtelWrite权限,并获得管理员同意。 - 对于服务间导出,任何未注册为 Agent 365 agent 实例的身份,无论是应用注册、托管身份,甚至是 agent 标识符,都需要
Agent365.Observability.OtelWrite应用程序角色,并获得管理员同意。
Agent 365 的可观测性属性有哪些用途?
与普通的生成式人工智能追踪数据相比,Agent 365 要求提供更多必填属性。这些属性也是实用的仪表板维度,因为它们说明了涉及谁、发生在哪里,以及属于哪个对话:
| 属性(Attribute) | 在 Elastic 中的用途(Use in Elastic) |
|---|---|
microsoft.tenant.id |
按租户筛选或拆分仪表板。 |
gen_ai.agent.id |
agent 实例的应用程序标识符。用作关联 Agent 365 管理记录的键,以及下文新工具检测的分组键。 |
gen_ai.agent.name |
按 agent 筛选仪表板。 |
microsoft.a365.agent.blueprint.id |
按蓝图汇总实例。 |
gen_ai.conversation.id |
将多次运行归入各自的对话。 |
microsoft.session.id、`microsoft.channel.name` |
用于会话和渠道面板。渠道值是简短的小写标记,例如 msteams、`outlook` 和 web。 |
user.id |
调用者的 Entra 对象标识符。用于查看每位调用者的词元花费和活动。 |
gen_ai.tool.type |
比较函数工具与模型上下文协议服务器。在最慢工具查询的 BY 子句中添加 tool_type = attributes.gen_ai.tool.type。 |
| 消息、工具参数、工具结果 | 内容。(参见上文的相关选择。) |
微软的属性参考(attribute reference)列出了所有属性,并注明每种追踪片段类型的必填属性。示例设置了身份、对话、渠道、调用者、工具类型、工具调用标识符、模型和提供商属性。除了消息内容,Agent 365 还要求提供服务端和客户端地址。在依赖 Agent 365 端的功能之前,你应将完整属性列表与你自己的 agent 发出的属性逐一核对。
九条用于分析 Foundry agent 成本、延迟和失败情况的 ES|QL 查询
下文的每条查询都为一个仪表板面板提供数据。字段名称来自开放遥测生成式人工智能语义(OTel GenAI semantic)约定和 Agent 365 属性。微软与思科旗下的 Outshift 合作,为多 agent 系统扩展了这些约定,加入了 invoke_agent、plan、invoke_workflow、execute_tool 和内存操作等追踪片段类型。微软的agent 追踪概述(agent tracing overview)介绍了这些类型,并指出开放遥测生成式人工智能约定在上游仍处于开发状态,可能会发生变化。请固定软件开发工具包的版本;如果查询结果为空,请对照实际追踪数据检查字段名称。
各模型的词元用量随时间的变化
使用堆积面积图。下面的查询会按小时汇总输入和输出词元数量,并按模型拆分总量,生成其后的图表。这个面板能让失控的 agent 一目了然。反复重试同一工具调用的循环,会表现为某个模型对应的色带出现尖峰。
less
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "chat"
3. | STATS tokens = SUM(attributes.gen_ai.usage.input_tokens + attributes.gen_ai.usage.output_tokens)
4. BY hour = BUCKET(@timestamp, 1 hour), model = attributes.gen_ai.request.model
5. | SORT hour
`AI代码解释

按模型估算 token 成本
使用水平条形图。该查询将词元数量乘以每百万词元的费率。下列费率仅为占位值,请将其替换为你自己的 Azure 协议中的价格。任何未匹配到 CASE 分支的模型都会返回空值成本,因此请为你运行的每个部署添加一个分支。如果你的 Foundry 部署名称与底层模型名称不同,请改用 attributes.gen_ai.response.model 进行分组,该字段记录了实际作答的模型。
ini
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "chat"
3. | STATS input_tokens = SUM(attributes.gen_ai.usage.input_tokens),
4. output_tokens = SUM(attributes.gen_ai.usage.output_tokens)
5. BY model = attributes.gen_ai.request.model
6. | EVAL cost_usd = CASE(
7. model == "gpt-4o", input_tokens / 1000000.0 * 2.50 + output_tokens / 1000000.0 * 10.00,
8. model == "gpt-4o-mini", input_tokens / 1000000.0 * 0.15 + output_tokens / 1000000.0 * 0.60,
9. model == "gpt-4.1", input_tokens / 1000000.0 * 2.00 + output_tokens / 1000000.0 * 8.00,
10. NULL)
11. | KEEP model, cost_usd
12. | SORT cost_usd DESC NULLS LAST
`AI代码解释

Token 消耗最多的 agent 运行
使用数据表。按追踪标识符汇总 chat 追踪片段,可以得到整个 agent 运行的成本,而非单次模型调用的成本,排名第一的运行通常最值得优先打开查看。失败的模型调用不包含词元计数,因此 NULLS LAST 可以防止完全由失败调用组成的运行挤占表格顶部的位置。
scss
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "chat"
3. | STATS input_tokens = SUM(attributes.gen_ai.usage.input_tokens),
4. output_tokens = SUM(attributes.gen_ai.usage.output_tokens),
5. chat_calls = COUNT(*)
6. BY trace.id
7. | SORT input_tokens DESC NULLS LAST
8. | LIMIT 10
`AI代码解释

按操作类型统计延迟
使用分组条形图。比较每种操作类型的第50百分位延迟和第95百分位延迟,可以判断耗时来自模型调用、工具调用,还是围绕这些调用的编排过程。开放遥测以纳秒为单位存储追踪片段的 duration,因此查询会将其转换为毫秒。
scss
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) IN ("invoke_agent", "chat", "execute_tool")
3. | EVAL duration_ms = duration / 1000000.0
4. | STATS p50 = PERCENTILE(duration_ms, 50),
5. p95 = PERCENTILE(duration_ms, 95)
6. BY operation = TO_LOWER(attributes.gen_ai.operation.name)
`AI代码解释

按第95百分位延迟排名的最慢工具调用
使用水平条形图。按第95百分位延迟而非平均值排名,可以避免通常很快、但偶尔耗时10秒的工具被正常的平均值掩盖。
ini
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "execute_tool"
3. | EVAL duration_ms = duration / 1000000.0
4. | STATS p95_ms = PERCENTILE(duration_ms, 95), calls = COUNT(*)
5. BY tool = attributes.gen_ai.tool.name
6. | SORT p95_ms DESC
7. | LIMIT 10
`AI代码解释

按操作和错误类型统计失败的追踪片段
使用数据表。按操作和错误类型分组,可以将提供商限流、内容过滤拦截与工具超时区分开来,这些问题各有不同的负责人和解决方法。
ini
`
1. FROM traces-generic.otel-*
2. | WHERE attributes.gen_ai.operation.name IS NOT NULL
3. AND status.code == "Error"
4. | STATS failures = COUNT(*)
5. BY operation = TO_LOWER(attributes.gen_ai.operation.name), error_type = attributes.error.type
6. | SORT failures DESC
`AI代码解释

按渠道统计 agent 运行:Teams、Outlook 和网页
使用水平条形图。Agent 365 会记录每次运行的来源入口,例如 Teams、Outlook 或网页。比较各个渠道,可以了解 agent 的实际使用情况,以及出现故障时应优先检查哪个渠道。
sql
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "invoke_agent"
3. | STATS runs = COUNT(*) BY channel = attributes.microsoft.channel.name
4. | SORT runs DESC
`AI代码解释

按调用者统计词元消耗
使用数据表。词元计数记录在 chat 追踪片段中,调用者信息则记录在根 invoke_agent 追踪片段中,因此查询会先按追踪汇总词元数量,并从同一追踪中获取调用者信息,然后再按调用者汇总。调用者由 user.id 中的 Entra 对象标识符表示。你可以在 Entra 中将其解析为名称,或在 Elastic 中补充相应信息。
scss
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) IN ("invoke_agent", "chat")
3. | STATS run_tokens = SUM(attributes.gen_ai.usage.input_tokens + attributes.gen_ai.usage.output_tokens),
4. caller = MAX(attributes.user.id)
5. BY trace.id
6. | WHERE caller IS NOT NULL
7. | STATS runs = COUNT(*), tokens = SUM(run_tokens) BY caller
8. | SORT tokens DESC NULLS LAST
9. | LIMIT 10
`AI代码解释

最活跃的会话和对话
使用数据表。一次_会话_代表一次访问,而一个_对话_是该会话中的一条交流线程。如果你想了解人们实际如何使用 agent,可以打开那些包含大量运行和多个对话的会话查看。
ini
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "invoke_agent"
3. | STATS runs = COUNT(*),
4. conversations = COUNT_DISTINCT(attributes.gen_ai.conversation.id)
5. BY session = attributes.microsoft.session.id
6. | SORT runs DESC
7. | LIMIT 10
`AI代码解释

在 Kibana 中构建 Foundry agent 仪表板
你可以导入已完成的仪表板,也可以按照以下步骤逐个构建面板。
导入已完成的 Kibana 仪表板
foundry-agent-traces-dashboard.ndjson 是仪表板的导出文件,包含全部九个面板,以及用于 agent、租户、渠道、对话和会话的五个筛选器。要将其导入你自己的 Kibana:
- 打开堆栈管理(Stack Management) ,然后打开已保存对象(Saved Objects) 。在 Elastic 云无服务器版中,依次打开项目设置(Project settings) 、管理(Management)和已保存对象(Saved objects)。
- 选择导入(Import) ,选择
.ndjson文件,并保留默认选项。 - 打开仪表板(Dashboards) ,选择 Foundry agent 追踪(Foundry agent traces)。时间选择器默认设为最近24小时。
这些面板读取 traces-generic.otel-*,并未限定为某个 agent,因此涵盖向该数据流写入数据的所有 agent。要缩小范围,请使用顶部的 Agent 和**租户(Tenant)**筛选器。
你也可以通过已保存对象应用程序编程接口导入该文件:
ini
`
1. curl -X POST "https://<your-kibana-url>/api/saved_objects/_import?overwrite=true" \
2. -H "Authorization: ApiKey <your-api-key>" \
3. -H "kbn-xsrf: true" \
4. -F file=@foundry-agent-traces-dashboard.ndjson
`AI代码解释
逐个构建仪表板面板
要手动创建仪表板:
- 在 Kibana 中打开仪表板(Dashboards),并创建一个新仪表板。
- 选择添加面板(Add panel) ,然后选择 ES|QL。
- 粘贴其中一条查询并运行。Kibana 会根据结果的结构推荐图表类型,请选择上文为该查询列出的类型。
- 将面板保存到仪表板,然后对其他查询重复上述步骤。
仪表板的时间选择器通过 @timestamp 应用于每个 ES|QL 面板,因此无需在查询中添加时间筛选条件。要按 agent、租户、渠道、对话或会话筛选,请像导入的仪表板那样,为相应字段添加 ES|QL 控件。
请注意,示例中的 lookup_order 工具会立即返回,因此在你封装实际调用之前,你自己的工具面板将显示接近零的延迟。
生成 605 次示例 agent 运行,填充仪表板
如果你的 agent 还不够活跃,generate_sample_traces.py 可以通过开放遥测协议发送24小时的逼真追踪数据,以及此前一周的历史数据。它会生成与上述容器相同的 invoke_agent、Chat 和 execute_tool 追踪片段及 Agent 365 属性,共包含605次 agent 运行和约3,000个追踪片段,服务名称为 support-agent-sample。
ini
`
1. pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
2. export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-motlp-endpoint>"
3. export ELASTIC_API_KEY="<your-api-key>"
4. python generate_sample_traces.py
`AI代码解释
该脚本覆盖当前小时之前的24个完整小时,因此仪表板的默认时间范围会显示全部数据。上方预览中的每个面板都来自这些数据,运行脚本和查询即可复现下一节中的每个数值。
示例数据揭示的情况:词元用量尖峰、缓慢的工具和79次失败
本文顶部的预览来自上述示例数据。示例数据包含四个工具(web_search、mcp_ticket_lookup、code_interpreter、file_search),而最简容器中只有一个,因此你自己的工具面板会列出你的 agent 实际调用的工具。Kibana 会按照浏览器的时区绘制时间轴,因此你图表上的具体时间会与预览不同。有四点值得关注:
- 词元图表在时间窗口结束前约九小时出现了明显尖峰(The token chart has a sharp spike about nine hours before the end of the window) ,集中在
gpt-4o色带中,约为平时每小时总量的两倍。词元消耗最多的运行表格揭示了原因:该小时内的四次运行,每次使用了12,060至41,200个输入词元,而典型运行通常只有几千个。排名第一的追踪4f2a91c0发起了14次模型调用。这四次运行合计消耗约110,000个词元,占据了尖峰的大部分。将排名第一的追踪标识符粘贴到 Elastic 应用性能监控中,打开瀑布图。如果图中显示 agent 反复调用同一个工具,你就找到了循环,而循环会返回超文本传输协议200状态码,且始终不会报错。 - 工具面板显示
web_search的第95百分位延迟约为10秒(The tools panel putsweb_searchat a p95 of about 10 seconds) ,远高于其他工具,延迟面板则显示了由此带来的代价:invoke_agent的第95百分位延迟为13.1秒,而第50百分位延迟为4.6秒。任何涉及web_search的运行都要承担这份延迟。 - 失败的追踪片段表格将79次失败分类展示(The failed spans table splits the 79 failures) ,包括
chat限流37次、工具超时21次、内容过滤拦截12次,以及数量较少的连接错误6次和触及词元上限3次。限流失败指向模型部署的配额问题,而超时则指向同一个缓慢的工具。web_search的第95百分位延迟达到10秒,主要由这些超时造成,因此修复超时最能改善该数值。 - 调用者和渠道面板揭示了这些数字背后的使用者。(The caller and channel panels say who's behind the numbers.) 在605次运行中,336次来自 Teams,165次来自网页,104次来自 Outlook。排名第一的调用者在63次运行中消耗了约253,000个词元,因此少数调用者贡献了大部分花费。当词元图表中的尖峰与某位调用者的活动重合时,你就知道该查看谁的用量,以及向谁询问。

检测 Foundry agent 调用此前从未使用过的工具
如果一个 agent 突然调用此前从未调用过的工具,就值得检查。这可能是新功能,也可能是提示词注入在引导 agent 访问不该触及的内容。该查询以过去30天为回溯范围,找出最近一天内首次出现的 agent 与工具组合。
less
`
1. FROM traces-generic.otel-*
2. | WHERE TO_LOWER(attributes.gen_ai.operation.name) == "execute_tool" AND @timestamp >= NOW() - 30 days
3. | STATS first_seen = MIN(@timestamp), calls = COUNT(*)
4. BY agent_id = attributes.gen_ai.agent.id, tool = attributes.gen_ai.tool.name
5. | WHERE first_seen > NOW() - 24 hours
`AI代码解释

示例数据中就包含这样一个案例:export_customer_data 出现在时间窗口的最后几个小时,而对应的 agent 此前一直只使用四个常规工具。要将该查询用作检测规则,请打开 Elastic 安全,创建一条新的 ES|QL 规则,粘贴查询,并设置为每小时运行一次。如果你不使用 Elastic 安全,也可以将其用作普通的 Kibana 告警。每次部署新增工具后,预计都会产生一些干扰告警,因此请在规则运行一周后调整回溯范围,并抑制针对已知工具的告警。
能否从 Foundry 提示词 agent 或 Copilot 工作室获取追踪数据?
这种仪表板方案适用于 Foundry 托管 agent,因为你拥有容器,可以将其追踪片段发送到任意位置。提示词 agent 完全在 Foundry 内部运行,没有可供你插桩的容器,因此其服务端追踪数据会保留在应用程序洞察中。微软 Copilot 工作室和 Microsoft 365 agent 同样运行在微软端,你没有自己的容器可用来添加导出器。本文中的方案不会将这些追踪数据发送到 Elastic。或许可以搭建桥接管道,例如将应用程序洞察数据导出到 Azure 事件中心,再通过 Elastic 的 Azure 集成读取,但这属于另一条采用不同数据结构的管道,也是后续讨论的话题。
生产环境检查清单:采样、版本固定和内容采集
请在上线前决定 Elastic 接收哪些消息内容,而不是上线后再决定。
采样会改变统计数值。这些面板会汇总收到的追踪片段,因此,如果你使用尾部采样,仅保留10%的常规追踪数据,词元和成本总量就会少算到大约实际值的十分之一。请按照前文的建议保留错误和缓慢的追踪数据,并选择不对 agent 追踪数据采样,或根据采样率按比例调整成本面板的数值。
请固定版本。示例已使用 azure-ai-agentserver-core 2.2.0、azure-ai-agentserver-invocations 1.2.0、azure-ai-projects 2.8.0 和 microsoft-opentelemetry 1.3.9 进行测试。该发行版和生成式人工智能约定都在不断变化,上文提到的 Chat 大小写就是可能随版本变化的细节。如果发生这种变化,每条查询中的 TO_LOWER() 都能让仪表板继续正常工作。
在账单到来前,对失控的词元用量发出告警
从词元消耗最多的运行查询开始。将其保存为一条 ES|QL 告警规则,并将词元阈值设为略高于正常情况下单次运行的第95百分位用量。当任何单条追踪的词元用量超过该阈值时,规则就会触发,让你在 agent 陷入循环的当小时收到通知,而不是等到月度账单到来才发现。然后添加新工具检测,并在开启 Agent 365 导出之前,决定你的 Elastic 项目应保留哪些内容。
开启 Elastic 云免费试用(Start a free trial on Elastic Cloud),获取托管开放遥测协议端点,或阅读托管开放遥测协议端点文档(mOTLP endpoint docs),了解其他部署选项。
更多资源:面向 Microsoft Foundry 的人工智能 agent 可观测性(AI agent observability for Microsoft Foundry) | 微软开放遥测发行版(Microsoft OpenTelemetry Distro) | Agent 365 可观测性属性参考(Agent 365 observability attribute reference) | Agent 365 可观测性概念(Agent 365 observability concepts) | agent 追踪概述(Agent tracing overview) | 为 Foundry agent 添加客户端追踪(Add client-side tracing to Foundry agents) | 开放遥测生成式人工智能语义约定(OpenTelemetry GenAI semantic conventions) | ES|QL 参考(ES|QL reference)*
原文:Agent 365 observability: Nine ES|QL queries for Foundry agents | Elastic Observability Labs