ನಿಮ್ಮ agent ನ Python environment ಅನ್ನು ಪ್ರತ್ಯೇಕಿಸಿ

ಪರಿಚಯ

ನೀವು ಒಂದು ಏಜೆಂಟ್ ಪ್ರಾಜೆಕ್ಟ್‌ಗಾಗಿ langgraph ಇನ್‌ಸ್ಟಾಲ್ ಮಾಡಿ, ಇನ್ನೊಂದಕ್ಕಾಗಿ openai ಅನ್ನು ಅಪ್‌ಗ್ರೇಡ್ ಮಾಡಿದಾಗ, ಗ್ಲೋಬಲ್ ಆಗಿ ಇನ್‌ಸ್ಟಾಲ್ ಆದ Python ಪ್ರತಿ ಬದಲಾವಣೆಯನ್ನೂ ನಾಣ್ಯ ಚಿಮ್ಮುವ ಜೂಜಾಗಿಸುತ್ತದೆ: ಇಂದು ಯಾವ ಪ್ರಾಜೆಕ್ಟ್ ಮುರಿಯುತ್ತದೆ? ಏಜೆಂಟ್ ಸ್ಟ್ಯಾಕ್‌ಗಳು ಆಗಾಗ್ಗೆ ಬ್ರೇಕಿಂಗ್ ರಿಲೀಸ್‌ಗಳನ್ನು ಹೊರತರುತ್ತವೆ — LangChain 0.1 ರಿಂದ 0.3, OpenAI SDK 0.x ರಿಂದ 1.x, Anthropic SDK ಫೀಚರ್ ಡ್ರಾಪ್‌ಗಳು — ಮತ್ತು ಪ್ರತ್ಯೇಕತೆ ಇಲ್ಲದಿದ್ದರೆ ಒಂದೇ ಒಂದು pip install ಇನ್ನೊಂದು ಪ್ರಾಜೆಕ್ಟ್‌ನ ಕಾಲಡಿಯಲ್ಲಿ ಆವೃತ್ತಿಗಳನ್ನು ಮೌನವಾಗಿ ಬದಲಾಯಿಸಬಹುದು, ಇದರಿಂದ "ನನ್ನ ಲ್ಯಾಪ್‌ಟಾಪ್‌ನಲ್ಲಿ ಕೆಲಸ ಮಾಡುತ್ತದೆ, CI ನಲ್ಲಿ ವಿಫಲವಾಗುತ್ತದೆ" ಎಂಬ ಸ್ಥಗಿತಗಳು ಉಂಟಾಗಿ ಪ್ರತಿ ಘಟನೆಗೂ ಗಂಟೆಗಟ್ಟಲೆ ಸಮಯ ವ್ಯಯವಾಗುತ್ತದೆ.

ಈ ಪಾಠದ ಕೊನೆಯ ವೇಳೆಗೆ ನೀವು venv ಬಳಸಿ ಪ್ರತಿ ಪ್ರಾಜೆಕ್ಟ್‌ಗೆ ಪ್ರತ್ಯೇಕ Python ವರ್ಚುವಲ್ ಎನ್ವಿರಾನ್‌ಮೆಂಟ್ ರಚಿಸಲು, ಅದನ್ನು Unix/macOS ಅಥವಾ Windows ನಲ್ಲಿ ಆಕ್ಟಿವೇಟ್ ಮಾಡಲು, sys.executable ಮೂಲಕ ಪ್ರತ್ಯೇಕತೆಯನ್ನು ಪರಿಶೀಲಿಸಲು, ಮತ್ತು Poetry ಬಳಸಿ pyproject.toml ನಲ್ಲಿ ಡಿಪೆಂಡೆನ್ಸಿಗಳನ್ನು ಘೋಷಿಸಿ poetry.lock ನಲ್ಲಿ ಅವುಗಳನ್ನು ಪಿನ್ ಮಾಡಲು ಸಾಧ್ಯವಾಗುತ್ತದೆ, ಇದರಿಂದ ಪ್ರತಿ ತಂಡದ ಸದಸ್ಯ ಮತ್ತು CI ರನ್ ಒಂದೇ ಆವೃತ್ತಿಗಳನ್ನು ಇನ್‌ಸ್ಟಾಲ್ ಮಾಡುತ್ತದೆ.

ಪ್ರಮುಖ ಪರಿಭಾಷೆ

• ವರ್ಚುವಲ್ ಎನ್ವಿರಾನ್‌ಮೆಂಟ್ — ತನ್ನದೇ ಆದ Python ಇಂಟರ್‌ಪ್ರಿಟರ್ ಮತ್ತು site-packages ಹೊಂದಿರುವ ಪ್ರತ್ಯೇಕ ಡೈರೆಕ್ಟರಿ (ಸಾಮಾನ್ಯವಾಗಿ .venv/); ಅದನ್ನು ಆಕ್ಟಿವೇಟ್ ಮಾಡಿದಾಗ ಆ ಇಂಟರ್‌ಪ್ರಿಟರ್ PATH ನಲ್ಲಿ ಮೊದಲಿಗೆ ಬರುತ್ತದೆ, ಹೀಗಾಗಿ ಪ್ಯಾಕೇಜ್ ಇನ್‌ಸ್ಟಾಲ್‌ಗಳು ಒಂದು ಪ್ರಾಜೆಕ್ಟ್‌ಗೆ ಮಾತ್ರ ಸೀಮಿತವಾಗಿರುತ್ತವೆ. ಇದಿಲ್ಲದಿದ್ದರೆ, ಏಜೆಂಟ್ SDK ಅಪ್‌ಗ್ರೇಡ್‌ಗಳು ಪ್ರಾಜೆಕ್ಟ್‌ಗಳ ನಡುವೆ ಘರ್ಷಣೆಗೊಳ್ಳುತ್ತವೆ.
• pyproject.toml — ನಿಮ್ಮ ಪ್ರಾಜೆಕ್ಟ್‌ನ ಮೆಟಾಡೇಟಾ ಮತ್ತು ಡಿಪೆಂಡೆನ್ಸಿ ಶ್ರೇಣಿಗಳನ್ನು (ಉದಾ. langgraph = "^0.2.0") ಪಟ್ಟಿ ಮಾಡುವ ಏಕೈಕ ಡಿಕ್ಲರೇಟಿವ್ ಫೈಲ್. ಇದನ್ನು ಮನುಷ್ಯರು ಸಂಪಾದಿಸುತ್ತಾರೆ ಮತ್ತು ಆವೃತ್ತಿಗಳನ್ನು ರಿಸಾಲ್ವ್ ಮಾಡಲು Poetry ಇದನ್ನು ಓದುತ್ತದೆ.
• poetry.lock — ಪ್ರತಿ ನೇರ ಮತ್ತು ಟ್ರಾನ್ಸಿಟಿವ್ ಡಿಪೆಂಡೆನ್ಸಿಯ ನಿಖರವಾಗಿ ರಿಸಾಲ್ವ್ ಆದ ಆವೃತ್ತಿಗಳನ್ನು ಪಿನ್ ಮಾಡುವ ಸ್ವಯಂ-ರಚಿತ ಫೈಲ್. git ಗೆ ಕಮಿಟ್ ಆಗಿರುವ ಇದು, poetry install ಪ್ರತಿ ಯಂತ್ರದಲ್ಲೂ ಒಂದೇ ಟ್ರೀ ಅನ್ನು ಉತ್ಪಾದಿಸುತ್ತದೆ ಎಂದು ಖಾತರಿಪಡಿಸುವ ಒಪ್ಪಂದ.
• ಡಿಪೆಂಡೆನ್ಸಿ ಗ್ರೂಪ್ — pyproject.toml ನಲ್ಲಿ ಲೇಬಲ್ ಮಾಡಲಾದ ಡಿಪೆಂಡೆನ್ಸಿಗಳ ಉಪವಿಭಾಗ (ಉದಾ. group.dev, group.test), ಇದನ್ನು ಸ್ಪಷ್ಟವಾಗಿ ಕೇಳಿದಾಗ ಮಾತ್ರ ಇನ್‌ಸ್ಟಾಲ್ ಮಾಡಲಾಗುತ್ತದೆ, ಹೀಗಾಗಿ ಪ್ರೊಡಕ್ಷನ್ ಇಮೇಜ್‌ಗಳು ಟೆಸ್ಟ್ ಅಥವಾ ಲಿಂಟ್ ಟೂಲಿಂಗ್‌ನಿಂದ ಮುಕ್ತವಾಗಿರುತ್ತವೆ.
• ಟ್ರಾನ್ಸಿಟಿವ್ ಡಿಪೆಂಡೆನ್ಸಿ — ನೀವು ಕೇಳಿದ ಯಾವುದೋ ಪ್ಯಾಕೇಜ್ ಅದನ್ನು ಅವಲಂಬಿಸಿರುವುದರಿಂದ ಒಳಗೆ ಬರುವ ಪ್ಯಾಕೇಜ್ (ಉದಾ. httpx openai ಮೂಲಕ ಬರುತ್ತದೆ). ಲಾಕ್ ಫೈಲ್‌ಗಳು ಮುಖ್ಯವಾಗುವುದು ನಿಖರವಾಗಿ ಇದಕ್ಕಾಗಿಯೇ — ಇವುಗಳ ಆವೃತ್ತಿಗಳೇ ಗಮನಕ್ಕೆ ಬಾರದೆ ಬದಲಾಗುವ ಸಾಧ್ಯತೆ ಹೆಚ್ಚು.

ಪರಿಕಲ್ಪನೆಗಳು

ಏಜೆಂಟ್ ಪ್ರಾಜೆಕ್ಟ್‌ಗಳಿಗೆ ಪ್ರತ್ಯೇಕತೆ ಏಕೆ ಡೀಫಾಲ್ಟ್ ಆಗಿದೆ

ಏಜೆಂಟ್ ಕೋಡ್‌ಬೇಸ್‌ಗಳು ವೇಗವಾಗಿ ಬದಲಾಗುವ ಸ್ಟ್ಯಾಕ್‌ಗಳನ್ನು ಒಳಗೆ ತರುತ್ತವೆ: langchain-core, langgraph, openai, anthropic, ಜೊತೆಗೆ pydantic ನಂತಹ ಮಾಡೆಲ್-ಕಡೆಯ ಲೈಬ್ರರಿಗಳು, ಇವುಗಳನ್ನು ಬೇರೆ ಬೇರೆ SDK ಗಳು ಎರಡು ದಿಕ್ಕುಗಳಿಗೆ ಎಳೆಯುತ್ತವೆ. ಗ್ಲೋಬಲ್ ಆಗಿ ಇನ್‌ಸ್ಟಾಲ್ ಮಾಡುವುದೆಂದರೆ ಯಂತ್ರದಲ್ಲಿರುವ ಪ್ರತಿ ಪ್ರಾಜೆಕ್ಟ್‌ಗೂ ಇತ್ತೀಚಿನ ಇನ್‌ಸ್ಟಾಲ್ ಗೆಲ್ಲುತ್ತದೆ. ವರ್ಚುವಲ್ ಎನ್ವಿರಾನ್‌ಮೆಂಟ್ ಪ್ರತಿ ಪ್ರಾಜೆಕ್ಟ್‌ಗೂ ತನ್ನದೇ ಆದ site-packages ನೀಡುತ್ತದೆ, ಹೀಗಾಗಿ ಆವೃತ್ತಿ ಪಿನ್‌ಗಳು ಇಡೀ ಬಳಕೆದಾರ ಖಾತೆಗೆ ಅಲ್ಲದೆ ಒಂದು ಡೈರೆಕ್ಟರಿ ಮತ್ತು ಒಂದು PATH ಬದಲಾವಣೆಗೆ ಸೀಮಿತವಾಗಿರುತ್ತವೆ.

ಆಕ್ಟಿವೇಶನ್ ಎಂದರೆ ಕೇವಲ PATH ಗೆ ಮುಂದೆ ಸೇರಿಸುವುದು ಮತ್ತು ಶೆಲ್ ಪ್ರಾಂಪ್ಟ್ ಬದಲಾವಣೆ — ಇಲ್ಲಿ ಯಾವುದೇ ಕರ್ನಲ್ ಮ್ಯಾಜಿಕ್ ಇಲ್ಲ. .venv/bin PATH ನಲ್ಲಿ ಮೊದಲಿಗೆ ಬಂದ ನಂತರ, python, pip, ಮತ್ತು ಯಾವುದೇ ಕನ್ಸೋಲ್-ಸ್ಕ್ರಿಪ್ಟ್ ಎಂಟ್ರಿ ಪಾಯಿಂಟ್ ಪ್ರತ್ಯೇಕ ಪ್ರತಿಗಳಿಗೆ ರಿಸಾಲ್ವ್ ಆಗುತ್ತವೆ. ಡೀಆಕ್ಟಿವೇಟ್ ಮಾಡಿದರೆ ಮೂಲ PATH ಮರಳುತ್ತದೆ.

venv ನಿಂದ Poetry ವರೆಗೆ: ಡಿಕ್ಲರೇಟಿವ್ ಡಿಪೆಂಡೆನ್ಸಿಗಳು ಮತ್ತು ಲಾಕಿಂಗ್

venv ಪ್ರತ್ಯೇಕತೆಯನ್ನು ಪರಿಹರಿಸುತ್ತದೆ ಆದರೆ ಪುನರುತ್ಪಾದನೆಯನ್ನು ಅಲ್ಲ — ಇಂದು pip install openai ಮಾಡಿದರೆ ನಾಳೆ ಬೇರೆ ಆವೃತ್ತಿ ಬರಬಹುದು. Poetry ಇದರ ಮೇಲೆ ಎರಡು ಅಂಶಗಳನ್ನು ಸೇರಿಸುತ್ತದೆ: pyproject.toml ನೀವು ಒಪ್ಪುವ ಆವೃತ್ತಿ ಶ್ರೇಣಿಗಳನ್ನು (^1.40.0) ಘೋಷಿಸುತ್ತದೆ, ಮತ್ತು poetry.lock ನೀವು ಕೊನೆಯ ಬಾರಿ ರಿಸಾಲ್ವ್ ಮಾಡಿದಾಗ ಆ ಶ್ರೇಣಿಗಳನ್ನು ತೃಪ್ತಿಪಡಿಸಿದ ನಿಖರ ಆವೃತ್ತಿಗಳನ್ನು ದಾಖಲಿಸುತ್ತದೆ. CI ಮತ್ತು ತಂಡದ ಸದಸ್ಯರು poetry install ರನ್ ಮಾಡಿ ಒಂದೇ ರೀತಿಯ ಟ್ರೀ ಪಡೆಯುತ್ತಾರೆ (ಕೋಡ್ ವಾಕ್‌ಥ್ರೂ ನೋಡಿ).

ಡಿಪೆಂಡೆನ್ಸಿ ಗ್ರೂಪ್‌ಗಳು (group.dev, group.test) pytest, mypy, ಮತ್ತು ruff ಅನ್ನು ಪ್ರೊಡಕ್ಷನ್ ಇನ್‌ಸ್ಟಾಲ್‌ಗಳಿಂದ ಹೊರಗಿಡುತ್ತಲೇ ಅವುಗಳನ್ನು ಸೋರ್ಸ್ ಕಂಟ್ರೋಲ್‌ನಲ್ಲಿ ಟ್ರ್ಯಾಕ್ ಮಾಡಲು ಅನುವು ಮಾಡಿಕೊಡುತ್ತವೆ.

ಕೋಡ್ ವಾಕ್‌ಥ್ರೂ

ಮೊದಲ ಸ್ನಿಪೆಟ್ ಶೂನ್ಯದಿಂದ ಪ್ರತ್ಯೇಕ venv ಅನ್ನು ರಚಿಸಿ ಪರಿಶೀಲಿಸುತ್ತದೆ — ಯಾವುದೇ pip install ಗೂ ಮುನ್ನ ಬೇಕಾದ ಕನಿಷ್ಠ ಹಂತ. ಎರಡನೆಯದು ಅದೇ ಪ್ರಾಜೆಕ್ಟ್ ಅನ್ನು Poetry ಗೆ ವಲಸೆ ಮಾಡಿಸುತ್ತದೆ, ಇದರಿಂದ ಡಿಪೆಂಡೆನ್ಸಿ ಸೆಟ್ ಡಿಕ್ಲರೇಟಿವ್ ಆಗುತ್ತದೆ ಮತ್ತು ರಿಸಾಲ್ವ್ ಆದ ಆವೃತ್ತಿಗಳು ಲಾಕ್ ಆಗುತ್ತವೆ.

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"

pyproject.toml ಅನ್ನು ಉಳಿಸಿದ ನಂತರ, ಒಮ್ಮೆ poetry config virtualenvs.in-project true ರನ್ ಮಾಡಿ, ನಂತರ poetry install ಮಾಡಿ — Poetry .venv/ ಅನ್ನು ರಚಿಸುತ್ತದೆ, ಶ್ರೇಣಿಗಳನ್ನು ರಿಸಾಲ್ವ್ ಮಾಡುತ್ತದೆ, ಮತ್ತು poetry.lock ಅನ್ನು ಬರೆಯುತ್ತದೆ. CI ಮತ್ತು ತಂಡದ ಸದಸ್ಯರು ನಿಖರವಾದ ಟ್ರೀ ಅನ್ನು ಪುನರುತ್ಪಾದಿಸುವಂತೆ ಎರಡೂ ಫೈಲ್‌ಗಳನ್ನು ಕಮಿಟ್ ಮಾಡಿ (git add pyproject.toml poetry.lock).

python -c "import sys; print(sys.executable)" (ಅಥವಾ poetry run python -c ...) ನಿಮ್ಮ ಪ್ರಾಜೆಕ್ಟ್‌ನ .venv/ ಒಳಗಿನ ಪಾತ್ ಅನ್ನು ಮುದ್ರಿಸಿದಾಗ, pip list ನೀವು ಇನ್‌ಸ್ಟಾಲ್ ಮಾಡಿದ SDK ಗಳನ್ನು ಮಾತ್ರ ತೋರಿಸಿದಾಗ (ನಿಮ್ಮ ಯಂತ್ರದ ಗ್ಲೋಬಲ್ ಪ್ಯಾಕೇಜ್‌ಗಳನ್ನಲ್ಲ), ಮತ್ತು ಇನ್ನೊಂದು ಯಂತ್ರದಲ್ಲಿ ಹೊಸದಾಗಿ poetry install ಮಾಡಿದಾಗ poetry.lock ನಲ್ಲಿ ಪಟ್ಟಿಯಾದ ಅದೇ ಆವೃತ್ತಿಗಳು ಬಂದಾಗ, ಇದು ಕೆಲಸ ಮಾಡುತ್ತಿದೆ ಎಂದು ನಿಮಗೆ ತಿಳಿಯುತ್ತದೆ.

ಶಿಸ್ತು ಅನ್ವಯ

ಮಾಡಬೇಕಾದವು ಮತ್ತು ಮಾಡಬಾರದವು

ಮಾಡಬೇಕಾದವು

1. ಪ್ರತಿ ಹೊಸ ಏಜೆಂಟ್ ಪ್ರಾಜೆಕ್ಟ್‌ನಲ್ಲಿ ಮೊದಲ pip install ಗೂ ಮುನ್ನ .venv/ ರಚಿಸಿ — ಪ್ರಾಜೆಕ್ಟ್‌ನ ಮೊದಲ ಡಿಪೆಂಡೆನ್ಸಿ ಗ್ಲೋಬಲ್ ಇಂಟರ್‌ಪ್ರಿಟರ್‌ನಲ್ಲಿ ಇಳಿದ ನಂತರ, ಅದನ್ನು ಬಿಡಿಸುವುದು ಶುದ್ಧವಾಗಿ ಆರಂಭಿಸುವುದಕ್ಕಿಂತ ಬಹಳ ದುಬಾರಿ.
2. pyproject.toml ಮತ್ತು poetry.lock ಎರಡನ್ನೂ ಕಮಿಟ್ ಮಾಡಿ — "ನನ್ನ ಯಂತ್ರದಲ್ಲಿ ಕೆಲಸ ಮಾಡುತ್ತದೆ" ಎಂಬುದನ್ನು ತಂಡದ ಸದಸ್ಯರ ಯಂತ್ರದಲ್ಲಿ ಮತ್ತು CI ನಲ್ಲಿ ಪುನರುತ್ಪಾದಿಸುವಂತೆ ಮಾಡುವುದು ಲಾಕ್ ಫೈಲ್.
3. pytest, mypy, ಮತ್ತು ruff ಅನ್ನು group.dev ನಲ್ಲಿ ಇಡಿ — ಪ್ರೊಡಕ್ಷನ್ ಇಮೇಜ್‌ಗಳು ಚಿಕ್ಕದಾಗಿರುತ್ತವೆ ಮತ್ತು ಸಂಬಂಧವಿಲ್ಲದ ಟೂಲ್ ಅಪ್‌ಗ್ರೇಡ್‌ಗಳು ರನ್‌ಟೈಮ್ ರಿಸಲ್ಯೂಶನ್ ಅನ್ನು ಮುರಿಯಲಾರವು.

ಮಾಡಬಾರದವು

1. "ಕೇವಲ ಒಂದು ತ್ವರಿತ ಪರೀಕ್ಷೆಗಾಗಿ" ಸಿಸ್ಟಮ್ Python ಗೆ pip install ಮಾಡಬೇಡಿ — ತ್ವರಿತ ಪರೀಕ್ಷೆಗಳಿಂದಲೇ ಏಜೆಂಟ್ SDK ಘರ್ಷಣೆಗಳು ಹುಟ್ಟಿಕೊಳ್ಳುತ್ತವೆ; ಯಾವಾಗಲೂ ಮೊದಲು venv ಅನ್ನು ಆಕ್ಟಿವೇಟ್ ಮಾಡಿ.
2. poetry.lock ಅನ್ನು ಕೈಯಾರೆ ಸಂಪಾದಿಸಬೇಡಿ — poetry lock ಅಥವಾ poetry add ಮೂಲಕ ಅದನ್ನು ಮರುರಚಿಸಿ; ಕೈಯಾರೆ ಮಾಡಿದ ಸಂಪಾದನೆಗಳು ಶ್ರೇಣಿಗಳನ್ನು ಪಿನ್ ಆದ ಆವೃತ್ತಿಗಳಿಂದ ಬೇರ್ಪಡಿಸಿ ಪುನರುತ್ಪಾದನೆಯನ್ನು ಮೌನವಾಗಿ ಮುರಿಯುತ್ತವೆ.
3. .venv/ ಅನ್ನು ಕಮಿಟ್ ಮಾಡಬೇಡಿ — ಅದನ್ನು gitignore ಮಾಡಿ — venv ಯಂತ್ರ-ನಿರ್ದಿಷ್ಟ ಮತ್ತು ದೊಡ್ಡದು; pyproject.toml ಮತ್ತು poetry.lock ಮಾತ್ರ ವರ್ಷನ್ ಕಂಟ್ರೋಲ್‌ಗೆ ಸೇರಬೇಕು.