Hermes Agent 报 No module named agent.transports？pip / Nix 源码安装缺包排错指南

如果你从源码安装 Hermes Agent 后，一切配置看起来都正常，但一启动 native Anthropic provider 就报：

ModuleNotFoundError: No module named 'agent.transports'

或者 API Server / REST proxy 返回：

API call failed after 3 retries: No module named 'agent.transports'

这大概率不是 Anthropic API Key 错了，也不是模型名写错了，而是打包配置没有把 agent/transports/ 子包带进安装产物。

这篇文章基于 NousResearch/hermes-agent issue #13581 和相关 PR #13580，整理一份面向 pip、Nix、源码安装、Docker/sidecar 部署的排错指南。

> 适合搜索关键词：Hermes Agent No module named agent.transports、ModuleNotFoundError agent.transports hermes-agent、pip install hermes-agent source missing package、Nix hermes-agent agent.transports、native Anthropic provider No module named agent.transports。

先给结论

agent.transports 缺失的核心原因是：

[tool.setuptools.packages.find]
include = ["agent", ...]

只包含了 agent 本身，却没有包含：

"agent.*"

在 setuptools 的 packages.find 里，显式 include 不会自动递归到子包。结果就是源码树里明明有：

agent/transports/__init__.py
agent/transports/anthropic.py
agent/transports/base.py
agent/transports/types.py

但安装到 site-packages 后，agent/transports/ 整个目录不见了。

于是运行到类似：

from agent.transports import get_transport

就会直接崩：

ModuleNotFoundError: No module named 'agent.transports'

这个问题影响哪些用户？

从 issue #13581 的信息看，主要影响：

从源码安装：pip install .
从 GitHub 安装：pip install "git+https://github.com/NousResearch/hermes-agent.git"
Nix / NixOS packaging
macOS 15 + Nix build
Ubuntu 24.04.3 + Python 3.12.3
Hermes v0.10.0 附近版本
使用 native Anthropic provider 的用户
把 Hermes 放在 REST proxy / API Server / sidecar 部署后面的用户

特别是这类配置：

provider: anthropic
model: anthropic/claude-sonnet-4.6

如果你只是使用 OpenAI-compatible provider，可能不会立刻触发 agent.transports 路径，所以会误以为安装没问题。等切到 native Anthropic provider，才突然爆出 import error。

为什么源码里有文件，安装后却没有？

这是 Python packaging 里非常典型的坑。

很多人会以为：只要目录里有 __init__.py，pip install . 就会自动包含所有子目录。实际上，如果项目在 pyproject.toml 里显式配置了 include 列表，就要把子包 glob 写完整。

issue #13581 指出的关键配置类似：

include = ["agent", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", ...]

可以看到：

tools 有 tools.*
gateway 有 gateway.*
plugins 也通常会有 plugins.*
但 agent 只有 agent，缺了 agent.*

所以 setuptools 只打包顶层 agent 包，不递归包含 agent.transports 这类子包。

相关 PR #13580 的修复方向就是一行：

"agent.*"

加到 include 列表里。

典型复现路径

你可以用下面思路判断自己是不是同一个问题。

1. 从源码安装

pip install "git+https://github.com/NousResearch/hermes-agent.git"

或：

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
pip install .

2. 启用 native Anthropic provider

例如：

provider: anthropic
model: anthropic/claude-sonnet-4.6

3. 启动聊天或 API Server

当运行到 Anthropic transport 相关逻辑时，出现：

ModuleNotFoundError: No module named 'agent.transports'

或 API Server 里包了一层：

API call failed after 3 retries: No module named 'agent.transports'

4. 检查 site-packages

进入 Python 环境后运行：

python - <<'PY'
import agent, pathlib
p = pathlib.Path(agent.__file__).parent
print(p)
print((p / "transports").exists())
print(list(p.iterdir()))
PY

如果输出里没有 transports 目录，基本就坐实了。

快速验证命令

最简单的检查是：

python -c "import agent.transports; print('agent.transports OK')"

如果报：

ModuleNotFoundError: No module named 'agent.transports'

说明当前安装产物确实缺子包。

如果成功输出：

agent.transports OK

那你遇到的就可能不是 #13581，需要继续检查 provider 配置、API Key、base URL、模型名或网络问题。

临时 workaround：手动复制 transports 目录

如果你现在生产环境已经挂了，短期 workaround 是把源码里的：

agent/transports/

复制到当前 Python 环境的：

site-packages/agent/transports/

issue 评论里有人确认，手动复制后 chat round-trip 可以恢复。

但这只能救急，不建议长期依赖。原因很简单：

下一次重装会丢；
Docker 镜像重建会丢；
Nix derivation 更新会丢；
多环境部署容易漏；
版本不一致时可能引入更隐蔽的问题。

长期还是应该升级到包含修复的版本，或者在你自己的 packaging patch 里补上 agent.*。

正确修复：确认 pyproject.toml 包含 agent.*

如果你维护自己的 fork、Nix package 或内部镜像，可以检查 pyproject.toml：

[tool.setuptools.packages.find]
include = [
  "agent",
  "agent.*",
  "tools",
  "tools.*",
  "hermes_cli",
  "gateway",
  "gateway.*",
]

关键是 agent 和 agent.* 都要在。

修改后重新构建并安装：

pip uninstall -y hermes-agent
pip install .
python -c "import agent.transports; print('OK')"

Nix 用户则应在 derivation patch 阶段补上同样的改动，然后重新 build。

为什么这个问题只在 native Anthropic provider 下明显？

因为 agent.transports 是 native provider transport 抽象的一部分。

如果你使用的是 OpenAI-compatible API 路径，Hermes 可能不会触发：

from agent.transports import get_transport

所以同一个安装包，在 A 配置下看起来正常，在 B 配置下突然炸。

这也解释了很多误判：

不是 Claude 模型一定坏了；
不是 Anthropic API 一定挂了；
不是 API Key 一定错误；
不是网络连不上；
而是运行到 native Anthropic transport import 时，安装产物里没有对应 Python 子包。

DeepAI API 中转站相关：什么时候能绕开这个坑？

如果你的目标是把多种模型统一接进工具链，DeepAI API 中转站这类 OpenAI-compatible API 网关可以降低很多 provider 切换成本：

统一 Base URL；
统一 API Key；
统一模型调用方式；
适配 Cherry Studio、Cline、Dify、Open WebUI 等支持 OpenAI Compatible API 的工具；
减少不同 native provider SDK 路径带来的差异。

在这个具体问题里，如果你不用 Hermes 的 native Anthropic provider，而是走 OpenAI-compatible provider 路径，确实可能避开 agent.transports import 路径。

但要注意边界：DeepAI API 中转站不能修复你的 Hermes 安装包缺文件。它只是让你在某些场景下选择另一条兼容 API 路径，减少触发 native transport 的概率。

如果你必须使用 native Anthropic provider，仍然应该修复 agent.* 打包问题。

排错清单

遇到 No module named 'agent.transports' 时，按这个顺序查：

1. 确认错误是否精确包含：ModuleNotFoundError: No module named 'agent.transports'； 2. 运行：python -c "import agent.transports"； 3. 查看 site-packages/agent/ 下是否存在 transports/； 4. 确认安装方式是否为 pip install .、GitHub source install、Nix build 或内部 packaging； 5. 检查是否使用 native Anthropic provider； 6. 检查当前 Hermes 版本是否在 v0.10.0 附近或早于修复； 7. 升级到包含 main 修复的版本； 8. 如果自己打包，确认 pyproject.toml include 列表里有 "agent.*"； 9. 重新安装后再次运行 python -c "import agent.transports; print('OK')"； 10. 仍失败时，再查虚拟环境、Python path、多版本冲突。

给 issue / 运维同事的最小复现模板

如果你要提交 issue 或发给运维同事，可以直接贴这段：

Symptom:
ModuleNotFoundError: No module named 'agent.transports'

Environment:
- OS:
- Python:
- Hermes version / commit:
- Install method: pip install . / pip install git+... / Nix / Docker
- Provider: anthropic
- Model:

Checks:
- python -c "import agent.transports" fails
- site-packages/agent/transports/ is missing
- source tree has agent/transports/

Suspected cause:
pyproject.toml setuptools packages.find include has "agent" but not "agent.*", so sub-package is missing from built distribution.

Expected fix:
Add "agent.*" next to "agent" and rebuild package.

这比只说“Claude 不能用”有效得多。

FAQ

这是 Anthropic API 的问题吗？

通常不是。No module named 'agent.transports' 是 Python import error，发生在本地运行环境加载模块时，请求可能还没真正发到 Anthropic。

为什么 pip install 成功了，运行才失败？

因为打包阶段没有验证所有运行路径都能 import。安装成功只说明包构建/安装流程完成，不代表 native Anthropic provider 所需的每个子包都被包含。

为什么 OpenAI-compatible provider 正常，Anthropic provider 不正常？

因为两条 provider 路径触发的代码不同。OpenAI-compatible 路径可能不需要 agent.transports，native Anthropic provider 才会 import 它。

直接复制 `agent/transports/` 可以吗？

可以作为短期救急，但不建议长期使用。正确做法是升级或修复 packaging，让安装产物自然包含 agent.transports。

PR `#13580` 是合并了吗？

GitHub API 查询时，#13580 显示 closed 且 merged_at 为 null；issue #13581 评论中维护者说 Fixed in main。所以更准确的说法是：修复方向是添加 agent.*，问题已在 main 中修复/关闭，但不要把它写成“PR #13580 已合并”。

总结

ModuleNotFoundError: No module named 'agent.transports' 是一个很典型的“源码有文件，安装包没带上”的 Python packaging 问题。

判断它的关键不是反复换 API Key 或模型名，而是检查：

python -c "import agent.transports"

以及：

site-packages/agent/transports/

是否存在。

如果不存在，优先升级 Hermes Agent 或在 pyproject.toml 的 setuptools include 列表中补上：

"agent.*"

对于只需要 OpenAI-compatible API 的工作流，可以考虑通过 DeepAI API 中转站统一模型入口，减少 native provider 差异；但如果你明确依赖 Hermes 的 native Anthropic provider，那最终还是要修复安装包里的 agent.transports 子包缺失问题。