Agent 崩溃与死循环排查指南：可观测性 Dashboard 教程

Agent 崩溃与死循环排查指南：可观测性 Dashboard 教程

关键词：Agent可观测性、崩溃排查、死循环检测、Prometheus+Grafana、OpenTelemetry、LlamaIndex/Trace、Dashboard设计

摘要：Agent是当前大模型应用的核心载体，但它的自主决策、工具调用、记忆迭代特性让传统的“单步日志排查”彻底失效——Agent要么在工具调用的边缘突然崩溃、要么陷入无限思考/无限重试的死循环，开发者根本无从下手。本文将用小学生都能听懂的“侦探破案”比喻，一步一步拆解Agent崩溃与死循环的本质，再结合OpenTelemetry全链路埋点、Prometheus指标采集、LlamaIndex/Trace事件追踪、Grafana可视化Dashboard搭建的完整实操流程，教你打造一套“0漏网、10秒定位、1分钟找到根因”的Agent可观测系统。全文包含3个核心Agent故障案例、10+个埋点代码片段、2套可直接复用的Grafana Dashboard配置、5个行业最佳实践，最后还有思考题和常见问题解答，带你彻底告别Agent“黑盒时代”！

背景介绍：当“黑盒侦探”遇上“黑盒Agent”——一场找不到凶手的悬案

目的和范围

目的

如果你曾遇到过以下场景，这篇文章就是为你量身定制的：

1. 用户反馈“我的Agent突然消失了，再问它之前在做的事全忘了”——Agent进程/会话崩溃
2. 用户反馈“我的Agent卡了10分钟没动，再刷新还是‘思考中…’”——Agent思考/工具调用死循环
3. 你打开日志看，只有一堆大模型API调用的JSON，没有任何决策路径、没有任何记忆变化、没有任何工具调用的前置条件/后置结果关联——Agent是个纯黑盒
4. 你靠“加print语句、重启应用、猜可能的边界条件”排查了3小时，还是没找到崩溃/死循环的原因——排查效率极低

我们的核心目的，就是通过埋点+指标+事件追踪+可视化，把Agent这个“只会说话的黑盒子”变成“有监控录像、有通话录音、有行动轨迹的透明房间”，让你像“福尔摩斯看证据链”一样，10秒内定位故障会话，1分钟内找到根因（比如工具API超时导致的会话断开、工具返回空值触发的无限重试、prompt模板里没有设置循环次数上限导致的无限思考）。

范围

本文的范围聚焦在基于Python的轻量级Agent框架（比如LlamaIndex、LangChain、AutoGPT Lite），我们会以LlamaIndex作为主要示例框架（因为它的埋点生态最成熟，官方已经集成了OpenTelemetry和Prometheus），但核心的埋点思路、Dashboard设计方法、故障排查逻辑，完全可以迁移到LangChain、AutoGPT、甚至你自己手写的Agent上。

本文不涉及：

1. 分布式Agent集群的排查（本文主要讲单机或轻量级多机部署）
2. 大模型服务端（比如OpenAI、Claude、本地部署的Llama3）本身的崩溃排查（这属于LLMOps的范围，本文主要讲Agent应用端）
3. 复杂的安全漏洞排查（比如Prompt Injection导致的死循环，本文主要讲技术逻辑缺陷导致的崩溃/死循环）

预期读者

本文的预期读者有3类，我们会根据不同读者的需求调整内容的深浅：

1. 初级开发者（刚接触Agent，只会用框架搭简单的问答/工具调用机器人）：我们会用“侦探破案”的比喻讲清楚所有核心概念，所有代码都有逐行注释，所有Dashboard配置都可以直接复制粘贴，不需要你有任何可观测性的基础。
2. 中级开发者（已经搭过生产级的Agent，但经常遇到崩溃/死循环，排查效率低）：我们会讲清楚埋点的最佳实践、指标的设计思路、Dashboard的布局技巧，还有3个真实的生产级故障案例，带你从“被动排查”变成“主动预警”。
3. 高级开发者/架构师（负责搭建Agent的可观测系统，需要考虑性能、成本、扩展性）：我们会讲清楚OpenTelemetry的架构设计、Prometheus的采集策略、Grafana的告警规则，还有2套针对不同场景（单Agent/多Agent集群Lite版）的架构方案。

文档结构概述

本文的结构就像“侦探破案的完整流程”：

1. 背景介绍：先讲清楚为什么Agent的排查这么难（就像侦探遇到了没有监控、没有证人的悬案）
2. 核心概念与联系：把Agent可观测性的核心概念（埋点、指标、事件追踪、日志、可视化Dashboard）比作“侦探破案的工具包”（比如监控录像=全链路追踪、指纹=指标、通话录音=日志、证据板=Dashboard）
3. 问题本质拆解：把Agent的崩溃与死循环比作“悬案的两种类型”（失踪案=崩溃、无限徘徊案=死循环），先讲清楚每种故障的触发条件、表现特征、排查难点
4. 全链路埋点方案：教你用“OpenTelemetry+LlamaIndex/Trace”给Agent这个“透明房间”安装监控录像、指纹采集器、通话录音设备，所有代码都有逐行注释
5. 指标采集与告警规则：教你用“Prometheus”收集指纹，用“Grafana Alerting”设置指纹异常的预警（比如工具调用超时次数超过5次就发邮件/钉钉告警）
6. 可视化Dashboard搭建：教你用“Grafana”制作“证据板”——2套可直接复用的Dashboard配置（一套叫“Agent实时监控Dashboard”，用来排查实时故障；一套叫“Agent历史故障分析Dashboard”，用来分析历史故障的规律）
7. 项目实战：3个真实故障的排查过程：用刚才搭建的可观测系统，一步一步排查3个真实的生产级故障（工具API超时导致的会话崩溃、工具返回空值触发的无限重试、prompt模板里没有设置循环次数上限导致的无限思考）
8. 实际应用场景：讲清楚这套可观测系统在电商客服Agent、代码生成Agent、智能运维Agent这3个高频场景中的应用
9. 工具和资源推荐：推荐一些好用的可观测工具、资源库、博客文章
10. 未来发展趋势与挑战：讲清楚Agent可观测性的未来发展方向（比如基于大模型的自动根因分析、多模态Agent的可观测性）和当前面临的挑战（比如埋点的性能开销、大模型思考过程的可观测性）
11. 总结：学到了什么？：用“侦探破案工具包”的比喻，再一次回顾所有核心概念
12. 思考题：动动小脑筋：提出一些思考题，鼓励读者进一步思考和应用所学知识
13. 附录：常见问题与解答：解答一些读者可能会遇到的问题
14. 扩展阅读 & 参考资料：列出一些扩展阅读的资源

术语表

为了让初级开发者也能看懂，我们先把本文用到的核心术语用“侦探破案”的比喻解释一遍：

核心术语定义

相关概念解释

• 大模型API调用（LLM Call）：Agent向大模型服务端（比如OpenAI、Claude）发送请求，获取大模型的响应，这是Agent最核心的操作之一
• 工具调用（Tool Call）：Agent调用外部工具（比如天气查询API、数据库查询API、代码执行API）获取信息或完成操作，这也是Agent最核心的操作之一
• 记忆（Memory）：Agent用来存储用户的历史对话、工具调用的历史结果、自己的思考过程的地方，记忆分为“短期记忆”（比如当前会话的对话历史）和“长期记忆”（比如所有会话的对话历史）
• 推理链（Reasoning Chain）：Agent从用户的问题到最终回答的整个思考和行动路径，也就是埋点数据里的Trace
• 重试机制（Retry Mechanism）：当Agent的大模型API调用或工具调用失败时，自动重试的机制，如果重试次数没有上限，就会导致死循环
• 超时机制（Timeout Mechanism）：当Agent的大模型API调用或工具调用超过一定时间没有响应时，自动终止的机制，如果超时机制设置得太长，就会导致用户等待时间过长；如果设置得太短，就会导致Agent频繁失败
• 会话（Session）：用户和Agent的一次完整对话，从用户发送第一个问题开始，到用户关闭对话或会话超时结束

缩略词列表

核心概念与联系：侦探破案的工具包——把黑盒Agent变成透明房间

故事引入

假设你是一个小镇的侦探，最近镇上发生了两起奇怪的案件：

1. 失踪案：镇上的私家侦探小明，上周帮用户李阿姨订机票，订到一半突然消失了——李阿姨再给小明打电话，小明的电话关机了；李阿姨去小明的办公室，办公室的门开着，但小明不在里面；李阿姨之前和小明的所有对话记录（存在小明的笔记本里）也不见了。
2. 无限徘徊案：镇上的另一个私家侦探小红，昨天帮用户王叔叔找丢失的猫——王叔叔给了小红一张猫的照片和一些线索（猫最后出现在小区的花园里），小红就一直在花园里无限徘徊，一会儿看看树后面，一会儿看看草丛里，一会儿看看垃圾桶旁边，就是不找王叔叔要更多的线索，也不回家整理一下线索。

你作为小镇的侦探，现在要调查这两起案件，但你遇到了一个大问题：小明和小红的办公室里没有监控录像、没有指纹采集器、没有通话录音设备、甚至连他们的行动轨迹（比如每天去哪里、见了谁）都没有记录——你根本无从下手！

这时候，你想到了一个办法：给所有的私家侦探（Agent）的办公室里安装监控录像、指纹采集器、通话录音设备，还要给他们的手机安装定位追踪器——这样以后再发生案件，你就能通过这些设备还原整个案件过程，找到凶手了！

这些设备，就是我们今天要讲的Agent可观测性工具包（Traces、Metrics、Logs），而把这些设备整合在一起的证据板，就是我们今天要讲的Grafana可视化Dashboard。

核心概念解释（像给小学生讲故事一样）

核心概念一：全链路追踪（Traces）——私家侦探的监控录像+定位追踪器

监控录像能记录私家侦探在办公室里的所有行动（比如见了谁、说了什么、做了什么），定位追踪器能记录私家侦探在外面的所有行动轨迹（比如从哪里出发、走了哪条路、最后在哪里失踪/徘徊）——全链路追踪（Traces）就是把监控录像和定位追踪器结合在一起的工具，它能记录Agent从用户发送第一个问题到给出最终回答的完整路径。

我们再用一个更具体的例子来说明：
假设你让Agent帮你订一张“明天从北京到上海的最便宜的机票”，Agent的完整路径是这样的：

1. 用户的问题进入系统（这是Traces的第一个步骤，叫“Root Span”，就像监控录像的开始）
2. Agent接收用户的问题（这是Root Span的第一个子Span，叫“Agent Receive Question Span”）
3. Agent访问自己的短期记忆（这是Agent Receive Question Span的第一个子Span，叫“Agent Access Short-Term Memory Span”，看看有没有之前订过的机票的历史记录）
4. Agent思考下一步该做什么（这是Agent Access Short-Term Memory Span的下一个子Span，叫“Agent Think Span”——Agent思考：“用户要订明天从北京到上海的最便宜的机票，我需要先查一下明天从北京到上海的所有机票，然后再筛选出最便宜的，最后再帮用户订下来——那我第一步应该调用‘机票查询API’”）
5. Agent调用机票查询API的前置条件检查（这是Agent Think Span的第一个子Span，叫“Tool Precondition Check Span”——Agent检查：“机票查询API需要的参数是‘出发地’、‘目的地’、‘出发日期’，用户的问题里都有，没问题，可以调用”）
6. Agent发送请求给机票查询API（这是Tool Precondition Check Span的下一个子Span，叫“Tool Send Request Span”）
7. 机票查询API返回响应（这是Tool Send Request Span的下一个子Span，叫“Tool Receive Response Span”——返回了明天从北京到上海的100张机票的信息）
8. Agent处理机票查询API的响应（这是Tool Receive Response Span的下一个子Span，叫“Agent Process Tool Response Span”——Agent筛选出了最便宜的一张机票：“东方航空MU5101，明天早上8点从北京首都机场T2出发，10点到上海虹桥机场T2，票价500元”）
9. Agent再次思考下一步该做什么（这是Agent Process Tool Response Span的下一个子Span，叫“Agent Think Again Span”——Agent思考：“我已经找到了最便宜的机票，现在需要确认一下这张机票有没有余票，所以我应该调用‘机票余票查询API’”）
10. ……（中间省略了余票查询、用户确认、支付的步骤）
11. Agent给出最终回答（这是Root Span的最后一个子Span，叫“Agent Give Final Answer Span”——“您好，我已经帮您订好了明天从北京到上海的最便宜的机票：东方航空MU5101，明天早上8点从北京首都机场T2出发，10点到上海虹桥机场T2，票价500元，支付成功，订单号是123456789”）
12. 用户的问题离开系统（这是Traces的最后一个步骤，就像监控录像的结束）

你看，全链路追踪（Traces）就像一部完整的电影，每一个步骤（Span）都是电影的一个镜头，镜头之间有明确的顺序（父Span和子Span的关系），每个镜头都有自己的开始时间、结束时间、状态（成功/失败）、标签（比如机票查询API的出发地是北京、目的地是上海、出发日期是明天）——这样以后再发生Agent崩溃或死循环的案件，你就能像看电影一样，还原整个案件过程，找到崩溃或死循环的位置了！

核心概念二：指标数据（Metrics）——私家侦探的指纹采集器+考勤表

指纹采集器能记录私家侦探的行为频率（比如每天见多少人、每天打多少电话），考勤表能记录私家侦探的行为时长（比如每次见人花多少时间、每次打电话花多少时间）、成功率（比如每天帮用户解决多少问题、每天订机票的成功率是多少）——指标数据（Metrics）就是把指纹采集器和考勤表结合在一起的工具，它能记录Agent的统计信息，而且这些信息是按时间顺序排列的（时间序列数据）。

我们再用刚才订机票的例子来说明：
假设你有10个Agent在同时帮用户订机票，指标数据（Metrics）能记录以下信息：

1. 当前活跃的Agent会话数（比如现在有50个用户在和Agent对话）
2. 过去1分钟内大模型API的调用次数（比如过去1分钟内10个Agent一共调用了200次大模型API）
3. 过去1分钟内大模型API的平均响应时间（比如过去1分钟内大模型API的平均响应时间是2秒）
4. 过去1分钟内大模型API的失败率（比如过去1分钟内大模型API的失败率是5%）
5. 过去1分钟内工具调用的次数（比如过去1分钟内10个Agent一共调用了300次工具API）
6. 过去1分钟内工具调用的平均响应时间（比如过去1分钟内工具调用的平均响应时间是1秒）
7. 过去1分钟内工具调用的失败率（比如过去1分钟内工具调用的失败率是10%）
8. 过去1小时内Agent的会话完成率（比如过去1小时内10个Agent一共处理了1000个会话，完成了900个，完成率是90%）
9. 过去1小时内Agent的平均会话时长（比如过去1小时内Agent的平均会话时长是5分钟）

你看，指标数据（Metrics）就像一张实时更新的统计图，你能通过这张统计图看到Agent的运行状态——如果大模型API的失败率突然上升到50%，你就知道可能是大模型服务端出问题了；如果工具调用的平均响应时间突然上升到10秒，你就知道可能是工具API出问题了；如果Agent的会话完成率突然下降到50%，你就知道可能是Agent出问题了——这样以后再发生故障，你就能通过指标数据（Metrics）快速发现异常，不用等用户反馈了！

核心概念三：日志数据（Logs）——私家侦探的通话录音+笔记本

通话录音能记录私家侦探的详细对话内容（比如私家侦探对用户说的话、私家侦探对工具说的话、工具对私家侦探说的话），笔记本能记录私家侦探的详细思考过程（比如私家侦探为什么要调用这个工具、私家侦探为什么要筛选出这张机票）——日志数据（Logs）就是把通话录音和笔记本结合在一起的工具，它能记录Agent的详细事件，这些事件可以是非结构化的（比如一段文字），也可以是半结构化的（比如JSON）。

我们再用刚才订机票的例子来说明：
日志数据（Logs）能记录以下信息：

1. 用户的问题内容（比如“帮我订一张明天从北京到上海的最便宜的机票”）
2. Agent的短期记忆内容（比如“之前帮李阿姨订过一张从北京到上海的机票，订单号是987654321”）
3. Agent的思考过程内容（比如“用户要订明天从北京到上海的最便宜的机票，我需要先查一下明天从北京到上海的所有机票，然后再筛选出最便宜的，最后再帮用户订下来——那我第一步应该调用‘机票查询API’，参数是出发地=北京，目的地=上海，出发日期=2024-05-20”）
4. Agent发送给工具API的请求内容（比如“{‘出发地’: ‘北京’, ‘目的地’: ‘上海’, ‘出发日期’: ‘2024-05-20’}”）
5. 工具API返回给Agent的响应内容（比如“{‘status’: ‘success’, ‘data’: [{‘航空公司’: ‘东方航空’, ‘航班号’: ‘MU5101’, ‘出发时间’: ‘2024-05-20 08:00:00’, ‘到达时间’: ‘2024-05-20 10:00:00’, ‘出发机场’: ‘北京首都机场T2’, ‘到达机场’: ‘上海虹桥机场T2’, ‘票价’: 500, ‘余票’: 10}, …]”）
6. Agent处理工具API响应的过程内容（比如“我已经收到了机票查询API的响应，一共有100张机票，现在我要筛选出票价最低的一张——东方航空MU5101，票价500元，余票10张”）
7. Agent给出的最终回答内容（比如“您好，我已经帮您订好了明天从北京到上海的最便宜的机票：东方航空MU5101，明天早上8点从北京首都机场T2出发，10点到上海虹桥机场T2，票价500元，支付成功，订单号是123456789”）
8. Agent的错误信息（比如“机票查询API返回了错误：{‘status’: ‘error’, ‘message’: ‘出发日期不能是过去的时间’}”）

你看，日志数据（Logs）就像一本详细的日记，你能通过这本日记了解Agent的所有细节——如果Agent崩溃了，你就能通过日志找到崩溃前的最后一个事件；如果Agent陷入了死循环，你就能通过日志找到循环的原因（比如工具API一直返回空值，Agent一直重试）——这样以后再发生故障，你就能通过日志数据（Logs）找到根因了！

核心概念四：可视化Dashboard（Dashboard）——私家侦探的证据板

证据板能把监控录像、指纹、通话录音、笔记本放在同一个地方，让侦探一目了然地看到整个案件过程——可视化Dashboard（Dashboard）就是把全链路追踪（Traces）、指标数据（Metrics）、日志数据（Logs）整合在一起的工具，它能用图表（比如折线图、柱状图、热力图、表格）的形式展示出来，让开发者一目了然地看到系统的运行状态，定位故障的根因。

我们再用刚才失踪案和无限徘徊案的例子来说明：
如果我们给小明和小红的办公室里安装了监控录像、指纹采集器、通话录音设备，还给他们的手机安装了定位追踪器，然后把这些设备的数据整合在一起，制作成一个证据板（Dashboard），我们就能快速调查这两起案件了：

1. 失踪案调查：
   • 首先看证据板上的指标数据（Metrics）——发现小明昨天下午3点到3点10分之间，大模型API的调用次数是0，工具调用的次数是0，会话数突然从1降到0——这说明小明昨天下午3点左右失踪了。
   • 然后看证据板上的全链路追踪（Traces）——找到小明昨天下午最后一个会话的Traces，发现Traces的最后一个步骤是“Tool Send Request Span”（发送请求给机票支付API），状态是“Pending”（等待中），开始时间是昨天下午2点59分30秒，结束时间是昨天下午3点10分——这说明小明在调用机票支付API的时候，机票支付API一直没有响应，然后小明就崩溃了。
   • 最后看证据板上的日志数据（Logs）——找到小明昨天下午最后一个会话的Logs，发现Logs的最后一条是“发送请求给机票支付API：{‘订单号’: ‘123456789’, ‘支付金额’: 500}”，时间是昨天下午2点59分30秒——这验证了我们的猜测，小明确实是在调用机票支付API的时候崩溃的，原因可能是机票支付API超时了，而且小明的Agent没有设置超时机制，或者超时机制设置得太长了。
2. 无限徘徊案调查：
   • 首先看证据板上的指标数据（Metrics）——发现小红昨天下午4点到4点30分之间，大模型API的调用次数是100次，工具调用的次数是200次（一直在调用“花园监控查询API”），会话完成率是0——这说明小红昨天下午4点左右陷入了死循环。
   • 然后看证据板上的全链路追踪（Traces）——找到小红昨天下午最后一个会话的Traces，发现Traces的步骤一直在重复：“Agent Think Span”→“Tool Precondition Check Span”→“Tool Send Request Span”→“Tool Receive Response Span”→“Agent Process Tool Response Span”→“Agent Think Span”→…——这说明小红确实是在无限循环。
   • 最后看证据板上的日志数据（Logs）——找到小红昨天下午最后一个会话的Logs，发现Logs的内容一直在重复：“我需要找丢失的猫，猫最后出现在小区的花园里，我应该调用花园监控查询API，看看花园里有没有猫的照片”→“花园监控查询API返回了空值：{‘status’: ‘success’, ‘data’: []}”→“花园监控查询API没有找到猫的照片，我应该再调用一次花园监控查询API”→…——这验证了我们的猜测，小红确实是在无限循环，原因可能是花园监控查询API一直返回空值，小红的Agent设置了无限重试机制，或者重试次数没有上限，而且小红的Agent没有设置“如果工具返回空值超过3次，就找用户要更多的线索”的逻辑。

你看，可视化Dashboard（Dashboard）就像一个超级放大镜，能让你快速发现异常、定位故障位置、找到根因——这样以后再发生Agent崩溃或死循环的案件，你就能在10秒内定位故障会话，1分钟内找到根因了！

核心概念之间的关系（用小学生能理解的比喻）

全链路追踪（Traces）、指标数据（Metrics）、日志数据（Logs）、可视化Dashboard（Dashboard）就像一个侦探破案的团队：

• 可视化Dashboard（Dashboard）是队长：它负责把所有队员收集到的信息整合在一起，展示给侦探看，让侦探一目了然地看到整个案件过程。
• 全链路追踪（Traces）是行动组组长：它负责记录私家侦探（Agent）的完整行动轨迹，让侦探知道私家侦探从哪里出发、走了哪条路、最后在哪里失踪/徘徊。
• 指标数据（Metrics）是统计组组长：它负责记录私家侦探（Agent）的统计信息，让侦探知道私家侦探的行为频率、时长、成功率，如果有异常，就及时报告给队长（Dashboard）。
• 日志数据（Logs）是情报组组长：它负责记录私家侦探（Agent）的详细事件，让侦探知道私家侦探为什么要走这条路、为什么要见这个人、为什么要做这件事，找到根因。

这个团队的协作流程是这样的：

1. 统计组组长（Metrics）先发现异常（比如私家侦探的会话数突然下降、工具调用的失败率突然上升），然后报告给队长（Dashboard）。
2. **队长（Dashboard）收到报告后，让行动组组长（Traces）**调出私家侦探（Agent）最后一个会话的完整行动轨迹，让侦探知道私家侦探最后在哪里失踪/徘徊。
3. 侦探看了完整行动轨迹后，让**情报组组长（Logs）**调出私家侦探（Agent）最后一个会话的详细事件，让侦探知道私家侦探为什么会失踪/徘徊，找到根因。
4. 侦探找到根因后，修复问题，然后让**统计组组长（Metrics）**继续监控，确保问题不会再发生。

我们再用刚才失踪案的例子来说明这个协作流程：

1. 统计组组长（Metrics）发现小明昨天下午3点到3点10分之间，会话数突然从1降到0，然后报告给队长（Dashboard）。
2. **队长（Dashboard）收到报告后，让行动组组长（Traces）**调出小明昨天下午最后一个会话的完整行动轨迹，侦探看了后发现小明最后在调用机票支付API，状态是“Pending”。
3. 侦探看了完整行动轨迹后，让**情报组组长（Logs）**调出小明昨天下午最后一个会话的详细事件，侦探看了后发现小明的Agent没有设置超时机制，机票支付API一直没有响应，然后小明就崩溃了。
4. 侦探找到根因后，给小明的Agent设置了超时机制（比如30秒），然后让**统计组组长（Metrics）**继续监控，确保问题不会再发生。

核心概念原理和架构的文本示意图（专业定义）

为了让中级和高级开发者也能看懂，我们再用专业的语言画一个Agent可观测性三支柱架构的文本示意图：

┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│                                          用户层（User Layer）                                    │
│                              （用户通过Web界面、App、API等方式访问Agent）                         │
└─────────────────────────────────────────────┬─────────────────────────────────────────────────┘
                                              │
                                              ▼
┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│                                        Agent应用层（Agent App Layer）                            │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │   LlamaIndex     │  │     LangChain    │  │    AutoGPT Lite  │  │  自定义Agent框架  │  │
│  │     Agent        │  │     Agent        │  │     Agent        │  │                  │  │
│  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │
│           │                       │                       │                       │            │
│           └───────────────────────┴───────────────────────┴───────────────────────┘            │
│                                              │                                                    │
│                                              ▼                                                    │
│                              ┌───────────────────────────────┐                                │
│                              │  OpenTelemetry SDK（埋点层）   │                                │
│                              │  ┌──────────────────────────┐ │                                │
│                              │  │  Traces SDK（采集Traces） │ │                                │
│                              │  └──────────────────────────┘ │                                │
│                              │  ┌──────────────────────────┐ │                                │
│                              │  │  Metrics SDK（采集Metrics）│ │                                │
│                              │  └──────────────────────────┘ │                                │
│                              │  ┌──────────────────────────┐ │                                │
│                              │  │  Logs SDK（采集Logs）     │ │                                │
│                              │  └──────────────────────────┘ │                                │
│                              └───────────────┬───────────────┘                                │
└──────────────────────────────────────────────┼────────────────────────────────────────────────┘
                                               │
                                               ▼
┌───────────────────────────────────────────────────────────────────────────────────────────────┐
│                                  OpenTelemetry Collector（处理层）                              │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │   Receiver（接收）│  │  Processor（处理） │  │   Exporter（导出）│  │  Extensions（扩展）│  │
│  │  从Agent应用层    │  │  过滤、聚合、      │  │  把处理后的数据    │  │  健康检查、        │  │
│  │  接收三支柱数据   │  │  转换三支柱数据   │  │  导出到可观测后端  │  │  服务发现等        │  │
│  └──────────────────┘  └──────────────────┘  └──────────────────┘  └──────────────────┘  │
└─────────────────────────────────────────────┬─────────────────────────────────────────────────┘
                                              │
                          ┌───────────────────┼───────────────────┐
                          │                   │                   │
                          ▼                   ▼                   ▼
┌───────────────────────────────┐ ┌───────────────────────────────┐ ┌───────────────────────────────┐
│   可观测后端：Traces存储      │ │   可观测后端：Metrics存储     │ │   可观测后端：Logs存储        │
│   （Grafana Tempo）           │ │   （Prometheus）              │ │   （Grafana Loki）            │
│   - 存储Traces数据            │ │   - 存储时间序列Metrics数据   │ │   - 存储Logs数据              │
│   - 快速查询Traces的轨迹      │ │   - 用PromQL查询Metrics数据   │ │   - 用LogQL查询Logs数据       │
└───────────────────┬───────────┘ └───────────────────┬───────────┘ └───────────────────┬───────────┘
                    │                                   │                                   │
                    └───────────────────────────────────┼───────────────────────────────────┘
                                                        │
                                                        ▼
                                    ┌───────────────────────────────┐
                                    │   可视化层：Grafana Dashboard  │
                                    │   ┌──────────────────────────┐ │
                                    │   │  实时监控Dashboard        │ │
                                    │   │  - 展示当前活跃会话数     │ │
                                    │   │  - 展示大模型API调用趋势  │ │
                                    │   │  - 展示工具调用趋势       │ │
                                    │   │  - 展示告警信息           │ │
                                    │   └──────────────────────────┘ │
                                    │   ┌──────────────────────────┐ │
                                    │   │  历史故障分析Dashboard    │ │
                                    │   │  - 展示历史故障的分布     │ │
                                    │   │  - 展示历史故障的根因     │ │
                                    │   │  - 展示历史故障的趋势     │ │
                                    │   └──────────────────────────┘ │
                                    │   ┌──────────────────────────┐ │
                                    │   │  告警规则设置            │ │
                                    │   │  - 设置大模型API失败率告警│ │
                                    │   │  - 设置工具调用超时告警   │ │
                                    │   │  - 设置Agent死循环告警    │ │
                                    │   └──────────────────────────┘ │
                                    └───────────────────┬───────────┘
                                                        │
                                                        ▼
                                    ┌───────────────────────────────┐
                                    │   开发者/运维人员              │
                                    │   - 查看Dashboard             │
                                    │   - 定位故障                   │
                                    │   - 找到根因                   │
                                    │   - 修复问题                   │
                                    └───────────────────────────────┘

这个架构的核心原理是：

1. 埋点：在Agent应用层使用OpenTelemetry SDK（或者框架自带的埋点工具，比如LlamaIndex/Trace）采集三支柱数据（Traces、Metrics、Logs）。
2. 处理：把采集到的三支柱数据发送到OpenTelemetry Collector，进行过滤、聚合、转换等处理。
3. 存储：把处理后的三支柱数据分别导出到对应的可观测后端（Traces→Grafana Tempo，Metrics→Prometheus，Logs→Grafana Loki）。
4. 可视化：用Grafana连接这三个可观测后端，制作Dashboard，展示给开发者/运维人员看。
5. 告警：在Grafana里设置告警规则，当指标数据（Metrics）出现异常时，及时通知开发者/运维人员。

Mermaid 流程图（架构图和交互图）

为了让大家更直观地理解这个架构，我们再画两个Mermaid流程图：一个是Agent可观测性三支柱架构图，一个是Agent崩溃与死循环排查的交互图。

Mermaid 架构图（Agent可观测性三支柱架构）

Mermaid 交互图（Agent崩溃与死循环排查的交互流程）