ModuleNotFoundError when deploying multi-agent system with src/ layout and cross-module imports

[this-dave]

Environment

google-cloud-aiplatform
google-adk: latest
Python: 3.13
Deployment method: agent_engines.create() via custom deployment script
Project structure: Poetry-based with src/ layout

Problem Description

I'm encountering persistent ModuleNotFoundError: No module named 'agents' when deploying a multi-agent ADK system to Vertex AI Agent Engine, despite the code working perfectly locally. This appears related to #2044 but with additional complexity due to multi-agent architecture.

Project Structure

project-root/
├── src/
│   ├── agents/
│   │   ├── supervisor_agent/
│   │   │   └── agent.py
│   │   ├── jira_closing_agent/
│   │   │   ├── agent.py
│   │   │   └── tools/
│   │   │       ├── get_project_details.py
│   │   │       └── update_project_settings.py
│   │   └── search_agent/
│   │       └── agent.py
│   ├── core/
│   │   ├── integrations/
│   │   │   ├── jira/
│   │   │   │   ├── projects.py
│   │   │   │   └── issues.py
│   │   │   └── tempo/
│   │   │       └── financial_projects.py
│   │   └── config.py
├── ops/
│   └── scripts/
│       └── deploy_agents.py
├── pyproject.toml
└── uv.lock

The Issue

Tools in agents/*/tools/ import from core.integrations.*:

# In agents/jira_closing_agent/tools/get_project_details.py
from core.integrations.jira.projects import get_project, is_user_project_lead
from core.integrations.jira.issues import search_issues

The supervisor agent imports sub-agents:

python# In agents/supervisor_agent/agent.py
from agents.jira_closing_agent.agent import jira_closing_agent
from agents.search_agent.agent import search_agent

Deployment Attempt

python# deploy_agents.py
extra_packages = [str(project_root)]  # Have also tried [str(project_root / "src")]

remote_agent = agent_engines.create(
    agent_engine=app,
    requirements=AGENT_REQUIREMENTS,
    extra_packages=extra_packages,
    display_name=f"supervisor-agent-{environment}",
    # ...
)

Error Log

ModuleNotFoundError: No module named 'agents'
  File "/code/app/api/factory/utils.py", line 177, in get_local_object
    return cloudpickle.loads(f.read())

What I've Tried

Different extra_packages configurations:

[str(project_root)]
[str(project_root / "src")]
Building wheel with Poetry and including it

sys.path manipulation (breaks cloudpickle serialization)
Modifying pyproject.toml:

toml[tool.setuptools.package-dir]
"" = "src"

[tool.setuptools.packages.find]
where = ["src"]
Questions

1. Is there a recommended approach for deploying ADK agents with clean, modular architecture? We need to maintain separation between reusable core modules and agent-specific code for maintainability.
2. Would cloudpickle's register_pickle_by_value() work here? Has anyone successfully used this with Agent Engine deployments?
3. Are there plans to improve support for standard Python project structures? The src/ layout is widely adopted in the Python community for good reasons (editable installs, import clarity, etc.).
4. Is Cloud Run the only viable option for complex multi-module projects? We'd prefer Agent Engine for its agent-specific optimizations, but need our modular structure.

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The most robust way to resolve this is to build your project into a standard Python wheel (.whl) file and pass the path to that wheel in the extra_packages argument of agent_engines.create(). This ensures your agents and core modules are properly installed in the deployment environment.

---

Hello @this-dave, thank you for the detailed question. This is a great question about Python packaging and deployment, which can be tricky. Here’s a breakdown of the issue and our recommended solution.

The Problem: Python Path on Agent Engine

When you run your code locally, your environment (like Poetry or your IDE) often adds your project's src directory to the Python path (sys.path). This is why imports like from agents... and from core... work on your machine.

However, when you deploy to Vertex AI Agent Engine, the remote environment receives your code but doesn't automatically know about your specific project structure. It doesn't add src to the Python path, leading to the ModuleNotFoundError when your agent is deserialized and its modules can't be found.

The Solution: Package Your Code as a Wheel

The extra_packages argument in agent_engines.create() is the correct mechanism to solve this. It tells Agent Engine to include and install additional local packages. Instead of passing a source directory, the most reliable method is to pass a pre-built wheel file.

Here is the recommended approach:

1. Configure pyproject.toml

Your pyproject.toml configuration for setuptools looks correct for a src layout. This tells the build tools that your packages (agents, core, etc.) are located inside the src directory.

[tool.setuptools.package-dir]
"" = "src"

[tool.setuptools.packages.find]
where = ["src"]

2. Build the Wheel

From your project root, generate the wheel file. You can use poetry or build.

# If you are using Poetry
poetry build

# Or using the standard 'build' package
# pip install build
python -m build --wheel

This will create a dist/ directory containing your wheel file (e.g., dist/your_project_name-0.1.0-py3-none-any.whl).

3. Update Your Deployment Script

Now, modify your deploy_agents.py to point extra_packages to the path of the newly created wheel file.

# deploy_agents.py
import os

# Assuming your script is in ops/scripts/
project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
# NOTE: Update the wheel file name to match the one you generated.
wheel_path = os.path.join(project_root, 'dist', 'your_project_name-0.1.0-py3-none-any.whl')

remote_agent = agent_engines.create(
    agent_engine=app,
    requirements=AGENT_REQUIREMENTS,
    # Pass the path to the built wheel file
    extra_packages=[wheel_path],
    display_name=f"supervisor-agent-{environment}",
    # ...
)

When you run this, agent_engines.create will upload the wheel, and the Agent Engine service will pip install it into the container. This correctly places your agents and core packages into the environment's site-packages, making them globally importable.

Answering Your Other Questions

1. Recommended approach for modular architecture?
   Packaging your modules into a wheel is the standard and recommended Python practice. It creates a formal, distributable artifact that works consistently across different environments, from local testing to cloud deployment.

2. Would cloudpickle.register_pickle_by_value() work?
   While it might be a possible workaround, it's not recommended. It makes cloudpickle serialize the raw source code of your objects instead of their import paths. This can make your serialized agent object very large and can be brittle. Proper packaging is the cleaner, more robust solution.

3. Plans to improve support for standard Python project structures?
   ADK deployment via agent_engines.create already supports these structures through the extra_packages argument. The key is that the Python ecosystem relies on packaging (like wheels) to formally define how a project's code is structured and should be installed. The documentation example extra_packages=["./weather_agent"] [6] works because it's a simple, self-contained package in the same directory, but for a src layout, building a wheel is the canonical solution.

4. Is Cloud Run the only viable option?
   No, Agent Engine is absolutely designed to handle complex, multi-module projects like yours. [1] The issue you're encountering is purely about packaging and Python path configuration, not a limitation of Agent Engine. By providing a wheel, you give Agent Engine all the information it needs to construct the correct environment for your agent.

I hope this helps you resolve the deployment issue! Let us know if you have any other questions.