మీ 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, అలాగే వేర్వేరు SDK లు రెండు దిశల్లోకి లాగే pydantic వంటి మోడల్-సైడ్ లైబ్రరీలు. గ్లోబల్‌గా ఇన్‌స్టాల్ చేయడం అంటే మెషీన్‌లోని ప్రతి ప్రాజెక్టుకూ చివరిగా ఇన్‌స్టాల్ చేసినదే గెలుస్తుంది. వర్చువల్ ఎన్విరాన్‌మెంట్ ప్రతి ప్రాజెక్టుకూ సొంత 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 మాత్రమే వెర్షన్ కంట్రోల్‌లో ఉండాలి.