உங்கள் agent-இன் Python சூழலைத் தனிமைப்படுத்துங்கள்

அறிமுகம்

ஒரு ஏஜென்ட் திட்டத்திற்காக 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 மூலம் தனிமைப்படுத்தலைச் சரிபார்க்கவும், மேலும் pyproject.toml இல் சார்புகளை அறிவித்து poetry.lock இல் அவற்றைப் பின் செய்ய Poetry ஐப் பயன்படுத்தவும் முடியும், இதனால் ஒவ்வொரு குழு உறுப்பினரும் CI ஓட்டமும் ஒரே பதிப்புகளை நிறுவும்.

முக்கியச் சொற்கள்

• மெய்நிகர் சூழல் (Virtual environment) — அதன் சொந்த Python இன்டர்ப்ரெட்டர் மற்றும் site-packages ஐக் கொண்ட தனிமைப்படுத்தப்பட்ட கோப்பகம் (பொதுவாக .venv/); அதைச் செயல்படுத்துவது அந்த இன்டர்ப்ரெட்டரை PATH இல் முதலில் வைக்கிறது, இதனால் பேக்கேஜ் நிறுவல்கள் ஒரு திட்டத்திற்கு மட்டுமே உள்ளூராக இருக்கும். இது இல்லாமல், ஏஜென்ட் SDK மேம்படுத்தல்கள் திட்டங்களுக்கிடையே மோதுகின்றன.
• pyproject.toml — உங்கள் திட்டத்தின் மெட்டாடேட்டா மற்றும் சார்பு வரம்புகளைப் (எ.கா. langgraph = "^0.2.0") பட்டியலிடும் ஒற்றை அறிவிப்புக் கோப்பு. இதைத்தான் மனிதர்கள் திருத்துகிறார்கள், பதிப்புகளைத் தீர்க்க Poetry இதைத்தான் படிக்கிறது.
• poetry.lock — ஒவ்வொரு நேரடி மற்றும் பரிமாற்றச் சார்பின் சரியான தீர்க்கப்பட்ட பதிப்புகளைப் பின் செய்யும் தானாக உருவாக்கப்பட்ட கோப்பு. git இல் கமிட் செய்யப்பட்டு, ஒவ்வொரு இயந்திரத்திலும் poetry install ஒரே மரத்தை உருவாக்குவதை உறுதி செய்யும் ஒப்பந்தம் இதுவே.
• சார்புக் குழு (Dependency group) — pyproject.toml இல் உள்ள சார்புகளின் லேபிளிடப்பட்ட துணைத்தொகுப்பு (எ.கா. group.dev, group.test), வெளிப்படையாகக் கோரப்படும்போது மட்டுமே நிறுவப்படுகிறது, இதனால் production இமேஜ்கள் சோதனை அல்லது lint கருவிகள் இல்லாமல் இருக்கும்.
• பரிமாற்றச் சார்பு (Transitive dependency) — நீங்கள் கேட்ட ஏதோ ஒன்று அதைச் சார்ந்திருப்பதால் இழுக்கப்படும் பேக்கேஜ் (எ.கா. httpx ஆனது openai வழியாக வருகிறது). இவைதான் கவனிக்கப்படாமல் நழுவக்கூடிய பதிப்புகள் என்பதால்தான் lock கோப்புகள் முக்கியமாகின்றன.

கருத்துகள்

ஏஜென்ட் திட்டங்களுக்குத் தனிமைப்படுத்தல் ஏன் இயல்புநிலை

ஏஜென்ட் கோட்பேஸ்கள் வேகமாக மாறும் ஸ்டாக்குகளை இழுக்கின்றன: langchain-core, langgraph, openai, anthropic, மேலும் வெவ்வேறு SDK களால் இரு திசைகளில் இழுக்கப்படும் pydantic போன்ற மாடல் பக்க நூலகங்கள். உலகளாவிய அளவில் நிறுவுவது என்றால், இயந்திரத்தில் உள்ள ஒவ்வொரு திட்டத்திற்கும் சமீபத்திய நிறுவல் வெற்றி பெறுகிறது. ஒரு மெய்நிகர் சூழல் ஒவ்வொரு திட்டத்திற்கும் அதன் சொந்த site-packages ஐ வழங்குகிறது, இதனால் பதிப்புப் பின்கள் ஒரு கோப்பகம் மற்றும் ஒரு PATH மாற்றத்திற்கு மட்டுமே வரம்பிடப்படுகின்றன, முழு பயனர் கணக்கிற்கும் அல்ல.

செயல்படுத்துதல் என்பது வெறும் PATH முன்னிணைப்பும் ஷெல் ப்ராம்ப்ட் மாற்றமும்தான் — இதில் கர்னல் மாயாஜாலம் எதுவும் இல்லை. .venv/bin ஆனது PATH இல் முதலில் வந்தவுடன், python, pip மற்றும் எந்த console-script நுழைவுப் புள்ளியும் தனிமைப்படுத்தப்பட்ட நகல்களுக்குத் தீர்க்கப்படுகின்றன. செயலிழக்கச் செய்வது அசல் 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 ஆகியவற்றை production நிறுவல்களிலிருந்து விலக்கி வைக்கும் அதே நேரத்தில், அவற்றை மூலக் கட்டுப்பாட்டில் தொடர்ந்து கண்காணிக்க அனுமதிக்கின்றன.

குறியீடு விளக்கம்

முதல் துணுக்கு புதிதாக ஒரு தனிமைப்படுத்தப்பட்ட 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 இரண்டையும் கமிட் செய்யவும் — lock கோப்புதான் "என் இயந்திரத்தில் வேலை செய்கிறது" என்பதை ஒரு குழு உறுப்பினரின் இயந்திரத்திலும் CI யிலும் மீளுருவாக்கக்கூடியதாக ஆக்குகிறது.
3. pytest, mypy மற்றும் ruff ஆகியவற்றை group.dev இல் வைக்கவும் — production இமேஜ்கள் சிறியதாக இருக்கும், மேலும் தொடர்பில்லாத கருவி மேம்படுத்தல்கள் இயக்கநேரத் தீர்வை உடைக்க முடியாது.

செய்யக்கூடாதவை

1. "வெறும் ஒரு விரைவுச் சோதனைக்காக" சிஸ்டம் Python இல் pip install செய்யாதீர்கள் — விரைவுச் சோதனைகள் மூலமாகத்தான் ஏஜென்ட் SDK முரண்பாடுகள் அறிமுகமாகின்றன; எப்போதும் முதலில் ஒரு venv ஐச் செயல்படுத்தவும்.
2. poetry.lock ஐக் கையால் திருத்தாதீர்கள் — poetry lock அல்லது poetry add மூலம் அதை மீண்டும் உருவாக்கவும்; கைமுறைத் திருத்தங்கள் வரம்புகளைப் பின் செய்யப்பட்ட பதிப்புகளிலிருந்து பிரித்து மீளுருவாக்கத்தை அமைதியாக உடைக்கின்றன.
3. .venv/ ஐக் கமிட் செய்யாதீர்கள் — அதை gitignore செய்யவும் — venv இயந்திரம் சார்ந்தது மற்றும் பெரியது; pyproject.toml மற்றும் poetry.lock மட்டுமே பதிப்புக் கட்டுப்பாட்டில் இருக்க வேண்டும்.