记录BUG：开发violet_agents过程中出现Python的循环导入

记录BUG：开发violet_agents过程中出现Python的循环导入

问题复现

在测试violet_agents包时，我们输入以下代码测试

fromviolet_agentsimportSimpleAgentfromviolet_agentsimportVioletAgentsLLMfromdotenvimportload_dotenv load_dotenv()agent=SimpleAgent(name="helloAgent",llm=VioletAgentsLLM(provider="deepseek"),system_prompt="你是一个简单的助手，直接回答用户的问题，不进行复杂的思考和计划。")response=agent.run("你好，1 + 1 等于多少？")print(response.content)

运行该文件后，会报错，报错如下

Traceback (most recent call last): File "d:\programming\Python\test_violet_agent\main.py", line 1, in <module> from violet_agents import SimpleAgent File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\__init__.py", line 4, in <module> from .agents.react_agent import ReactAgent, REACT_PROMPT File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\agents\__init__.py", line 2, in <module> from .simple_agent import SimpleAgent File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\agents\simple_agent.py", line 4, in <module> from ..core.config import Config File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\__init__.py", line 2, in <module> from .agent import Agent File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\agent.py", line 10, in <module> from ..tools.registry import ToolRegistry File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\tools\__init__.py", line 3, in <module> from .builtin import WeatherTool, SkillsTool, SearchToolsTool, TerminalTool File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\tools\builtin\__init__.py", line 4, in <module> from .search_tools_tool import SearchToolsTool File "D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\tools\builtin\search_tools_tool.py", line 7, in <module> from ...core.agent import Agent, SubAgent ImportError: cannot import name 'Agent' from partially initialized module 'violet_agents.core.agent' (most likely due to a circular import) (D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\agent.py)

遇到报错，不着急，顺藤摸瓜。

追踪报错

先看报错最后一行，明确错误类型和原因

ImportError: cannot import name 'Agent' from partially initialized module 'violet_agents.core.agent' (most likely due to a circular import) (D:\programming\Python\test_violet_agent\.venv\lib\site-packages\violet_agents\core\agent.py)

• 错误类型：ImportError– 导入失败。
• 具体原因：无法从violet_agents.core.agent中导入Agent，而且模块处于“部分初始化”状态，很可能是因为循环导入（circular import）。

从下往上读，定位循环链条

Traceback 是从最底层（错误发生点）向上（调用入口）排列的，最后一行是错误本身，而上面每一行都显示了导入过程中的一环。

File "...\search_tools_tool.py", line 7, in <module> from ...core.agent import Agent, SubAgent

• 这里试图从core.agent导入Agent，是直接触发错误的地方。

再往上看，是谁导入了search_tools_tool.py？

File "...\tools\builtin\__init__.py", line 4, in <module> from .search_tools_tool import SearchToolsTool

• builtin/__init__.py导入了search_tools_tool。

继续：

File "...\tools\__init__.py", line 3, in <module> from .builtin import WeatherTool, SkillsTool, SearchToolsTool, TerminalTool

• tools/__init__.py导入了builtin包。

再往上：

File "...\core\agent.py", line 10, in <module> from ..tools.registry import ToolRegistry

• 我们发现core/agent.py里导入了tools.registry，而tools包又导入了builtin包，进而导入了search_tools_tool，而它又反过来导入core.agent——这就形成了循环。这种情况是间接循环导入，由这几个__init__.py把路铺成了闭环，简单说，就是search_tools_tool.py在执行from ...core.agent import Agent, SubAgent时，回头找还没定义完的core/agent.py。

解决方法

core/agent.py

• 将from ..tools.registry import ToolRegistry从顶层导入移入TYPE_CHECKING块
• __init__中改用懒加载：from ..tools.registry import ToolRegistry as _ToolRegistry
• 消除了core.agent↔tools.builtin.search_tools_tool之间的潜在循环导入

修改如下：

检查/防止循环导入的方法

方法一：pip install pylint

使用命令进行检查

pip install pylint pylint src/violet_agents pylint src/violet_agents --disable=all --enable=cyclic-import

方法二：pip install import-linter

/violet_agents
pylint src/violet_agents --disable=all --enable=cyclic-import

### 方法二：`pip install import-linter` 这是大型 Python 项目经常使用的工具。此处不做过多介绍