故障排查

升级后 `ksadk` 或 `a2a` 命令报依赖错误

在运行命令的同一个 Python 环境中升级 KsADK。推荐为每个项目创建独立环境：

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade "ksadk[all]"
python -m pip show ksadk a2a-sdk
ksadk --help

python -m pip 必须和随后运行 ksadk 的 Python 属于同一环境；直接执行另一个 pip 可能把新依赖装到别的解释器。通过源码可编辑安装时，修改依赖声明后也必须再次执行安装命令，才能刷新已安装包的元数据。

KsADK 0.8 的 A2A 实现精确锁定 a2a-sdk==1.1.0。仍锁定 A2A 0.3 的项目（例如某些 VEADK 版本）不能与它共用一个虚拟环境，请分别创建环境。依赖不兼容时，ksadk --help 仍可使用；执行 ksadk a2a 会显示具体的加载错误。

找不到 `agentengine` 命令

确认虚拟环境已经激活，并且命令与包安装在同一个 Python 环境：

python -m pip show ksadk
python -m pip install -U ksadk
which agentengine

Windows 安装后若刚把 Scripts 目录加入 PATH，请重新打开终端。

模型调用失败

检查：

OPENAI_API_KEY 是否存在。
OPENAI_BASE_URL 是否是 OpenAI 兼容 endpoint。
OPENAI_MODEL_NAME 是否被 provider 支持。
本地网络是否能访问 provider。

框架检测失败

优先确认 agentengine.yaml：

framework: langgraph
entry_point: my_agent/agent.py
agent_variable: root_agent

如果检测成功但加载失败，通常是依赖缺失、导入路径错误或导出变量不匹配。

Web UI 无法打开

检查：

agentengine web . --no-open 是否启动成功。
端口是否被占用。
ksadk/server/static/index.html 是否存在。
浏览器控制台是否有资源 404。

如果端口被占用，显式换一个端口：

agentengine web . --port 7860 --no-open

API 服务端口被占用

本地运行时可以直接选择其他端口：

agentengine run . --port 8090

构建或部署要求云凭证

本地开发不需要云凭证；build、deploy、launch 是否需要 AK/SK 取决于目标和模式。评审配置或文档时，优先使用支持的 dry-run：

agentengine --dry-run build .

不要把真实凭证、私有镜像仓库、kubeconfig 或客户数据写入公开 issue、文档和测试。

导入已有 Agent 失败

先检查生成的 agentengine.yaml：

cat agentengine.yaml

常见修复是显式设置 framework，让 entry_point 指向真实 Python 文件，让 agent_variable 与导出对象同名，并安装缺少的框架依赖。带副作用的启动逻辑应放到 if __name__ == "__main__" 之后。

Responses API 会话冲突

conversation 与 session_id 只能表达同一个会话，不要在同一请求里发送两个不同值：

{
  "conversation": {"id": "local-session-1"},
  "input": "继续"
}

流式客户端一直等待

stream: true 使用服务端事件流。先用 stream: false 区分运行时问题与客户端 SSE 解析、代理缓冲问题。页面刷新会断开原连接，但运行可能仍在服务端继续；支持重连的客户端应使用已知的 session id、invocation id 和最后消费的事件序号续读，而不是假设 TCP 连接可以原样恢复。

上传文件未进入回答

确认请求使用支持的 input_file 形态，或在 Web UI 后续请求中引用上传接口返回的 ksadk-upload://... URI。这个 URI 属于当前运行时；删除 .agentengine/ui、移动项目或把请求发给另一个 Runtime 后不能继续使用。

文件已显示但模型没有使用内容时，检查文件类型、抽取警告和大小；自定义 hook 需要只处理当前轮上传时读取 current_attachment_results，需要保留追问上下文时读取 attachment_results。

追问丢失附件上下文

确认追问沿用同一个 conversation.id 或 session_id，首轮请求已成功完成，并且客户端没有在刷新页面后创建新本地会话。纯文本追问的 current_attachment_results 为空是预期行为。

会话历史不正确或看似丢失

确认 KSADK_STM_PATH 或 AGENTENGINE_UI_DIR 是否稳定。每次换目录或重新生成 session id 都会导致 UI 看起来像新会话。运行时从追加事件日志投影模型历史； run_status、reasoning 是生命周期或诊断事件，不应当成普通模型消息。还应检查上下文压缩是否产生 checkpoint，以及工具或审批事件是否被错误投影成文本摘要。

Skill Runtime 不执行

Skill Space 可发现不等于 sandbox 已启用。隔离执行需要：

KSADK_SKILL_RUNTIME_BACKEND
KSADK_SKILL_RUNTIME_TEMPLATE_ID 或 KSADK_SANDBOX_TEMPLATE_ID
对应 runtime 依赖和凭证

未配置时应返回诊断，而不是伪造执行成功。

公开文档构建失败

运行：

make docs-site-build

构建会同时检查 MDX、TypeScript、静态页面、部署子路径、站内链接与锚点、中英文初始语言、 canonical 和 hreflang。常见原因包括错误的相对链接、缺少中英文页面、无效 MDX 或文档引用了公开仓库中不存在的私有文件。

需要更多诊断信息

先查看命令的真实帮助，而不是照抄旧示例：

agentengine --help
agentengine run --help
agentengine web --help
agentengine config --help

故障排查

本页导航