Google ADK-Python 项目中解决模块导入错误的完整指南

在开发基于Google ADK-Python框架的AI代理应用时，很多开发者会遇到"ModuleNotFoundError: No module named 'google_search_agent'"的错误。这个问题看似简单，但实际上涉及到了Python模块系统、项目结构设计以及ADK框架使用规范等多个技术要点。

问题本质分析

这个错误的核心在于Python解释器无法找到名为'google_search_agent'的模块。在ADK-Python框架中，这通常意味着项目结构不符合框架预期或者模块导入路径设置不正确。

正确的项目结构

根据ADK框架的设计规范，一个标准的流式处理应用项目应该遵循以下目录结构：

adk-streaming/
├── app/
│   ├── .env
│   ├── google_search_agent/
│   │   ├── __init__.py
│   │   └── agent.py
│   ├── static/
│   │   └── index.html
│   └── main.py
└── requirements.txt

关键点在于google_search_agent必须作为一个Python包存在，这意味着它需要包含__init__.py文件。这个文件可以是空的，但必须存在才能使Python将其识别为一个包。

解决方案详解

方案一：修复项目结构

1. 在app目录下创建google_search_agent子目录
2. 在该子目录中创建__init__.py文件
3. 创建agent.py文件并定义root_agent

agent.py内容示例：

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="basic_search_agent",
    model="gemini-2.0-flash-live-001",
    description="Agent to answer questions using Google Search.",
    instruction="You are an expert researcher.",
    tools=[google_search]
)

方案二：直接在主文件中定义

如果不想创建额外的包结构，也可以直接在main.py中定义root_agent：

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="basic_search_agent",
    model="gemini-2.0-flash-live-001",
    description="Agent to answer questions using Google Search.",
    instruction="You are an expert researcher.",
    tools=[google_search]
)

常见陷阱与解决方案

1. 工具导入错误：文档中曾错误地使用了built_in_google_search，正确应为google_search

2. 相对导入问题：确保__init__.py中包含正确的导入语句：

   from . import agent
   

3. 运行目录问题：执行命令时确保在正确的目录层级，通常应该在项目根目录(adk-streaming/)下运行

最佳实践建议

1. 始终遵循ADK框架推荐的项目结构
2. 使用虚拟环境隔离项目依赖
3. 在开发过程中使用adk web命令测试代理
4. 保持文档更新，注意框架版本变化

通过理解这些原理和实践，开发者可以避免类似的模块导入问题，并构建出符合ADK框架规范的AI代理应用。记住，良好的项目结构不仅是让代码运行的前提，也是团队协作和项目维护的基础。