Virtual Environments - Isolation for Agent Projects

When you install langgraph for one agent project and openai upgrades for another, a globally installed Python turns every change into a coin-flip: which project breaks today? Agent stacks ship breaking releases often — LangChain 0.1 to 0.3, OpenAI SDK 0.x to 1.x, Anthropic SDK feature drops — and without isolation a single pip install can silently shift versions under another project's feet, producing "works on my laptop, fails in CI" stalls that cost hours per incident.

By the end of this lesson you will be able to create a per-project Python virtual environment with venv, activate it on Unix/macOS or Windows, verify isolation with sys.executable, and use Poetry to declare dependencies in pyproject.toml plus pin them in poetry.lock so every teammate and CI run installs the same versions.

• Virtual environment — an isolated directory (commonly .venv/) containing its own Python interpreter and site-packages; activating it puts that interpreter first on PATH so package installs stay local to one project. Without it, agent SDK upgrades collide across projects.
• pyproject.toml — the single declarative file that lists your project's metadata and dependency ranges (e.g. langgraph = "^0.2.0"). It is what humans edit and what Poetry reads to resolve versions.
• poetry.lock — an auto-generated file pinning the exact resolved versions of every direct and transitive dependency. Committed to git, it is the contract that guarantees poetry install produces the same tree on every machine.
• Dependency group — a labelled subset of dependencies in pyproject.toml (e.g. group.dev, group.test) installed only when explicitly requested, so production images stay free of test or lint tooling.
• Transitive dependency — a package pulled in because something you asked for depends on it (e.g. httpx arrives via openai). Lock files matter precisely because these are the versions most likely to drift unnoticed.

Why isolation is the default for agent projects

Agent codebases pull in fast-moving stacks: langchain-core, langgraph, openai, anthropic, plus model-side libraries like pydantic that get tugged in two directions by different SDKs. Installing globally means the latest install wins for every project on the machine. A virtual environment gives each project its own site-packages so version pins are scoped to one directory and one PATH mutation, not the whole user account.

Activation is just a PATH prepend plus a shell prompt change — there is no kernel magic. Once .venv/bin is first on PATH, python, pip, and any console-script entry point resolve to the isolated copies. Deactivating restores the original PATH.

From venv to Poetry: declarative dependencies and locking

venv solves isolation but not reproducibility — pip install openai today may fetch a different version tomorrow. Poetry layers two pieces on top: pyproject.toml declares the version ranges you accept (^1.40.0), and poetry.lock records the exact versions that satisfied those ranges when you last resolved. CI and teammates run poetry install and get an identical tree (see Code Walkthrough).

Dependency groups (group.dev, group.test) let you keep pytest, mypy, and ruff out of production installs while still tracking them in source control.

The first snippet creates and verifies an isolated venv from scratch — the minimum needed before any pip install. The second migrates the same project to Poetry so the dependency set is declarative and the resolved versions are locked.

Code snippetbash
1# 1. Create and activate an isolated environment in the project root.
2python -m venv .venv
3source .venv/bin/activate            # Unix/macOS
4# .venv\Scripts\Activate.ps1         # Windows PowerShell
5
6# 2. Confirm PATH now points at the isolated interpreter, not the system one.
7python -c "import sys, site; print(sys.executable); print(site.getsitepackages())"
8# Expected: paths beginning with the absolute path to .venv/
9
10# 3. Install agent SDKs only into this venv.
11pip install --upgrade pip
12pip install "openai>=1.40,<2" "anthropic>=0.34,<1" "langgraph>=0.2,<0.3"
13
14# 4. Leave the environment cleanly when you're done.
15deactivate

Code snippettoml
1# pyproject.toml — declarative replacement for ad-hoc pip installs.
2[tool.poetry]
3name = "my-agent"
4version = "0.1.0"
5description = "Production AI agent"
6
7[tool.poetry.dependencies]
8python    = "^3.11"
9openai    = "^1.40.0"
10anthropic = "^0.34.0"
11langgraph = "^0.2.0"
12
13[tool.poetry.group.dev.dependencies]
14pytest = "^8.0.0"
15ruff   = "^0.6.0"
16
17[build-system]
18requires      = ["poetry-core"]
19build-backend = "poetry.core.masonry.api"

After saving pyproject.toml, run poetry config virtualenvs.in-project true once, then poetry install — Poetry creates .venv/, resolves the ranges, and writes poetry.lock. Commit both files (git add pyproject.toml poetry.lock) so CI and teammates reproduce the exact tree.

You'll know it works when python -c "import sys; print(sys.executable)" (or poetry run python -c ...) prints a path inside your project's .venv/, pip list shows only the SDKs you installed (not your machine's global packages), and a fresh poetry install on another machine produces the same versions listed in poetry.lock.

Do's

1. ✓Do create a .venv/ in every new agent project before the first pip install — once a project's first dependency lands in the global interpreter, untangling later is far more expensive than starting clean.
2. ✓Do commit both pyproject.toml and poetry.lock — the lock file is what makes "works on my machine" reproducible on a teammate's machine and in CI.
3. ✓Do put pytest, mypy, and ruff in group.dev — production images stay smaller and unrelated tool upgrades cannot break runtime resolution.

Don'ts

1. ✗Don't pip install into the system Python for "just a quick test" — quick tests are how agent SDK conflicts get introduced; activate a venv first, always.
2. ✗Don't edit poetry.lock by hand — regenerate it with poetry lock or poetry add; manual edits desync ranges from pinned versions and silently break reproducibility.
3. ✗Don't commit .venv/ — gitignore it — the venv is machine-specific and large; only pyproject.toml and poetry.lock belong in version control.