agent输出异常时须逐层排查工具注册、参数生成、结构化校验、执行反馈四断点：先确认toolkit含目标工具（langchain 0.2+需显式传入工具列表），再校验llm生成参数键名与schema严格一致，接着用pydantic校验json结构，最后检查执行污染、截断及外部api响应异常，并启用降级与双模型交叉验证。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent输出结果不符合预期时，不能只盯着提示词反复修改，必须逐层排查工具注册、参数生成、结构化校验、执行反馈四个关键断点。
确认工具是否真正注册成功
运行Agent前先打印toolkit内容，检查目标工具名是否出现在列表中。LangChain 0.2+版本不会自动扫描全局函数，【必须显式传入工具列表】，否则即使代码里写了@tool装饰器也无效。
用print(agent.tools)验证，若输出为空或不包含目标工具名，说明注册失败。常见原因是：用了旧版教程的auto-discovery写法，或在create_tool_calling_agent时漏传工具列表参数。
检查模型生成的工具调用参数是否合法
方法一：开启debug日志，捕获LLM原始输出中的tool_calls字段，确认参数键名与工具定义的parameters完全一致（包括大小写和下划线）。
方法二：在工具函数内部加type-check断言，例如def get_weather(location: str) → 调用时传入{"Location": "Beijing"}会直接报错，因为键名大小写不匹配。这一步最容易被忽略，但90%的“调用成功却返回空”问题都源于此。
注意：工具描述（description）中写的示例参数格式，不代表模型必须照搬；模型实际生成的参数键名必须严格等于工具schema中定义的properties字段名。
验证结构化输出是否通过Schema校验
第一步：在调用工具前插入Pydantic模型校验，用model_validate_json()解析模型输出的JSON字符串。
第二步：若抛出ValidationError，立即提取error_details()中的loc字段，定位是哪个字段缺失、类型错误还是枚举值越界。
UP 简历 AI 求职助手。创建专业简历、搜索校招/社招/实习岗位、JD 对照优化、简历诊断、每日求职监控、智能投递指导。当用户说"创建简历"、"编辑简历"、"搜索校招"、"找工作"、"优化简历"、"投递"、"监控校招"时使用。
第三步：把完整错误信息拼进下一轮prompt，例如：“你上次输出的JSON中，'price'字段是字符串类型，但要求是number类型，请修正后重试”。【不反馈具体错误就重试，等于让模型蒙答案】
排查执行结果是否被截断或污染
① 检查工具函数return语句是否被print()或logging干扰——某些框架会把stdout内容混入最终返回值，导致JSON解析失败。
② 对长文本结果启用content_truncation策略：在工具定义中显式声明response_format = "text"或"json"，并设置max_length限制。
③ 若工具调用依赖外部API，抓包确认HTTP响应体是否含BOM头、不可见控制字符或HTML包装层——这些都会让后续的JSON解析器直接崩溃。
启用降级与人工兜底链路
当连续两次校验失败且重试无果时，触发降级逻辑：跳过当前工具节点，改用规则引擎从缓存/配置表中提取默认值。例如天气查询失败时，返回预设的“暂无实时数据，请稍后再试”。
对关键业务字段（如订单金额、用户手机号），强制开启双模型交叉验证：用Qwen2-7B快速校验GPT-4输出的数值范围是否合理，偏差超±5%即标记为高风险。
最后一步：将完整上下文（原始输入、模型输出、校验错误、降级结果）写入数据库，并向运维看板推送告警，同时生成人工复核工单。
