Agent Framework 问题排查

本页面可帮助您诊断和解决使用 Agent Framework 时遇到的常见问题。

本页面包含以下内容：

安装和设置

常见问题：安装失败、导入错误、API 身份验证问题。

检查：

  • Python 和 pip 版本
  • .whl 文件完整性和路径
  • .env 文件配置（API 密钥、项目详细信息）
  • gcloud auth 设置（适用于 Vertex AI）
  • 依赖项安装 (requirements.txt)
  • 虚拟环境激活

代理定义问题

常见问题：代理行为不符合预期、未调用工具、agent.py 中存在错误。

检查：

  • agent.py 代码语法（lint 检查）
  • 代理 instruction 清晰度和正确性
  • 工具定义（名称、说明、参数）
  • 代理属性 (name, model, tools, flow) - 拼写错误、有效性
  • agent.py 中的代码逻辑 - 使用 print 语句进行调试

执行问题

常见问题：CLI 命令失败（af run、af web、af test）、网页界面错误、API 服务器问题。

检查：

  • CLI 命令语法和参数 (--help)
  • 工作目录（代理项目根目录）
  • 终端错误消息（复制完整错误）
  • 端口冲突（适用于网页界面/API 服务器 - 尝试使用其他端口）
  • 浏览器兼容性（适用于网页界面）
  • 浏览器控制台错误（适用于网页界面）

评估问题

常见问题：测试失败、评估结果异常。

检查：

  • *.test.json 文件语法（有效 JSON）
  • 测试文件内容（查询、expected_tool_use、reference 准确性）
  • af test 命令或 pytest 代码中的文件路径
  • test_config.json 中的评估标准（如果使用）
  • 在网页界面中运行测试以获取视觉反馈

常见的错误消息

  • 安装问题
  • API 密钥或身份验证问题
  • model 属性不正确
  • 网络/API 服务器上的端口冲突

常规问题排查提示：

  • 简化和隔离：从简单系统开始，逐步提高复杂性。
  • 检查日志：终端、Cloud Logging、浏览器控制台。
  • 请参阅文档：重新阅读相关部分。
  • 在线搜索：Stack Overflow、论坛。
  • 在寻求帮助时提供详细信息：代码、错误、步骤、环境。