第9章 Agent 故障排查指南
Agent 故障排查
使用本指南来诊断和修复常见的 Agent 问题。
快速初筛
确认模型提供商已在 Agents Config 中启用 确认 Agent 已连接到有效模型 确认必需的工具已启用 运行一个简单的、已知有效的测试提示词
常见问题
问题 | 可能原因 | 解决方法 --- | --- | --- Agent 无响应 | 提供商/模型配置不正确 | 重新检查 API 凭证、模型名称和提供商状态 设置成功后模型调用返回 404 | 自定义提供商基础 URL 缺少带版本号的 API 路径 | 在基础 URL 中包含完整的 API 根路径,例如 https://proxy.example.com/v1 Agent 编造数值 | 缺少工具使用规则或未启用读取工具 | 添加严格的工具规则并启用必需的读取工具 Agent 意外更新数据 | 写入规则过于模糊 | 添加明确的写入约束和拒绝规则 自动化解析失败 | 响应间的输出格式发生变化 | 在指令中强制使用稳定的 JSON schema 自托管 AI 请求失败 | 网络出站限制 | 遵循自托管 AI 功能要求 Agent Knowledge 操作被禁用 | GEMINI_API_KEY 未配置 | 在环境中设置 GEMINI_API_KEY 并重启 Budibase Gemini 存储摄取失败 | 无法访问(403 Forbidden)或未找到(404) | 摄取将立即失败且不会重试。使用“重置存储”来重新创建它。 SharePoint 文件未被摄取 | 文件大小超过 100MB 限制 | 确保用于摄取的知识源文件小于 100MB 摄取等待容量 | 达到 Gemini API 速率限制 | Budibase 会自动推迟并重试摄取作业,采用退避策略。除非持续数小时,否则无需采取行动。 已批准的工具执行失败 | 输入与当前资源模式不匹配,或发生其他后端错误 | 在活动时间线中检查具体错误。确认字段名称、类型和约束与当前的表格、自动化触发器或 REST 查询模式匹配。
调试清单
当行为不一致时:
降低提示词复杂度并重新测试 验证 Agent 上下文中的工具列表 添加有效和无效行为的明确示例 针对固定的回归测试集测试每项指令更改
何时更改指令 vs 工具
在以下情况更改指令:
行为大体正确但不一致 拒绝或升级逻辑需要收紧
在以下情况更改工具:
Agent 无法访问必需的数据 Agent 拥有不应具备的高风险能力
相关指南
Agent 工具和权限 Agent 测试指南 更新于 15 天前。此页面对您有帮助吗?