Troubleshooting Dependency Conflicts in AI Agent Projects: A Hands-On Environment Setup Guide

When developing AI Agent applications, environment setup is often the very first hurdle. Compared to model calls and agent logic design, installing dependency libraries — seemingly straightforward — is actually where beginners trip up most. This guide walks through a real multi-agent (ITS) project to explain how to properly handle dependency conflicts in requirements.txt after cloning someone else's project, ensuring a clean and functional development environment.

Background: Multi-Agent Systems (MAS) are a foundational architectural paradigm in the AI Agent space, where multiple specialized agents collaborate to complete complex tasks. ITS (Intelligent Tutoring System) is a classic MAS application, typically involving a teaching agent, an assessment agent, a learning path planning agent, and other collaborative roles. These systems have relatively complex dependency stacks — on top of the agent framework itself (e.g., LangChain, AutoGen), they layer in browser automation, network proxies, data processing, and other tooling, each with its own versioning lifecycle. This is precisely why MAS projects are far more prone to dependency conflicts during setup than single-model-call projects.

Why You Shouldn't Just Run pip install on a Cloned Project

When developers get their hands on an open-source or shared AI Agent project, their first instinct is usually to run pip install -r requirements.txt. In collaborative or project-reuse scenarios, however, this approach is a recipe for trouble.

The root cause: the dependency versions declared in someone else's project may conflict with libraries already installed in your environment. Take selenium as an example — it has breaking API changes across major versions. Forcing an overwrite installation can, at best, trigger warnings and, at worst, crash your existing projects entirely.

The right approach isn't to install blindly. It's to first conduct a dependency audit — understand what's already in your environment, then decide which entries in requirements.txt should be kept, modified, or removed.

The Hands-On Process for Resolving Dependency Conflicts

Step 1: Audit Your Current Environment with pip list

Before touching requirements.txt, you need to know what's already installed in your Python environment. Run pip list to see all installed packages and their version numbers. This is the foundation for everything that follows — you can't identify what conflicts until you know what you already have.

Step 2: Compare Line by Line, Identify Conflicts

Next, go through requirements.txt entry by entry. Here's how the conflict analysis played out in this example project:

• selenium: A classic high-risk conflict source. The current environment already has selenium installed, potentially at a different version than what the project declares. Installing it directly will overwrite the version. Action: remove this entry from requirements.
• pysocks: Not present in the current environment, and not a core dependency. Action: ignore.
• async-related libraries: Also absent from the current environment. No action needed.
• attrs: Already installed, version roughly matches the project's requirement. Action: keep as-is.
• certifi: Already present, version difference is negligible — close enough. No forced update needed.

Here's an important practical principle worth remembering: minor version differences don't require forced alignment. In the Python ecosystem, most libraries handle small version gaps with good backward compatibility. Over-engineering perfect version parity introduces unnecessary overhead. Focus your energy on dependencies that have known breaking changes.

Why selenium Is Always the First Thing to Check

The repeated focus on selenium in this walkthrough isn't arbitrary.

Selenium is the most widely used browser automation framework, and in AI Agent projects it's commonly used to give agents web interaction capabilities — automated form filling, data scraping, page screenshots, and more. Its versioning is fast-moving: the jump from 3.x to 4.x involved a major architectural overhaul with significant breaking changes, including: a complete overhaul of WebDriver management (4.x ships with a built-in driver manager, eliminating the need to manually download chromedriver), namespace changes to the Options class, and the deprecation and replacement of certain locator methods. If your environment has a working selenium installation and a new project declares a different version, installing it will break one of them.

The safest approach: remove selenium from the requirements file entirely, stick with the version already in your environment, and only upgrade it separately after confirming compatibility.

This also points to a more fundamental solution: when developing multiple projects in parallel, virtual environment isolation is the real fix.

A deeper look: Python virtual environments work by creating an isolated copy of the Python interpreter and a separate site-packages directory for each project, allowing different projects to depend on different versions of the same library without interference. Common tools include the built-in venv module (Python 3.3+), conda (the Anaconda/Miniconda ecosystem, great for scientific computing dependencies), and more modern options like Poetry and uv. In AI Agent development, frameworks like LangChain, AutoGen, and CrewAI iterate extremely fast with frequent API changes across versions. Without environment isolation, cross-project pollution is almost inevitable. The recommendation: create a dedicated virtual environment for every project, eliminating dependency conflicts at the source.

Using a Domestic Mirror to Speed Up Installation

Once you've cleaned up the requirements file, it's time to install. Here are the commands:

# Navigate to the project directory
cd mobileframework

# Install dependencies using a domestic mirror
pip install -r requirements.txt -i https://pypi.douban.com/simple/

Notice the explicit use of Douban's PyPI mirror. PyPI (Python Package Index) is Python's official package hosting platform, home to over 500,000 open-source libraries — but because its servers are overseas, access from mainland China is slow and unreliable, and installing large AI frameworks can take tens of minutes or fail entirely.

Popular domestic mirrors include Douban (pypi.douban.com), Tsinghua TUNA (pypi.tuna.tsinghua.edu.cn — the most frequently synced, approximately every 5 minutes, and currently the most recommended), and Aliyun (mirrors.aliyun.com/pypi). Using the -i flag to temporarily specify a mirror can improve installation speed by 10x or more. For a permanent default, edit ~/.pip/pip.conf (Linux/macOS) or %APPDATA%\pip\pip.ini (Windows).

Once installation completes without errors in the console, your project's dependency environment is essentially ready — you can move on to building the agent's business logic.

Environment Setup Checklist

Here's the full process distilled into a reusable checklist:

1. Audit your current environment: Run pip list to confirm installed packages and their versions.
2. Compare against requirements: Go through project dependencies line by line, identify entries that conflict with your local environment.
3. Remove conflicting entries: Pay special attention to libraries like selenium that are known to cause version conflicts.
4. Run the install command: Navigate to the project directory and install remaining dependencies using a domestic mirror.
5. Verify the result: Confirm no errors before moving to the next development phase.

Final Thoughts

Environment setup may seem unglamorous, but it's the prerequisite for any AI Agent project to move forward smoothly. It reflects a broader truth in engineering: building AI applications isn't just about writing prompts and calling APIs — solid engineering fundamentals matter just as much. Skills like dependency management, environment isolation, and mirror configuration may seem like minor details, but they're often what determines whether a project runs at all.

For anyone learning multi-agent systems or building Coze applications, the advice is: get your environment setup right before writing a single line of business logic. And going further — start building the habit of using virtual environments now. When you're juggling multiple agent projects simultaneously, it'll save you countless hours of repeated dependency conflict debugging.