AgentKit

Appearance

故障排除指南 ​

本指南旨在帮助您诊断和解决在使用 AgentKit 过程中可能遇到的常见问题。如果您在此处未找到解决方案，请随时通过 GitHub Issues 与我们联系。

安装问题 ​

1. agentkit 命令未找到 ​

  • 现象: 在终端中执行 agentkit 命令时，系统提示 command not found。
  • 原因: 这通常是由于 pip 安装的可执行文件路径未被添加到系统的 PATH 环境变量中。
  • 解决方案:
    • 确认安装路径: 执行 pip show agentkit-sdk-python 或 uv pip show agentkit-sdk-python，找到 Location 字段指示的安装路径。
    • 找到可执行文件: 在安装路径下的 bin 目录中（例如 .../site-packages/bin），应该能找到 agentkit 可执行文件。
    • 添加到 PATH: 将此 bin 目录的绝对路径添加到您的 ~/.bashrc、~/.zshrc 或其他 Shell 配置文件中。
      bash
      export PATH="/path/to/your/python/bin:$PATH"
    • 重新加载配置: 执行 source ~/.bashrc 或重启终端以使更改生效。

2. 依赖冲突 ​

  • 现象: 在安装 agentkit-sdk-python 时，pip 报告依赖版本冲突。
  • 原因: 您的 Python 环境中可能已存在与 AgentKit 不兼容的库版本。
  • 解决方案:
    • 使用虚拟环境（推荐）: 强烈建议在项目中使用 uv 或 venv 创建一个干净的虚拟环境，以避免与系统级的 Python 包产生冲突。
      bash
      uv venv
source .venv/bin/activate
uv pip install agentkit-sdk-python
    • 强制重新安装: 如果不想使用虚拟环境，可以尝试强制重新安装 AgentKit 及其依赖。
      bash
      pip install --force-reinstall agentkit-sdk-python

配置问题 ​

1. 环境变量未生效 ​

  • 现象：提示无法连接到 AgentKit Platform 或认证失败。
  • 原因：可能未传入环境变量或传入了错误的环境变量名称
  • 解决方案：
    • 确认已设置必需的环境变
    bash
    echo $VOLCENGINE_ACCESS_KEY
echo $VOLCENGINE_SECRET_KEY
    • 确保没有多余的空格或引号
    • 在当前 shell 会话中重新 export 环境变量

2. 配置文件格式错误 ​

  • 现象：执行 agentkit launch 时提示配置文件解析失败。
  • 原因：文件格式问题
  • 解决方案：
    • 检查 agentkit.yaml 格式是否正确（注意缩进）
    • 重新运行 agentkit config 生成配置

部署问题 ​

1. CR 创建失败 ​

  • 现象：
CreateRegistry: QuotaExceeded.Registry The quota of Registry is exceeded.
  • 原因：账号配额不足
  • 解决方案：
    • CR 实例数量超出配额限制
    • 在 agentkit config 中配置为已有的 CR 实例名称
    • 或联系管理员提高配额

2. 镜像构建失败 ​

  • 现象：Pipeline 构建失败，提示依赖安装错误。
  • 原因：依赖安装失败
  • 解决方案：
    • 检查 requirements.txt 中的依赖是否正确
    • 确认依赖版本是否兼容 Python 3.12
    • 查看 Pipeline 日志获取详细错误信息 (日志会自动下载到您本地根目录下，您可以注意交互界面的提示，在根目录找到一个类似命名的文件pipeline_failed_****ff20ce223.log)

3. Runtime 部署超时 ​

  • 现象：Runtime 长时间处于 Releasing 状态。
  • 原因：首次部署耗时久，或可能存在资源不足
  • 解决方案：
    • 首次部署通常需要 2-3 分钟，请耐心等待
    • 使用 agentkit status 检查状态
    • 如果超过 5 分钟仍未就绪，可能是资源不足，尝试 agentkit destroy 后重新部署

4. Runtime 状态异常 ​

  • 现象：Runtime 状态为 Failed 或 Error。
  • 原因：Runtime 内部异常
  • 解决方案：
    • 检查环境变量配置是否正确（特别是模型 API Key）
    • 查看 AgentKit Platform 控制台的日志
    • 确认应用代码没有启动时错误
    • 尝试使用 agentkit destroy 清理后重新部署

调用问题 ​

1. invoke 调用失败 ​

  • 现象：执行 agentkit invoke 时提示连接失败或超时。
  • 原因：网络问题或 Endpoint 配置错误
  • 解决方案：
    • 使用 agentkit status 确认 Runtime 状态为 Ready
    • 检查网络连接
    • 确认 Endpoint 地址正确
    • 检查防火墙或代理设置

2. 模型调用失败 ​

  • 现象：Agent 返回错误，提示模型访问失败。
  • 原因：模型 API Key 配置错误或模型配额用尽
  • 解决方案：
    • 确认方舟模型 API Key 配置是否正确
    • 检查接入点 ID 是否有效
    • 确认模型配额是否用尽
    • 登录方舟平台检查 API Key 权限

权限问题 ​

1. AK/SK 认证失败 ​

  • 现象：提示 InvalidAccessKeyId 或 SignatureDoesNotMatch。
  • 原因：AK/SK 配置错误或权限不足
  • 解决方案：
    • 确认 AK/SK 正确且有效
    • 检查是否有 AgentKit 服务的访问权限
    • 确认 AK/SK 没有被禁用或过期
    • 联系管理员分配相关权限

2. 资源访问被拒绝 ​

  • 现象：提示 AccessDenied 或权限不足。
  • 原因：账号没有足够的权限执行操作
  • 解决方案：
    • 确认账号有相应资源的操作权限
    • 检查 IAM 角色配置
    • 联系管理员授予必要权限

获取帮助 ​

如果以上方案无法解决您的问题，请：

  1. 查看日志：

    • 本地日志：检查命令行输出
    • Platform 日志：访问 AgentKit 控制台查看详细日志

  2. 联系支持：

    • 提供详细的错误信息和日志
    • 说明复现步骤
    • 附上相关配置文件（注意脱敏）
    • 联系火山引擎技术支持

  3. 查阅文档：

Released under the Apache-2.0 License.

Copyright © 2025 Volcengine