AgentKit
AgentKit
文档指南
请输入
- 文档首页
AgentKitAgentKit开发者指南CLI 参考故障排除指南
复制全文
下载 pdf故障排除指南
文档反馈
问问助手
说明
- 提供详细的错误信息和日志。
- 说明复现步骤。
- 附上相关配置文件（注意脱敏）。
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 配置文件中。
-
- 重新加载配置：执行source ~/.bashrc或重启终端以使更改生效。
依赖冲突
- 现象：在安装agentkit-sdk-python时，pip报告依赖版本冲突。
- 原因：您的 Python 环境中可能已存在与 AgentKit 不兼容的库版本。
- 解决方案：
- 使用虚拟环境（推荐）：强烈建议在项目中使用uv或venv创建一个干净的虚拟环境，以避免与系统级的 Python 包产生冲突。
-
- 清理环境重新安装：如果必须使用现有环境，建议先卸载再重新安装：
-
环境变量未生效
- 现象：提示无法连接到 AgentKit 或认证失败。
- 原因：可能未传入环境变量或传入了错误的环境变量名称。
- 解决方案：
- 确认已设置必需的环境变量。
-
- 确保没有多余的空格或引号。
- 在当前 Shell 会话中重新 export 环境变量。
配置文件格式错误
- 现象：执行agentkit launch时提示配置文件解析失败。
- 原因：文件格式问题
- 解决方案：
- 检查agentkit.yaml格式是否正确（注意缩进）。
- 重新运行agentkit config生成配置。
CR 创建失败
- 现象：
-
- 原因：账号配额不足。
- 解决方案：
- CR 实例数量超出配额限制。
- 在agentkit config中配置为已有的CR实例名称。
- 或联系管理员提高配额。
镜像构建失败
- 现象：Pipeline 构建失败，提示依赖安装错误。
- 原因：依赖安装失败。
- 解决方案：
- 检查requirements.txt中的依赖是否正确。
- 确认依赖版本是否兼容 Python 3.12。
- 查看 Pipeline 日志获取详细错误信息（日志会自动下载到您本地根目录下，您可以注意交互界面的提示，在根目录找到一个类似命名的文件pipeline_failed_****ff20ce223.log）。
Runtime 部署超时
- 现象：Runtime 长时间处于 Releasing 状态。
- 原因：首次部署耗时久，或可能存在资源不足。
- 解决方案：
- 首次部署通常需要 2 ～ 3 分钟，请耐心等待。
- 使用agentkit status检查状态。
- 如果超过 5 分钟仍未就绪，可能是资源不足，尝试agentkit destroy后重新部署。
Runtime 状态异常
- 现象：Runtime 状态为Failed或Error。
- 原因：Runtime 内部异常。
- 解决方案：
- 检查环境变量配置是否正确（特别是模型 API Key）。
- 查看 AgentKit 控制台的日志。
- 确认应用代码没有启动时错误。
- 尝试使用agentkit destroy清理后重新部署。
invoke 调用失败
- 现象：执行agentkit invoke时提示连接失败或超时。
- 原因：网络问题或 Endpoint 配置错误。
- 解决方案：
- 使用agentkit status确认 Runtime 状态为Ready。
- 检查网络连接。
- 确认 Endpoint 地址正确。
- 检查防火墙或代理设置。
模型调用失败
- 现象：Agent 返回错误，提示模型访问失败。
- 原因：模型 API Key 配置错误或模型配额用尽。
- 解决方案：
- 确认方舟模型 API Key 配置是否正确。
- 检查接入点 ID 是否有效。
- 确认模型配额是否用尽。
- 登录方舟平台检查 API Key 权限。
AK/SK 认证失败
- 现象：提示InvalidAccessKeyId或SignatureDoesNotMatch。
- 原因：AK/SK 配置错误或权限不足
- 解决方案：
- 确认 AK/SK 正确且有效。
- 检查是否有 AgentKit 服务的访问权限。
- 确认 AK/SK 没有被禁用或过期。
- 联系管理员分配相关权限。
资源访问被拒绝
- 现象：提示AccessDenied或权限不足。
- 原因：账号没有足够的权限执行操作。
- 解决方案：
- 确认账号有相应资源的操作权限。
- 检查IAM角色配置。
- 联系管理员授予必要权限。
日志文件没有创建
可能原因：
- 文件日志被禁用了
- 目录权限不足
解决方法：
控制台没有日志输出
可能原因：
- 控制台日志默认是关闭的
- 日志级别设置过高
解决方法：
日志太多或太少
调整日志级别：
最近更新时间：2026.10.29 12:23:56
这个页面对您有帮助吗？
有用
有用
无用
无用