自用 Agent 全面功能测试实战：从对话、工具调用到记忆与定时任务

1. 为什么我要给自己的 Agent 做一次全面功能测试说实话做 Agent 这件事最怕的不是功能少而是功能多了之后自己都不知道哪个环节在什么时候会掉链子。我手头这个自用 Agent 从最初的一个简单对话壳子慢慢长成了一个能处理日程、能查资料、能跑脚本、能管文件、还能定时触发任务的“多面手”。功能越堆越多表面上看着挺美实际上每次加一个新能力心里就多一分不踏实——因为你永远不知道新加的模块会不会把旧模块的上下文搅乱也不知道某个工具调用在特定输入下会不会直接卡死。所以这次我下定决心把手头这个 Agent 从头到尾做一次系统性的功能测试。不是那种跑几个 demo 就完事的“表演式测试”而是真正把它当成一个要长期依赖的工具去压榨它的边界、暴露它的短板。这篇文章就是这次测试的完整记录包括我怎么设计测试用例、怎么搭建测试环境、每个功能模块具体怎么测、遇到了哪些坑、最后怎么定位和解决的。如果你也在自己折腾 Agent不管你是刚起步还是已经堆了一堆功能这篇内容应该都能给你一些直接能抄的作业。我会尽量把每个步骤写清楚把每个判断背后的理由讲明白让你看完就能在自己的 Agent 上复现这套测试流程。2. 测试前的整体设计与思路拆解2.1 先想清楚自用 Agent 的测试和产品级测试有什么不同很多人一提到测试脑子里第一反应就是写单元测试、跑覆盖率、搞 CI/CD。这套东西放在团队协作的产品上没问题但放在自用 Agent 上逻辑完全不一样。自用 Agent 的核心特点是需求随时变、功能边界模糊、没有明确的验收标准。你今天觉得这个功能够用了明天可能就想加个新工具进去后天又觉得某个流程太绕想重构。所以我的测试思路不是追求“全覆盖”而是追求“关键路径的确定性”。具体来说我把测试目标拆成三层第一层基础可用性。Agent 能不能稳定启动、能不能正确加载配置、能不能在没有任何外部依赖的情况下完成一次最简单的对话。这是底线底线不稳后面全是白搭。第二层核心功能链路。每个功能模块单独跑通并且验证模块之间的衔接是否顺畅。比如工具调用之后上下文有没有正确传递、多轮对话中记忆有没有丢失、定时任务触发时状态是否一致。第三层边界与异常。故意输入超长文本、故意让工具返回错误、故意断开网络、故意并发触发多个任务看 Agent 怎么反应。这一层最能暴露问题也最容易被忽略。我的经验是自用 Agent 出问题八成不是出在“正常路径”上而是出在“你以为不会发生”的边界情况上。所以第三层的测试权重应该给得最高。2.2 测试环境的搭建原则隔离、可复现、可观测测试环境这块我踩过不少坑。最开始我直接在生产环境上测结果就是测试数据把真实数据污染了排查问题的时候根本分不清是测试引入的还是原本就有的。后来我学乖了专门搭了一套隔离环境。具体做法是配置隔离用独立的配置文件所有 API Key、数据库连接、文件路径都指向测试专用的资源。我习惯用环境变量来区分比如AGENT_ENVtest的时候自动加载config.test.yaml。数据隔离测试用的记忆存储、日志文件、临时文件全部放在单独的目录下测试结束后可以一键清理。我一般会在项目根目录下建一个.test-workspace文件夹所有测试产生的脏数据都往里面扔。可观测性这是最关键的一环。Agent 的内部状态很难直接看到所以我强制要求所有关键节点都打日志包括输入接收、意图识别、工具选择、工具调用参数、工具返回结果、最终输出。日志格式统一用 JSON方便后续用脚本分析。# config.test.yaml 示例 agent: name: test-agent log_level: debug log_format: json workspace: ./.test-workspace tools: - name: file_manager enabled: true sandbox: true - name: web_search enabled: true mock: true # 测试时用 mock 数据避免真实网络请求 memory: backend: sqlite path: ./.test-workspace/memory.db这套配置看起来简单但实际用起来能省掉大量排查时间。尤其是mock: true这个开关让我可以在不依赖外部服务的情况下反复跑测试用例稳定性提升非常明显。2.3 测试用例的设计方法从“用户故事”到“断言”设计测试用例的时候我没有一上来就写代码而是先用自然语言把每个功能的使用场景描述出来。比如“文件管理”这个功能我会写当我让 Agent 帮我整理某个目录下的文件时它应该能正确列出文件、识别文件类型、按照我指定的规则重命名或移动并且在操作完成后给我一个清晰的汇总。然后我把这个描述拆成具体的测试步骤和预期结果准备一个包含多种类型文件的测试目录发送指令“帮我把这个目录下的图片文件都移到 images 子目录”检查 Agent 是否调用了文件管理工具检查工具调用的参数是否正确源目录、目标目录、文件过滤条件检查操作完成后目录结构是否符合预期检查 Agent 的回复是否包含操作汇总每一步都要有明确的“断言”不能模棱两可。比如“回复是否清晰”这种就没法测得改成“回复中是否包含移动的文件数量”这种可验证的条件。3. 核心功能模块的详细测试与实操记录3.1 对话与意图识别最基础也最容易翻车的地方对话看起来是最简单的功能但实际上它是整个 Agent 的入口一旦这里出问题后面所有功能都别想正常跑。我重点测了三个方面意图识别的准确率、多轮对话的上下文保持、以及模糊指令的处理。意图识别这块我准备了 50 条测试指令覆盖了查询、操作、闲聊、复合指令四种类型。结果发现一个很典型的问题当指令里同时包含“查询”和“操作”两个意图时Agent 经常只执行其中一个。比如“帮我查一下明天天气然后提醒我带伞”它要么只查天气要么只设提醒很少两个都做。排查下来发现是意图分类器的设计问题——它用的是单标签分类而不是多标签。解决办法也很直接把意图识别改成多标签模式并且加一个“意图优先级”的配置让 Agent 知道先执行哪个再执行哪个。# 修改前的单标签分类 intent classifier.predict(text) # 返回单个意图 # 修改后的多标签分类 intents classifier.predict_multi(text) # 返回意图列表 # 按优先级排序 intents.sort(keylambda x: INTENT_PRIORITY[x], reverseTrue)多轮对话的上下文保持是另一个重灾区。我测试的时候发现当对话轮次超过 5 轮之后Agent 开始“忘记”前面说过的关键信息。比如第 2 轮我说“我叫张三”到第 7 轮它就不记得了。这个问题出在上下文窗口的管理策略上——默认的滑动窗口太小而且没有对关键信息做特殊标记。我的改进方案是引入一个“关键信息提取”步骤每轮对话结束后自动从对话内容中提取实体和关键事实存到一个独立的“长期记忆”里。这样即使滑动窗口滑走了原始对话关键信息也不会丢。实操心得上下文管理不要指望模型自己记住一定要有显式的记忆机制。我试过纯靠大窗口硬扛结果就是 token 消耗爆炸而且效果还不稳定。3.2 工具调用参数传递和错误处理是两大难关工具调用是 Agent 的核心能力也是最容易出问题的环节。我测试的工具包括文件管理、网络查询、代码执行、日程管理四个大类。每个工具我都从“正常调用”“参数缺失”“参数错误”“工具内部报错”四个维度去测。正常调用这块大部分工具都能跑通但有一个细节值得注意工具返回结果的格式一致性。有的工具返回 JSON有的返回纯文本有的返回带 markdown 的字符串。Agent 在处理这些结果时如果没有统一的解析层就很容易出现“工具明明成功了但 Agent 说失败了”的情况。我的做法是加一个“结果规范化层”所有工具返回的结果都先经过这个层处理统一转换成{status, data, message}的格式然后再交给 Agent 消费。def normalize_tool_result(raw_result): 统一工具返回格式 if isinstance(raw_result, dict): return { status: raw_result.get(status, success), data: raw_result.get(data, raw_result), message: raw_result.get(message, ) } elif isinstance(raw_result, str): return { status: success, data: raw_result, message: } else: return { status: error, data: None, message: fUnsupported result type: {type(raw_result)} }参数错误这块我遇到的最典型问题是Agent 在调用工具时有时候会“编造”参数。比如文件管理工具需要source和destination两个参数Agent 在用户没有明确指定 destination 的时候会自己瞎填一个路径。这个问题的根源在于工具定义的 schema 不够严格没有把必填参数标记清楚。解决办法是在工具定义里明确标注required字段并且在 Agent 调用之前加一层参数校验。如果必填参数缺失直接返回错误提示让 Agent 重新向用户确认而不是自己瞎猜。工具内部报错的处理也很关键。我测试的时候故意让代码执行工具跑一段会抛异常的代码结果发现 Agent 直接把异常堆栈返回给用户了体验非常差。正确的做法应该是工具捕获异常后返回结构化的错误信息Agent 根据错误类型决定是重试、降级还是告知用户。错误类型处理策略示例参数缺失向用户确认“请告诉我目标目录是哪个”参数格式错误自动修正常见格式路径中的反斜杠自动转正斜杠工具超时重试一次失败则降级网络查询超时后改用缓存数据工具内部异常返回友好提示记录日志“文件操作失败请检查权限”3.3 记忆与状态管理短期记忆和长期记忆要分开治记忆管理是我这次测试中改动最大的部分。原来的设计很简单所有对话历史都塞进一个列表每次请求的时候把整个列表传给模型。这个方案在对话轮次少的时候没问题但轮次一多就崩了——token 消耗巨大而且模型对早期信息的注意力明显下降。我重新设计了一套分层记忆机制短期记忆最近 3 轮对话的完整内容保证当前对话的连贯性。工作记忆当前任务相关的关键信息比如正在处理的文件路径、正在查询的日期范围。这部分用结构化的方式存储不依赖模型自己记。长期记忆用户偏好、常用配置、历史重要事件。这部分存在数据库里需要的时候通过检索召回。测试的时候我专门设计了一个场景让 Agent 先记住我的文件整理偏好比如“图片放 images文档放 docs”然后过 20 轮对话之后再让它整理文件看它还能不能正确应用这个偏好。结果在改进之前它完全忘了改进之后它能从长期记忆里正确召回。class MemoryManager: def __init__(self): self.short_term [] # 最近3轮 self.working {} # 当前任务上下文 self.long_term LongTermStore() # 持久化存储 def add_dialogue(self, role, content): self.short_term.append({role: role, content: content}) if len(self.short_term) 6: # 3轮对话6条消息 self.short_term.pop(0) # 提取关键信息存入长期记忆 facts extract_facts(content) for fact in facts: self.long_term.save(fact) def get_context(self): return { short_term: self.short_term, working: self.working, long_term: self.long_term.retrieve_relevant() }注意长期记忆的召回一定要做相关性过滤不能把所有历史都塞回去。我试过全量召回结果就是上下文爆炸而且引入了大量无关信息干扰模型判断。3.4 定时任务与触发机制时间相关的 bug 最隐蔽定时任务这块我原本以为很简单不就是到点触发吗结果测试下来发现坑最多。主要问题集中在三个方面时区处理、任务重叠、以及触发失败后的补偿。时区问题很典型我在配置里写的是“每天早上 9 点”但实际触发时间是下午 5 点。排查发现是服务器时区和本地时区不一致而配置里没有显式指定时区。解决办法是在所有时间相关的配置里强制要求带时区信息比如09:0008:00并且在代码里统一用 UTC 存储展示的时候再转本地时区。任务重叠是指如果前一个任务还没执行完下一个触发时间就到了该怎么办我测试的时候故意让一个任务执行时间超过触发间隔结果发现 Agent 会同时启动两个实例导致资源竞争和数据混乱。正确的做法是加一个“任务锁”同一个任务在同一时间只能有一个实例在跑。import threading class ScheduledTask: def __init__(self, name, func, interval): self.name name self.func func self.interval interval self.lock threading.Lock() def run(self): if not self.lock.acquire(blockingFalse): log.warning(fTask {self.name} is still running, skip this trigger) return try: self.func() finally: self.lock.release()触发失败后的补偿也很重要。我测试的时候模拟了网络中断的情况结果发现任务失败后就直接丢了没有任何重试机制。后来我加了一个简单的重试队列失败的任务会进入队列等待下一次触发时优先执行。4. 常见问题与排查技巧实录4.1 问题速查表我踩过的坑和对应的解法问题现象可能原因排查方法解决方案Agent 启动后无响应配置文件路径错误检查启动日志中的配置加载记录用绝对路径或确认工作目录工具调用总是失败API Key 过期或权限不足单独测试工具接口更新 Key检查权限范围多轮对话后回答质量下降上下文窗口溢出打印每轮请求的 token 数引入分层记忆机制定时任务不触发时区配置错误对比服务器时间和配置时间统一使用 UTC 存储并发请求时数据混乱共享状态没有加锁检查全局变量的读写加锁或改用无状态设计工具返回结果解析失败返回格式不统一打印原始返回内容加结果规范化层长文本输入被截断输入长度限制检查模型的最大输入长度分段处理或摘要压缩4.2 独家避坑技巧那些文档里不会写的东西第一个技巧日志一定要打全但不要打太多。我一开始为了排查问题把所有中间状态都打成日志结果日志文件一天就涨到几个 G反而影响性能。后来我改成“分级日志”正常流程只打关键节点异常情况才打详细堆栈。这样既能排查问题又不会拖慢系统。第二个技巧测试用例要能一键重跑。我见过很多人测试的时候手动敲指令测完就完了下次想复现又得重新敲一遍。我的做法是把所有测试用例写成 YAML 文件用一个脚本批量执行每次改完代码跑一遍几分钟就能知道有没有引入回归问题。# test_cases.yaml - name: 文件整理-正常路径 input: 把 test_files 目录下的图片移到 images 子目录 setup: - create_dir: test_files - create_file: test_files/a.jpg - create_file: test_files/b.txt expect: - tool_called: file_manager - dir_exists: test_files/images - file_exists: test_files/images/a.jpg - file_not_exists: test_files/a.jpg第三个技巧给 Agent 加一个“调试模式”。开启后Agent 会在每次回复后面附上它的“思考过程”——选了哪个工具、为什么选、参数是什么。这个功能在排查问题时极其有用平时关掉就行。if config.debug_mode: response f\n\n[调试信息]\n意图: {intent}\n工具: {tool_name}\n参数: {tool_params}4.3 性能优化的几个关键点测试过程中我也顺手做了一些性能优化效果比较明显的有三个工具调用并行化如果多个工具之间没有依赖关系可以并行调用。比如同时查天气和查日程没必要串行。我用asyncio.gather把这块的耗时从 2 秒降到了 0.8 秒。记忆检索加缓存长期记忆的检索比较耗时我加了一层 LRU 缓存相同查询在短时间内直接返回缓存结果命中率大概在 60% 左右。日志异步写入日志同步写磁盘会阻塞主流程改成异步队列之后主流程的响应时间平均降低了 15%。5. 测试之后的整体感受和后续计划这次全面测试下来最大的收获不是修了多少 bug而是对整个 Agent 的行为有了更清晰的认知。以前很多问题是“感觉不对劲但说不清哪里不对”现在通过系统化的测试能把模糊的感觉转化成具体的指标和日志排查起来有据可依。如果让我给也在折腾 Agent 的朋友一个建议那就是不要等到功能堆完了才想起来测试。最好是每加一个新功能就顺手补上对应的测试用例。这样虽然前期麻烦一点但后期能省掉大量“牵一发而动全身”的排查成本。我现在已经把测试用例的编写纳入到日常开发流程里了每次改完代码先跑一遍测试心里踏实很多。后续我打算把这套测试流程进一步自动化做成一个可以定时跑的“健康检查”这样即使我一段时间不碰它也能知道 Agent 的状态是不是正常的。另外还想加一些更贴近真实使用场景的端到端测试比如模拟一整天的使用流程看看在连续、复杂的交互下Agent 的表现会不会有衰减。