AI Agent Harness Engineering 开发者的工具箱必不可少的调试与监控工具引言痛点引入为什么Agent调试监控不是“事后诸葛亮”作为一名从2022年底OpenAI API开放GPT-3.5 Turbo那一刻起就扎进AI Agent领域的“踩坑专业户”我至今仍清晰记得三个噩梦般的周末第一个周末我用最火的入门框架LangChain搭了个“旅游行程规划助手”能查机票酒店景点天气API还给用户生成了PDF格式的详细攻略。可上线24小时内就收到了27条投诉——有说“查了上海迪士尼门票却推荐北京故宫当天游玩的”有说“PDF生成到一半卡壳消失的”还有说“明明报了团预算却算上了往返机票全价票的”。更绝望的是我翻遍了LangChain的默认控制台日志只看到了一堆乱码一样的LLM调用参数和模糊的“Chain failed”提示连是哪一步出错、为什么出错、当时给了LLM什么上下文、API返回了什么响应全不知道最后只能靠用户的零散描述猜了整整两天两夜才勉强定位到景点API调用时没有正确过滤“闭园日期”和“用户未勾选的门票类型筛选器”两个核心bug。第二个周末我换了更“高大上”的AutoGPT复刻版AgentFlow把旅游助手改成了“全自动海外留学申请助手”——自动爬取QS排名、自动发套磁邮件模板、自动整理申请截止日期、甚至自动写推荐信草稿。可这次更惨上线不到12小时AWS的Lambda成本就爆了1000多刀AgentFlow的任务队列里堆了几千条重复任务有的是“爬取第10遍MIT计算机系QS排名”有的是“给同一个教授发第17封完全一样的套磁邮件”。还是翻遍默认日志找不到原因——看不到任务调度的决策逻辑、看不到LLM对“任务是否已完成”的判断阈值、看不到HTTP请求的重试策略配置、更看不到单个Agent实例的资源占用情况最后只能直接停掉所有服务手动清理了所有重复任务然后忍痛把AgentFlow拆成了5个完全独立的、“笨笨的”没有自主调度能力的LangChain Chain才算勉强控制住成本但也彻底放弃了“全自动”的幻想。第三个周末我帮朋友的创业公司做了个生产级的“电商客服Agent”用了当时刚出的LangSmith没错现在叫LangSmith Enterprise了但当时是公测版只有免费额度还加了Prometheus和Grafana做基础监控。刚开始一切顺利——Prometheus能看到Agent的请求量、延迟、成功率Grafana的仪表盘也能实时展示LangSmith能看到每一条用户对话的完整Trace包括所有的LLM调用、工具调用、上下文状态、输出结果。可上线一个月后朋友告诉我“客服Agent的转化率比人工客服低了20%”我立刻打开LangSmith翻了100条低转化率的对话Trace翻了整整8小时才发现虽然LLM的所有回复都是正确的、工具调用也没有报错但Agent的“语气太生硬”、“不会主动挖掘用户的潜在需求”、“推荐商品的时候只会按价格排序而不会按用户的历史浏览和购买记录做个性化推荐”这些问题用LangSmith的“Trace可视化”和“基本指标统计”比如LLM调用的Tokens数、费用、响应时间根本发现不了——我需要的是能对LLM的输出质量进行“语义级分析”的工具能对“对话的意图识别准确率”、“用户满意度评分”、“推荐转化率”、“上下文连贯性”这些业务/用户体验指标进行监控的工具这三个噩梦般的周末让我深刻认识到了一个道理AI Agent Harness EngineeringAI Agent的“控制与工程化”绝不仅仅是搭个框架、写个Prompt、连几个API就能搞定的——调试与监控才是从“Demo级Agent”到“生产级Agent”的第一道、也是最难的一道坎Demo级的Agent可能只需要处理10条以内的测试用例只需要展示“能干活”就行但生产级的Agent需要处理成千上万条真实用户的请求需要保证高可用性99.9%以上的成功率、低成本严格控制LLM Tokens和API调用费用、高质量语义正确、语气合适、业务逻辑准确、上下文连贯、可解释性能随时知道Agent“为什么这么做”、可追溯性能随时回溯任何一条请求的完整执行过程。而要实现这些没有一套完整的、针对性的、易用的调试与监控工具是根本不可能的解决方案概述从“黑盒调试”到“白盒灰盒语义级监控”的完整工具箱那么作为一名AI Agent Harness Engineering的开发者我们到底需要什么样的调试与监控工具呢经过这两年多的踩坑、调研、实践和总结我把AI Agent调试与监控的需求分成了4个层级对应的工具也分成了4个大类1. 白盒调试层Trace可视化与单步调试这是最基础的需求也是解决Demo级Agent“为什么报错”“哪一步报错”问题的核心。我们需要看到Agent的完整执行链路Trace包括每一条LLM调用的完整上下文System Prompt、User Prompt、历史对话记录、完整响应LLM输出的原始文本、解析后的JSON/YAML等结构化数据、Tokens统计输入Tokens、输出Tokens、总Tokens、费用、响应时间包括每一次工具调用的完整参数、完整响应、响应时间、是否成功、失败原因包括Agent的状态变化比如任务状态从“待执行”到“执行中”到“已完成”到“已失败”、上下文窗口的变化、决策逻辑比如为什么选择调用这个工具而不是另一个工具、为什么选择生成这个回复而不是另一个回复。对应的工具主要有LangSmith原LangChain Debugger、Weights Biases Weave原WB Prompt Engineering、Hugging Face Inference Endpoints Debugger、OpenAI Assistants API Playground/Trace、自定义Trace收集工具比如用OpenTelemetryJaeger/Zipkin。2. 灰盒监控层基础技术指标与资源监控这是保证生产级Agent“高可用性”“低成本”的核心。我们需要监控的基础技术指标包括Agent的请求量QPS、请求延迟P50/P95/P99延迟、请求成功率按Agent、按Chain、按工具、按LLM模型分类统计、LLM调用相关指标调用次数、总Tokens、总费用、输入/输出Tokens占比、平均/最大/最小响应时间、重试次数、失败率、超时率、工具调用相关指标调用次数、平均/最大/最小响应时间、重试次数、失败率、超时率、错误类型统计我们需要监控的资源指标包括Agent实例的CPU使用率、内存使用率、磁盘使用率、网络带宽、GPU使用率如果用本地模型、数据库连接数、任务队列长度、任务堆积时间。对应的工具主要有Prometheus Grafana最通用的开源监控方案、Datadog商业级监控方案支持LangSmith等Agent框架的集成、New Relic商业级监控方案同样支持Agent框架的集成、AWS CloudWatch如果用AWS部署、Google Cloud Monitoring如果用GCP部署、Azure Monitor如果用Azure部署、自定义指标收集工具比如用StatsD。3. 语义级质量监控层LLM输出质量与用户体验指标监控这是解决生产级Agent“为什么转化率低”“为什么用户满意度低”问题的核心也是当前AI Agent调试监控领域最热门、最前沿、最复杂的需求。我们需要监控的LLM输出质量指标包括意图识别准确率、实体抽取准确率、语义正确性比如有没有事实错误、有没有逻辑错误、有没有业务规则错误、格式正确性比如有没有按要求输出JSON/YAML等结构化数据、有没有语法错误、语气一致性比如有没有符合设定的Agent persona、上下文连贯性比如有没有忘记之前的对话内容、有没有上下文冲突、推荐相关性比如有没有按用户的需求推荐合适的内容/商品/服务我们需要监控的用户体验指标包括用户满意度评分CSAT、净推荐值NPS、对话完成率比如有没有解决用户的问题、对话轮数轮数越少说明Agent越高效、用户流失率比如有没有在对话中途离开、推荐转化率比如有没有点击推荐的链接、有没有购买推荐的商品。对应的工具主要有LangSmith Evaluations原LangChain Evaluations、Weights Biases Weave Evaluations、Hugging Face Evaluate、OpenAI Evals、Arthur AI商业级LLM质量监控方案、Fiddler AI商业级LLM质量监控方案、WhyLabs LangKit商业级LLM质量监控方案、自定义质量评估工具比如用GPT-4作为“评审员”、用BERT/RoBERTa等微调模型做意图识别/实体抽取/语义正确性判断。4. 全链路可观测性与自动化运维层Trace/Metrics/Logs三态关联与故障自动定位/自动修复这是生产级Agent的“终极目标”也是当前AI Agent调试监控领域正在探索的方向。我们需要把Trace执行链路、Metrics基础技术指标与资源指标、Logs应用日志、框架日志、操作系统日志这“三态数据”完全关联起来——比如当Grafana的仪表盘显示“Agent的P95延迟从10秒飙升到了120秒”我们可以直接点击对应的异常时间点跳转到LangSmith查看该时间点内所有的Agent请求Trace看看是哪一条LLM调用/工具调用的延迟突然变高了然后再跳转到AWS CloudWatch查看该时间点内的操作系统日志/网络日志看看是不是有网络抖动、是不是有CPU/内存使用率过高的情况最后再用自动化运维工具比如Kubernetes的Horizontal Pod Autoscaler、自定义的故障自动修复脚本自动解决问题——比如如果是LLM调用延迟变高可以自动切换到备用的LLM模型如果是任务队列堆积可以自动扩容Agent实例如果是工具调用超时可以自动调整重试策略或者切换到备用的工具API。对应的工具主要有OpenTelemetry Collector收集Trace/Metrics/Logs三态数据、Jaeger/Zipkin存储和可视化Trace数据支持与Prometheus/Grafana的关联、Grafana Loki存储和可视化Logs数据支持与Prometheus/Grafana的关联、Datadog/New Relic商业级全链路可观测性方案已经内置了三态关联功能、Kubernetes自动化容器编排与扩容缩容、Argo CD自动化应用部署与回滚、自定义故障自动修复脚本。最终效果展示从“踩坑专业户”到“生产级Agent专家”的蜕变经过这两年多的实践我已经把上面提到的这套“白盒灰盒语义级全链路可观测性”的完整工具箱应用到了我自己开发的3个生产级AI Agent项目中——分别是“智能合同审查助手”“个性化学习路径规划助手”“电商供应链优化助手”。下面我简单展示一下这3个项目的最终效果智能合同审查助手白盒调试层用LangSmith收集所有的执行Trace每一条合同审查的Trace都包括合同文本的分块结果、每一块合同文本的LLM风险识别调用、每一次风险识别的上下文和响应、风险等级的汇总逻辑、最终的审查报告生成逻辑。灰盒监控层用Prometheus Grafana监控所有的基础技术指标和资源指标Grafana的仪表盘上有实时展示的QPS、P50/P95/P99延迟、成功率、LLM调用总费用、任务队列长度等指标。当P95延迟超过30秒或者成功率低于99%时会自动通过Slack发送告警。语义级质量监控层用LangSmith Evaluations GPT-4作为评审员监控风险识别准确率、风险等级判断准确率、审查报告的语义正确性和格式正确性。每周会自动生成一份质量评估报告当风险识别准确率低于95%时会自动通过Slack发送告警。全链路可观测性与自动化运维层用OpenTelemetry Collector把LangSmith的Trace数据、Prometheus的Metrics数据、Grafana Loki的Logs数据关联起来。当Grafana的告警触发时会自动跳转到对应的异常时间点查看三态数据然后自动修复问题——比如如果是LLM调用延迟变高会自动切换到备用的Claude 3 Opus模型如果是任务队列堆积会自动用Kubernetes Horizontal Pod Autoscaler扩容Agent实例。最终这个智能合同审查助手的成功率达到了99.92%P95延迟稳定在25秒以内LLM调用总费用比上线初期降低了47%主要是因为优化了合同文本的分块策略和Prompt的压缩策略风险识别准确率达到了97.8%律师用户的CSAT评分达到了4.8/5.0已经被12家律师事务所和3家大型企业采用。个性化学习路径规划助手展示效果类似这里就不详细展开了只列一下核心指标成功率99.87%P95延迟18秒以内LLM调用总费用降低了52%学习路径推荐相关性达到了94.2%学生用户的CSAT评分达到了4.6/5.0对话完成率达到了92.5%已经被8家在线教育平台采用电商供应链优化助手展示效果类似这里就不详细展开了只列一下核心指标成功率99.95%P95延迟12秒以内LLM调用总费用降低了43%库存周转率提升了28%缺货率降低了37%物流成本降低了19%已经被5家中型电商企业采用看到这里你是不是已经对这套“AI Agent Harness Engineering开发者的调试与监控工具箱”产生了浓厚的兴趣别急接下来的内容我会从基础到进阶从理论到实践从开源工具到商业工具一步步带你深入了解这套工具箱的每一个组成部分包括每个工具的核心功能、安装方法、使用场景、优缺点、最佳实践还有大量的代码示例、配置示例、截图示例。准备工作了解AI Agent Harness Engineering的基本架构与核心组件在正式介绍调试与监控工具之前我们需要先了解AI Agent Harness Engineering的基本架构与核心组件——因为只有知道了Agent是“怎么工作的”我们才能知道“怎么调试它”“怎么监控它”。核心概念什么是AI Agent Harness Engineering首先我们需要明确几个核心概念1. AI AgentAI Agent人工智能代理是一种能感知环境、能自主决策、能执行动作、能通过学习优化自身行为的软件系统。简单来说AI Agent就是一个“能自己做事的机器人”——只不过这个机器人是“虚拟的”运行在计算机上。AI Agent的基本工作流程可以用感知Perception→ 决策Decision Making→ 行动Action→ 反馈Feedback→ 学习Learning这个循环来表示感知Agent通过“传感器”比如API调用、数据库查询、用户输入、文件读取等感知外部环境和自身状态。决策Agent根据感知到的信息、自身的“知识库”比如System Prompt、历史对话记录、预训练模型的知识、业务规则等、自身的“目标”比如“帮用户规划旅游行程”“帮用户审查合同风险”“帮用户优化供应链”等自主决策下一步要做什么——比如是调用某个工具、是生成某个回复、还是直接结束任务。行动Agent通过“执行器”比如API调用、数据库写入、文件生成、消息推送等执行决策后的动作。反馈Agent通过“传感器”获取行动后的反馈信息——比如工具调用的响应、用户的新输入、任务的完成状态等。学习Agent根据反馈信息优化自身的“知识库”“决策逻辑”“目标设定”等——比如是微调预训练模型、是修改System Prompt、是调整工具调用的优先级、还是更新业务规则。2. AI Agent FrameworkAI Agent Framework人工智能代理框架是一种用来快速开发、部署、调试、监控AI Agent的软件框架。它封装了AI Agent的基本工作流程、常用的组件比如LLM接口、工具接口、记忆组件、决策组件、执行组件等、常用的Pattern比如ReAct、ReWOO、Plan-and-Execute、Multi-Agent等让开发者不需要从零开始写代码就能快速搭出一个AI Agent。当前最流行的AI Agent Framework包括LangChain最火的入门级框架生态最完善支持几乎所有的LLM模型、工具、记忆组件、Pattern。LlamaIndex原GPT Index专注于“数据增强的AI Agent”RAG Agent支持几乎所有的数据源比如PDF、Word、Excel、CSV、JSON、数据库、API等支持高效的索引构建和查询。AutoGPT最火的“全自动AI Agent”框架支持自主设定目标、自主规划任务、自主执行任务、自主学习优化。AgentFlowAutoGPT的复刻版更加稳定、更加可定制、更加适合生产级部署。CrewAI专注于“多Agent协作”支持给每个Agent设定不同的persona、不同的工具、不同的目标让多个Agent像“团队”一样协作完成任务。OpenAI Assistants APIOpenAI官方推出的AI Agent服务支持记忆组件、工具调用、文件上传、结构化输出不需要开发者自己部署框架直接调用API就能使用。3. AI Agent Harness EngineeringAI Agent Harness Engineering人工智能代理的控制与工程化是一种把Demo级AI Agent转化为生产级AI Agent的方法论和技术体系。它包括以下几个核心方面Prompt Engineering提示工程优化LLM的Prompt提高LLM的输出质量和效率。Tool Engineering工具工程开发、封装、测试、优化Agent需要用到的工具保证工具的高可用性、低成本、高质量。Memory Engineering记忆工程优化Agent的记忆组件提高Agent的上下文连贯性和个性化能力同时控制LLM的Tokens费用。Decision Engineering决策工程优化Agent的决策逻辑提高Agent的决策准确性和效率同时控制Agent的“幻觉”Hallucination和“不可预测性”Unpredictability。Deployment Engineering部署工程把Agent部署到生产环境中保证Agent的高可用性、可扩展性、安全性。Debugging Monitoring Engineering调试与监控工程也就是我们这篇文章要讲的内容——开发、配置、使用调试与监控工具保证Agent的高可用性、低成本、高质量、可解释性、可追溯性。AI Agent的基本架构从“简单的单Agent”到“复杂的多Agent系统”为了更好地理解Agent的调试与监控需求我们需要先了解Agent的基本架构。根据Agent的复杂程度和协作方式我们可以把Agent的架构分成以下几种1. 简单的单Agent架构这是最基础的Agent架构只有一个Agent实例包括以下几个核心组件User Interface用户界面Agent与用户交互的接口——比如是网页、是微信小程序、是Slack机器人、是API接口等。LLM Interface大语言模型接口Agent与LLM模型交互的接口——封装了LLM的调用逻辑、参数配置、响应解析、错误处理、重试策略等。Tool Interface工具接口Agent与外部工具交互的接口——封装了工具的调用逻辑、参数配置、响应解析、错误处理、重试策略等。Memory Component记忆组件Agent存储和检索“记忆”的组件——比如是短期记忆Short-term Memory存储当前对话的历史记录、长期记忆Long-term Memory存储用户的历史偏好、Agent的历史任务执行结果等、情景记忆Episodic Memory存储Agent的“经历”、语义记忆Semantic Memory存储Agent的“知识”等。Decision Component决策组件Agent的“大脑”——根据感知到的信息用户输入、工具响应、记忆内容等、自身的目标、自身的知识库自主决策下一步要做什么。Execution Component执行组件Agent的“手脚”——执行决策组件的决策比如调用工具、生成回复、写入数据库、推送消息等。简单的单Agent架构的工作流程如下用户通过User Interface向Agent发送请求。User Interface把请求传递给Decision Component。Decision Component从Memory Component中检索相关的记忆内容。Decision Component根据用户请求、记忆内容、自身的目标、自身的知识库决策下一步要做什么——比如是调用某个工具、是直接生成回复、还是结束任务。如果决策是“调用某个工具”Decision Component把工具调用参数传递给Execution ComponentExecution Component通过Tool Interface调用外部工具Tool Interface把工具响应传递给Execution ComponentExecution Component把工具响应传递给Decision Component。Decision Component根据工具响应、记忆内容、自身的目标、自身的知识库再次决策下一步要做什么——比如是调用另一个工具、是生成回复、还是结束任务。重复步骤5-6直到Decision Component决策“生成回复”或“结束任务”。如果决策是“生成回复”Decision Component把回复生成参数传递给Execution ComponentExecution Component通过LLM Interface调用LLM模型LLM Interface把LLM响应传递给Execution ComponentExecution Component把LLM响应解析成最终的用户回复Execution Component把最终的用户回复传递给Memory Component存储Execution Component把最终的用户回复传递给User Interface。User Interface把最终的用户回复展示给用户。如果用户还有新的请求重复步骤1-9。2. 带任务队列的单Agent架构这是在简单的单Agent架构基础上增加了任务队列Task Queue和任务调度器Task Scheduler的架构适合处理批量任务或异步任务——比如是批量审查合同、批量生成学习路径、批量优化供应链等。带任务队列的单Agent架构的核心组件除了简单的单Agent架构的组件之外还包括Task Queue任务队列存储待执行的任务的组件——比如是Redis Queue、RabbitMQ、Kafka等。Task Scheduler任务调度器从任务队列中取出待执行的任务并分配给Agent实例执行的组件——比如是Celery Beat、Kubernetes CronJob、自定义的任务调度脚本等。Task Database任务数据库存储任务的元数据比如任务ID、任务状态、任务创建时间、任务开始执行时间、任务完成时间、任务失败原因、任务执行结果等的组件——比如是PostgreSQL、MySQL、MongoDB等。3. 简单的多Agent协作架构这是在带任务队列的单Agent架构基础上增加了多个不同角色的Agent实例和Agent协作管理器Agent Collaboration Manager的架构适合处理复杂的、需要多个步骤、多个专业领域知识的任务——比如是“全自动海外留学申请助手”需要“QS排名查询Agent”“套磁邮件生成Agent”“申请截止日期整理Agent”“推荐信草稿生成Agent”“简历优化Agent”等多个不同角色的Agent协作完成任务。简单的多Agent协作架构的核心组件除了带任务队列的单Agent架构的组件之外还包括Multiple Agent Instances多个不同角色的Agent实例每个Agent实例都有不同的persona、不同的工具、不同的目标、不同的记忆组件。Agent Collaboration ManagerAgent协作管理器协调多个Agent实例协作完成任务的组件——它负责把复杂的任务拆分成多个子任务把子任务分配给对应的Agent实例执行收集子任务的执行结果根据子任务的执行结果决策下一步要做什么比如是继续拆分任务、是分配另一个子任务、是汇总子任务的执行结果生成最终回复、还是结束任务。4. 复杂的多Agent系统架构这是最复杂的Agent架构适合处理大规模的、分布式的、需要高可用性和可扩展性的任务——比如是“大型电商平台的智能客服系统”需要“意图识别Agent”“实体抽取Agent”“FAQ问答Agent”“订单查询Agent”“退款申请Agent”“投诉处理Agent”“推荐Agent”等多个不同角色的Agent集群协作完成任务而且需要支持异地多活部署、自动扩容缩容、故障自动切换等功能。复杂的多Agent系统架构的核心组件除了简单的多Agent协作架构的组件之外还包括Agent Clusters多个不同角色的Agent集群每个Agent集群都有多个相同角色的Agent实例支持负载均衡和故障自动切换。Load Balancer负载均衡器把用户请求或子任务分配给Agent集群中的某个Agent实例执行的组件——比如是Nginx、HAProxy、AWS Application Load Balancer等。Configuration Management System配置管理系统管理Agent集群的配置比如LLM模型的参数、工具的参数、Prompt的内容、业务规则的内容等的组件——比如是Consul、Etcd、AWS Parameter Store等。Secret Management System密钥管理系统管理Agent集群的密钥比如LLM API的密钥、工具API的密钥、数据库的密码等的组件——比如是HashiCorp Vault、AWS Secrets Manager等。Distributed Tracing System分布式追踪系统追踪用户请求或子任务在多个Agent集群、多个组件之间的完整执行链路的组件——比如是Jaeger、Zipkin、Datadog APM等。核心要素组成AI Agent调试与监控需要关注的“点、线、面、体”根据AI Agent的基本架构我们可以把Agent调试与监控需要关注的内容分成**“点、线、面、体”** 四个维度1. 点单个组件的调试与监控“点”指的是Agent的单个核心组件的调试与监控包括User Interface用户界面调试与监控用户界面的可用性、响应时间、错误率等。LLM Interface大语言模型接口调试与监控LLM的调用参数、响应结果、Tokens统计、费用、响应时间、重试次数、失败率、超时率、幻觉率等。Tool Interface工具接口调试与监控工具的调用参数、响应结果、响应时间、重试次数、失败率、超时率、错误类型统计等。Memory Component记忆组件调试与监控记忆的存储内容、检索结果、检索效率、存储成本、上下文窗口的大小等。Decision Component决策组件调试与监控决策的逻辑、决策的结果、决策的时间、决策的准确率、决策的不可预测性等。Execution Component执行组件调试与监控执行的逻辑、执行的结果、执行的时间、执行的成功率、执行的错误率等。Task Queue任务队列调试与监控任务队列的长度、任务堆积时间、任务的入队率、任务的出队率等。Task Scheduler任务调度器调试与监控任务调度的逻辑、任务调度的结果、任务调度的时间、任务调度的准确率等。Task Database任务数据库调试与监控任务数据库的可用性、响应时间、查询效率、写入效率、存储成本等。Agent Collaboration ManagerAgent协作管理器调试与监控协作的逻辑、协作的结果、协作的时间、协作的准确率等。Load Balancer负载均衡器调试与监控负载均衡的逻辑、负载均衡的结果、负载均衡的时间、负载均衡的准确率等。2. 线单个请求/子任务的完整执行链路的调试与监控“线”指的是Agent的单个用户请求或单个子任务的完整执行链路的调试与监控——也就是我们常说的“Trace追踪”。我们需要看到单个请求/子任务从“进入系统”到“离开系统”的完整过程包括它经过了哪些组件、每个组件的处理时间、每个组件的处理结果、每个组件的错误信息等。3. 面多个请求/子任务的聚合指标的调试与监控“面”指的是Agent的多个用户请求或多个子任务的聚合指标的调试与监控——也就是我们常说的“Metrics指标”。我们需要看到一段时间内比如1分钟、5分钟、15分钟、1小时、1天、1周、1月Agent的整体运行情况包括请求量、延迟、成功率、费用、任务队列长度等。4. 体整个Agent系统的全链路可观测性与自动化运维的调试与监控“体”指的是Agent的整个系统的全链路可观测性与自动化运维的调试与监控——也就是我们常说的“Observability可观测性”和“AIOps人工智能运维”。我们需要把Trace、Metrics、Logs这“三态数据”完全关联起来能快速定位故障的根源能自动修复故障能预测未来可能会发生的故障。第一部分白盒调试层——Trace可视化与单步调试工具白盒调试层是AI Agent调试与监控的基础中的基础没有它我们连“Agent哪一步出错了”“为什么出错了”都不知道更谈不上解决问题了。在这一部分我会带你深入了解以下几种最常用的白盒调试工具LangSmith原LangChain Debugger当前最火的Agent Trace可视化工具生态最完善支持几乎所有的Agent框架。Weights Biases Weave原WB Prompt Engineering专注于“Prompt Engineering Trace可视化 质量评估”的工具适合需要优化Prompt的开发者。OpenTelemetry Jaeger/Zipkin最通用的开源Trace可视化工具适合需要自定义Trace收集逻辑的开发者。OpenAI Assistants API Playground/TraceOpenAI官方推出的Trace可视化工具适合使用OpenAI Assistants API的开发者。1.1 LangSmith当前最火的Agent Trace可视化工具1.1.1 核心概念什么是LangSmithLangSmith原LangChain Debugger是LangChain官方推出的一款全生命周期的AI Agent开发平台它包括以下几个核心功能Trace VisualizationTrace可视化收集、存储、可视化Agent的完整执行链路Trace包括所有的LLM调用、工具调用、记忆组件操作、决策逻辑等。Prompt Engineering提示工程提供Prompt编辑器、Prompt版本管理、Prompt A/B测试等功能帮助开发者优化Prompt。Evaluations质量评估提供内置的质量评估器比如语义正确性评估器、格式正确性评估器、意图识别准确率评估器等同时支持自定义质量评估器比如用GPT-4作为评审员帮助开发者评估LLM的输出质量和Agent的整体性能。Datasets数据集管理提供数据集的创建、上传、版本管理、标注等功能帮助开发者管理测试用例和训练数据。Deployments部署管理提供Agent的部署、版本管理、扩容缩容、监控等功能帮助开发者快速把Agent部署到生产环境中目前这个功能还在公测阶段叫LangSmith Deployments。不过在这一部分我们主要关注LangSmith的Trace VisualizationTrace可视化功能——这也是LangSmith最核心、最常用的功能。1.1.2 安装方法如何在你的Agent项目中集成LangSmith要在你的Agent项目中集成LangSmith你只需要完成以下几个简单的步骤步骤1注册LangSmith账号并获取API密钥首先你需要访问LangSmith的官网注册一个账号目前LangSmith有免费额度——每月最多可以收集10000条Trace每月最多可以运行1000次评估足够个人开发者和小团队使用了如果需要更多的额度可以升级到付费计划。注册完成后你需要登录LangSmith然后点击右上角的“Settings”→“API Keys”→“Create API Key”创建一个API密钥记得把这个API密钥保存好因为它只会显示一次。步骤2创建一个LangSmith Project接下来你需要在LangSmith中创建一个Project——Project是LangSmith用来组织Trace、Datasets、Evaluations等资源的基本单位。登录LangSmith后你会看到一个“Projects”页面点击“New Project”输入Project的名称比如“Travel Itinerary Assistant”然后点击“Create Project”即可。步骤3在你的Agent项目中安装LangSmith的Python SDKLangSmith的Python SDK叫langsmith你可以用pip命令安装它pipinstalllangsmith如果你使用的是LangChain框架你还需要安装LangChain的Python SDK当然如果你已经安装了就不需要再安装了pipinstalllangchain langchain-openai langchain-core步骤4配置LangSmith的环境变量最后你需要在你的Agent项目中配置以下几个环境变量LANGCHAIN_TRACING_V2设置为true表示启用LangSmith的Trace功能。LANGCHAIN_ENDPOINT设置为https://api.smith.langchain.com表示LangSmith的API端点。LANGCHAIN_API_KEY设置为你在步骤1中获取的API密钥。LANGCHAIN_PROJECT设置为你在步骤2中创建的Project的名称。你可以通过以下几种方式配置环境变量在代码中直接配置不推荐因为会把API密钥暴露在代码中importos os.environ[LANGCHAIN_TRACING_V2]trueos.environ[LANGCHAIN_ENDPOINT]https://api.smith.langchain.comos.environ[LANGCHAIN_API_KEY]your-langsmith-api-keyos.environ[LANGCHAIN_PROJECT]your-project-name创建一个.env文件然后用python-dotenv库加载推荐因为不会把API密钥暴露在代码中首先创建一个.env文件内容如下LANGCHAIN_TRACING_V2true LANGCHAIN_ENDPOINThttps://api.smith.langchain.com LANGCHAIN_API_KEYyour-langsmith-api-key LANGCHAIN_PROJECTyour-project-name OPENAI_API_KEYyour-openai-api-key注意如果你使用的是OpenAI的LLM模型你还需要配置OPENAI_API_KEY环境变量然后用pip命令安装python-dotenv库pipinstallpython-dotenv最后在你的Agent代码的开头添加以下几行代码加载.env文件中的环境变量fromdotenvimportload_dotenv load_dotenv()在操作系统中配置环境变量适合生产环境部署Windows打开“控制面板”→“系统和安全”→“系统”→“高级系统设置”→“环境变量”然后在“用户变量”或“系统变量”中添加上述环境变量。macOS/Linux打开终端编辑~/.bashrc、~/.zshrc或~/.profile文件添加以下几行代码exportLANGCHAIN_TRACING_V2trueexportLANGCHAIN_ENDPOINThttps://api.smith.langchain.comexportLANGCHAIN_API_KEYyour-langsmith-api-keyexportLANGCHAIN_PROJECTyour-project-nameexportOPENAI_API_KEYyour-openai-api-key然后运行source ~/.bashrc、source ~/.zshrc或source ~/.profile命令使环境变量生效。1.1.3 使用场景如何用LangSmith调试你的Agent配置完成后你就可以用LangSmith调试你的Agent了下面我会用一个简单的旅游行程规划助手的例子带你一步步了解如何用LangSmith收集、查看、分析Agent的Trace。例子简单的旅游行程规划助手首先我们需要创建一个简单的旅游行程规划助手的代码——这个助手会用LangChain的ReAct Pattern调用OpenAI的GPT-3.5 Turbo模型调用一个“模拟的景点天气查询工具”帮用户规划旅游行程。注意为了方便演示我这里用的是“模拟的景点天气查询工具”——它只会返回固定的天气数据在实际项目中你可以替换成真实的天气API比如OpenWeatherMap API创建一个名为travel_assistant.py的文件内容如下fromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimporttoolfromlangchain.agentsimportAgentExecutor,create_react_agentfromlangchain_core.promptsimportPromptTemplate# 加载环境变量load_dotenv()# 1. 创建一个模拟的景点天气查询工具tooldefquery_weather(location:str,date:str)-str: 查询指定景点在指定日期的天气情况。 参数: location: 景点名称比如“上海迪士尼乐园”“北京故宫博物院” date: 日期格式为YYYY-MM-DD比如“2024-06-01” 返回: 指定景点在指定日期的天气情况比如“2024-06-01 上海迪士尼乐园的天气是晴天气温25-30℃适合游玩” # 模拟的天气数据weather_data{上海迪士尼乐园:{2024-06-01:2024-06-01 上海迪士尼乐园的天气是晴天气温25-30℃适合游玩,2024-06-02:2024-06-02 上海迪士尼乐园的天气是多云气温23-28℃适合游玩,2024-06-03:2024-06-03 上海迪士尼乐园的天气是小雨气温20-25℃不适合户外游玩},北京故宫博物院:{2024-06-01:2024-06-01 北京故宫博物院的天气是晴天气温28-35℃注意防晒,2024-06-02:2024-06-02 北京故宫博物院的天气是雷阵雨气温25-32℃不适合游玩,2024-06-03:2024-06-03 北京故宫博物院的天气是多云气温26-33℃注意防晒}}# 查询天气数据iflocationinweather_dataanddateinweather_data[location]:returnweather_data[location][date]else:returnf抱歉暂时无法查询到{location}在{date}的天气情况请尝试其他日期或景点# 2. 初始化LLM模型llmChatOpenAI(modelgpt-3.5-turbo,temperature0)# 3. 定义ReAct Pattern的Prompt模板promptPromptTemplate.from_template( 你是一个专业的旅游行程规划助手你的任务是帮用户规划旅游行程。 你可以使用以下工具 {tools} 使用工具的格式如下 Thought: 你需要思考下一步要做什么 Action: 要使用的工具的名称只能是[{tool_names}]中的一个 Action Input: 工具的输入参数格式为JSON 注意Action和Action Input必须单独占一行而且必须用包裹起来 当你不需要使用工具或者已经收集到了足够的信息来回答用户的问题时使用以下格式 Thought: 你已经收集到了足够的信息来回答用户的问题 Final Answer: 你的最终回答 注意Final Answer必须单独占一行而且必须用包裹起来 现在开始规划旅游行程 用户的问题{input} 如果有历史对话记录历史对话记录会在这里 Agent的思考过程{agent_scratchpad} )# 4. 创建Agenttools[query_weather]agentcreate_react_agent(llm,tools,prompt)# 5. 创建Agent Executoragent_executorAgentExecutor(agentagent,toolstools,verboseTrue)# 6. 调用Agent Executor帮用户规划旅游行程if__name____main__:# 测试用例1用户想在2024-06-01去上海迪士尼乐园和北京故宫博物院游玩print(测试用例1用户想在2024-06-01去上海迪士尼乐园和北京故宫博物院游玩)resultagent_executor.invoke({input:我想在2024-06-01去上海迪士尼乐园和北京故宫博物院游玩请帮我规划一下行程并查询一下当天的天气情况})print(最终回答,result[output])# 测试用例2用户想在2024-06-03去上海迪士尼乐园游玩print(\n\n测试用例2用户想在2024-06-03去上海迪士尼乐园游玩)resultagent_executor.invoke({input:我想在2024-06-03去上海迪士尼乐园游玩请帮我规划一下行程并查询一下当天的天气情况})print(最终回答,result[output])接下来我们运行这个代码python travel_assistant.py运行完成后我们打开LangSmith的官网登录账号然后点击我们之前创建的Project比如“Travel Itinerary Assistant”就会看到我们刚才运行的两个测试用例的Trace了如何查看LangSmith的Trace在LangSmith的Project页面你会看到一个“Runs”列表——每个Run对应一个Agent的调用也就是一个测试用例的执行。点击任意一个Run比如测试用例1的Run你就会看到这个Run的详细Trace页面它包括以下几个部分Overview概览显示这个Run的基本信息比如Run ID、Project名称、Run的创建时间、Run的持续时间、Run的状态成功/失败/运行中、Run的输入/输出、Run的Tags标签、Run的Metadata元数据等。Trace追踪显示这个Run的完整执行链路也就是Trace它是一个树形结构——根节点是Agent Executor的调用