Azure VM에 Poetry로 Agent 프로젝트 디펜던시 관리하기

1 Poetry를 활용한 Dependency 관리

Poetry는 Python 프로젝트의 의존성 관리와 패키징을 위한 현대적인 도구다.

1.1 Poetry의 장점

• 의존성 관리: pyproject.toml 파일로 모든 패키지 버전 관리
  
• 가상환경 자동 생성: 프로젝트별로 독립된 Python 환경 자동 구축
  
• Lock 파일: poetry.lock으로 정확한 버전 재현 가능
  
• 패키징: 배포용 패키지 빌드 자동화
  
• 개발/운영 분리: 개발용/프로덕션용 디펜던시 구분 관리

1.2 pip vs Poetry

항목	pip + requirements.txt	Poetry
설정 파일	requirements.txt (수동 관리)	pyproject.toml (자동 생성)
버전 고정	수동으로 작성	poetry.lock 자동 생성
가상환경	별도 도구 필요 (venv, virtualenv)	내장 기능
의존성 해결	충돌 시 수동 해결	자동 해결
개발/운영 분리	별도 파일 필요	하나의 파일로 관리

2 프로젝트 생성 및 설정

• Poetry cli 명령어 공식 목록-https://python-poetry.org/docs/cli/

2.1 새 프로젝트 생성

# 수동 생성  
mkdir -p ~/projects/insilico  
cd ~/projects/insilico  
pyenv local 3.11.10  

#생성된 디렉토리 구조  
insilico/  
├── pyproject.toml  
└── main.py          # ← 소스 코드는 루트에 (또는 직접 src/ 생성)  

• 폴더 생성: 수동
  
• 프로젝트 구조: insilico/ (빈 폴더)
  
• pyproject.toml: 대화형으로 생성
  
• 소스 폴더: 없음 (직접 생성 필요)
  
• tests 폴더: 없음 (직접 생성 필요)
  
• README.md: 없음 (직접 생성 필요)
  
• Python 버전: pyenv local 3.11.10으로 명시

# 자동생성  
poetry new insilico  
cd insilico  

#생성된 디렉토리 구조  
insilico/  
├── pyproject.toml  
├── README.md  
├── insilico/        # ← 소스 코드는 여기  
│   └── __init__.py  
└── tests/  

• 폴더 생성: 자동 (중첩 구조)
  
• 프로젝트 구조: insilico/insilico/ (패키지 폴더 포함)
  
• pyproject.toml: 자동 생성 (기본값)
  
• 소스 폴더: insilico/ 자동 생성
  
• tests 폴더: 자동 생성
  
• README.md: 자동 생성
  
• Python 버전: 시스템 기본값

본인은 수동으로 다음과 같이 생성

• 본인은 poetry 어떻게 동작하는지 알고싶어서 수동으로 생성했지만 자동 생성도 괜찮음

# 1. 폴더 생성 및 Python 버전 고정  
mkdir -p ~/projects/insilico  
cd ~/projects/insilico  
pyenv local 3.11.10  

# 2. Poetry 초기화  
poetry init # pyproject.toml 파일을 생성  

• 아래는 poetry init 실행으로 인해 pyproject.toml 파일을 생성하기 위해 나타나는 대화형 질문들이다.

Package name [insilico]: insilico  
Version [0.1.0]: 0.1.0  
Description []: AI Agent Development Using LangChain & LangGraph  
Author [kmkim, n to skip]:   
License []: MIT  
Compatible Python versions [^3.11]: ^3.11   
Would you like to define your main dependencies interactively? (yes/no) [yes] no  
Would you like to define your development dependencies interactively? (yes/no) [yes] no  

Do you confirm generation? (yes/no) [yes] yes  

# 3. 수동으로 구조 생성  
mkdir -p insilico tests  
touch insilico/__init__.py tests/__init__.py  
touch README.md  

insilico/                      # 프로젝트 루트 폴더  
├── pyproject.toml            # 자동 생성 (기본 설정 포함)  
├── README.md                 # 수동 생성   
├── src/                 # 수동 생성  
└── tests/                    # 수동 생성  

• 수동으로 하든 자동으로 하든 후에 pyproject.toml만 잘 작성해주면 아무 문제 없음

2.2 Poetry 가상 환경 생성

• 기존 pyproject.toml이 있을때 가상환경 생성

# 기존 pyproject.toml이 있을때, 가상환경 생성 (자동으로 .venv 폴더에 생성)  
poetry install   

• install: The install command reads the pyproject.toml file from the current project, resolves the dependencies, and installs them.
  
• 이때 가상환경 생성됨
  
• .venv/ 폴더 생성
  
• poetry.lock 생성
  
• pyproject.toml에 정의된 패키지 설치

poetry env list  

insilico-sFIBWfwq-py3.11 (Activated)  

• 본인은 conda를 사용자라서 activation의 의미가 혼동이 왔었는데 conda의 가상환경 활성화 상태와 poetry의 활성화 상태의 정의가 다름을 깨달았다.
  • Conda 환경: conda activate env_name 로 실행하면 쉘 명령어(activate)를 사용하여 쉘 프롬프트를 변경하는 의미
    
  • Poetry 환경: poetry env list로 실행하면 현재 poetry env list 명령어를 실행 중인 곳이 해당 환경인지를 나타낸다. 즉, 위의 (Activated)의 의미는 poetry env list 명령어를 실행하고 있는 현재 프로세스가 해당 insilico-sFIBWfwq-py3.11 가상 환경 내부에 있음을 의미하는 것이다.

2.3 가상환경 활성화 및 비활성화

• Poetry 환경에서 실제 가상환경을 활성화 시키려면?
  • poetry에서 가상환경의 활성화는 poetry shell로 가능했는데 Poetry 2.0+부터는 이 명령어가 코어 기능에서 제거(Removed)되었다 (deprecated)

2.3.1 표준 활성화 방법

• eval $(poetry env activate): 공식 웹사이트에서 제 1 에시로 나옴

azureuser@test-agent:~/projects/insilico$ eval $(poetry env activate) # 가상환경 활성화   
(insilico-py3.11) azureuser@test-agent:~/projects/insilico$ deactivate # 가상환경이 활성화되었음. 가상환경 비활성화 명령어 입력  
azureuser@test-agent:~/projects/insilico$ # 가상환경 비활성화됨  

2.3.2 개별 명령어 실행

• poetry run 명령어는 가상환경을 수동으로 활성화하지 않아도 프로젝트의 가상환경을 찾고, 해당 가상환경 안에서 명령어를 실행해주는 역할을 한다.
  
• poetry run은 뒤에 실행하고자 하는 명령(Command)을 인수로 받는다.
  • Poetry는 insilico/.venv/bin/python을 사용하도록 설정한 후, 이 Python으로 test_setup.py 스크립트를 실행

azureuser@test-agent:~/projects/insilico$ cat test_setup.py  
from langchain import __version__ as lc_version  
from langgraph import version  

print(f"LangChain: {lc_version}")  
print("LangGraph: imported successfully")  

# 가상환경 활성화 없이 Poetry로 명령어 실행  
poetry run python test_setup.py  

azureuser@test-agent:~/projects/insilico$ poetry run python test_setup.py  
LangChain: 1.1.0  
LangGraph: imported successfully  

2.3.3 수동 활성화

• 가장 직접적인 방법으로 path 를 읽어와서 활성화시킨다. poetry 가 비정상적으로 설치됐을 경우 가장 효과적으로 활성화 시킬 수 있다.

source $(poetry env info --path)/bin/activate  

2.4 Poetry의 가상환경 위치 설정

• pyenv vs venv
  • pyenv: Python 버전 관리
    • pyenv local 3.11.10
      
    • 역할: Python 인터프리터 버전 관리
      
    • 설치 위치: ~/.pyenv/versions/3.11.10/
      
    • 관리 대상: Python 실행 파일 자체
      
    • 목적: 프로젝트마다 다른 Python 버전 사용
      
  • Poetry .venv: 패키지 격리
    • poetry config virtualenvs.in-project true: 프로젝트 폴더 내에 .venv 생성하도록 설정
      
    • poetry install
      
    • 설치 위치: 프로젝트 폴더 내 .venv/
      
    • 관리 대상: 패키지(langchain, fastapi 등)
      
    • 목적: 프로젝트마다 독립된 패키지 환경

# 프로젝트 폴더 내에 .venv 생성 (권장)  
azureuser@test-agent:~/projects/insilico$ poetry config virtualenvs.in-project true  
azureuser@test-agent:~/projects/insilico$ ls -la  
total 316  
drwxrwxr-x 4 azureuser azureuser   4096 Dec  3 04:18 .  
drwxrwxr-x 3 azureuser azureuser   4096 Dec  1 07:45 ..  
-rw-rw-r-- 1 azureuser azureuser      8 Dec  1 07:45 .python-version  
-rw-rw-r-- 1 azureuser azureuser 293841 Dec  1 07:55 poetry.lock  
-rw-rw-r-- 1 azureuser azureuser    711 Dec  1 07:55 pyproject.toml  
drwxrwxr-x 4 azureuser azureuser   4096 Dec  1 08:02 src  
-rw-rw-r-- 1 azureuser azureuser    155 Dec  1 08:02 test_setup.py  
drwxrwxr-x 2 azureuser azureuser   4096 Dec  1 08:02 tests  

• poetry config virtualenvs.in-project true 명령어를 실행했지만 .venv 폴더가 아직 생성되지 않았다.
  • 시행착오 결과, 내가 poetry에서 가상환경 재설치를 위해 필요한 폴더 구조를 만들지 않아서 .venv 생성이 되지 않았던 것
    
  • 필요한 폴더 구조: Python 패키지 규칙과 Poetry의 프로젝트 구조 요구사항을 의미
    
  • Python 패키지 = 폴더 + __init__.py

  # __init__.py 있음 → Python 패키지  
  insilico/                       # 프로젝트 루트  
  ├── README.md                   # 프로젝트 설명  
  ├── pyproject.toml  
  ├── poetry.lock  
  ├── .venv/  
  └── src/  
      └── insilico/                   # 패키지 루트 (프로젝트명과 동일)  
          ├── __init__.py            # 패키지 표시 (필수)  
          ├── agents/  
          │   ├── __init__.py        # 서브패키지 표시 (필수)  
          │   └── chat_agent.py  
          └── utils/  
              ├── __init__.py        # 서브패키지 표시 (필수)  
              └── helpers.py  
  # import 성공  
  python -c "import insilico.agents"  
  python -c "from insilico import Agent"  
  # 정상 작동  

• poetry new insilico 로 자동설치하면 이런 시행착오를 안겪고 가상환경으로 자동으로 만들 수 있음
  
• 수동 설치시 아래의 구조를 수동으로 만들어야함

#가능한 디렉토리 구조: Flat 레이아웃 사용 (덜 권장)  
insilico/  
├── pyproject.toml  
├── README.md # 포에트리 구조 요구 사항: PyPI 등록 시 표시될 설명. 이 파일이 없어도 가상환경이 설치되지만 경고 메세지가 출력된다.  
├── insilico/        # 소스 코드 폴더명은 프로젝트 폴더명과 일치시켜야함  
│   └── __init__.py # 패키지 인식 스크립트 필요  
└── tests/  

• 소스 코드 폴더명과 프로젝트 폴더명의 일치
  • 별도 설정 없이 패키지 자동 인식시키면 pip install insilico 후 import insilico로 자동 사용 가능
    
• 만약 소스 코드 폴더명 과 폴더명이 불일치하면 pyproject.toml을 수정해야함
  • 그래도 여전히, 패키지 이름과 일치하는 폴더는 필수적으로 만들어야한다.

#가능한 디렉토리 구조: src 레이아웃 사용 (표준 권장)  
insilico/ # 프로젝트 명 or 패키지 명  
├── pyproject.toml  
├── src/ # 소스 코드 폴더명: 프로젝트 명 or 패키지 명과 달라도 됨  
│       └── insilico/  # **패키지 이름과 일치하는 폴더 (필수)**  
│           ├── __init__.py  
│           └── (모듈 파일들...)  
└── tests/  

• pyproject.toml 변경: Poetry가 src/ 디렉토리 내에서 패키지 소스 코드를 찾도록 지정

<중략>  
[tool.poetry]  
name = "insilico"  
packages = [{ include = "insilico", from = "src" } # src/insilico/를 패키지로 지정]  
# ...  
<중략>  

• 개발만 하고 배포 안 할 경우: 패키지 모드 비활성화 (비권장)
  • poetry install --no-root: # 폴더명, init.py 상관없이 설치 가능

[tool.poetry]  
package-mode = false  # ← 패키지 구조 무시  
name = "insilico"  

• 아예 깔끔하게 기존 가상환경 삭제 하고 재생성 시도

# Poetry가 캐시 폴더에 이미 만든 가상환경 확인  
poetry env list  
# 출력: insilico-sFIBWfwq-py3.11 (Activated)  

# 기존 환경 삭제  
poetry env remove python  
# 또는 전체 삭제  
poetry env remove --all  

• 가상환경 재설치

# insilico 폴더에 __init__.py 생성  
cd ~/projects/insilico  
touch __init__.py  
touch README.md  

• pyproject.toml 수정

[tool.poetry]  
name = "insilico"  
version = "0.1.0"  
description = "AI Agent Development Using LangChain & LangGraph"  
authors = ["kmkim <kmkim@seegene.com>"]  
license = "MIT"  
readme = "README.md"  
packages = [{include = "insilico", from = "src"}]  # 가상환경 만들기전에 명시적으로 이 줄 추가  

[tool.poetry.dependencies]  
python = "^3.11"  
langchain = "^1.1.0"  
langchain-community = "^0.4.1"  
langgraph = "^1.0.4"  
python-dotenv = "^1.2.1"  
pydantic = "^2.12.5"  
fastapi = "^0.123.0"  
uvicorn = "^0.38.0"  
numpy = "^2.3.5"  
pandas = "^2.3.3"  
polars = "^1.35.2"  

[build-system]  
requires = ["poetry-core>=2.0.0,<3.0.0"]  
build-backend = "poetry.core.masonry.api"  

# 가상환경 재생성  
azureuser@test-agent:~/projects/insilico$ poetry install  

azureuser@test-agent:~/projects/insilico$ cd ~/projects/insilico  

# insilico 폴더에 __init__.py 생성  
touch insilico/__init__.py  

# agents 폴더에 __init__.py 생성  
touch insilico/agents/__init__.py  

# utils 폴더에 __init__.py 생성  
touch insilico/utils/__init__.py  
azureuser@test-agent:~/projects/insilico$ cd insilico/  
azureuser@test-agent:~/projects/insilico/insilico$ ls  
__init__.py  agents  utils  
azureuser@test-agent:~/projects/insilico/insilico$ cd agents  
azureuser@test-agent:~/projects/insilico/insilico/agents$ ls  
__init__.py  
azureuser@test-agent:~/projects/insilico/insilico/agents$ cd ../../  
azureuser@test-agent:~/projects/insilico$ ls  
README.md  insilico  poetry.lock  pyproject.toml  test_setup.py  tests  
azureuser@test-agent:~/projects/insilico$ nano pyproject.toml  
azureuser@test-agent:~/projects/insilico$ poetry install  
Creating virtualenv insilico in /home/azureuser/projects/insilico/.venv  
Installing dependencies from lock file  

Package operations: 64 installs, 0 updates, 0 removals  

  - Installing certifi (2025.11.12)  
  - Installing charset-normalizer (3.4.4)  
  - Installing h11 (0.16.0)  
  - Installing idna (3.11)  
  - Installing typing-extensions (4.15.0)  
  - Installing urllib3 (2.5.0)  
  - Installing annotated-types (0.7.0)  
  - Installing anyio (4.12.0)  
  - Installing httpcore (1.0.9)  
  - Installing pydantic-core (2.41.5)  
  - Installing requests (2.32.5)  
  - Installing typing-inspection (0.4.2)  
  - Installing httpx (0.28.1)  
  - Installing jsonpointer (3.0.0)  
  - Installing orjson (3.11.4)  
  - Installing packaging (25.0)  
  - Installing pydantic (2.12.5)  
  - Installing requests-toolbelt (1.0.0)  
  - Installing zstandard (0.25.0)  
  - Installing jsonpatch (1.33)  
  - Installing langsmith (0.4.49)  
  - Installing pyyaml (6.0.3)  
  - Installing tenacity (9.1.2)  
  - Installing langchain-core (1.1.0)  
  - Installing ormsgpack (1.12.0)  
  - Installing frozenlist (1.8.0)  
  - Installing greenlet (3.2.4)  
  - Installing langgraph-checkpoint (3.0.1)  
  - Installing multidict (6.7.0)  
  - Installing mypy-extensions (1.1.0)  
  - Installing propcache (0.4.1)  
  - Installing aiohappyeyeballs (2.6.1)  
  - Installing aiosignal (1.4.0)  
  - Installing attrs (25.4.0)  
  - Installing langchain-text-splitters (1.0.0)  
  - Installing langgraph-prebuilt (1.0.5)  
  - Installing langgraph-sdk (0.2.10)  
  - Installing marshmallow (3.26.1)  
  - Installing python-dotenv (1.2.1)  
  - Installing six (1.17.0)  
  - Installing sqlalchemy (2.0.44)  
  - Installing typing-inspect (0.9.0)  
  - Installing xxhash (3.6.0)  
  - Installing yarl (1.22.0)  
  - Installing aiohttp (3.13.2)  
  - Installing annotated-doc (0.0.4)  
  - Installing click (8.3.1)  
  - Installing dataclasses-json (0.6.7)  
  - Installing httpx-sse (0.4.3)  
  - Installing langchain-classic (1.0.0)  
  - Installing langgraph (1.0.4)  
  - Installing numpy (2.3.5)  
  - Installing polars-runtime-32 (1.35.2)  
  - Installing pydantic-settings (2.12.0)  
  - Installing python-dateutil (2.9.0.post0)  
  - Installing pytz (2025.2)  
  - Installing starlette (0.50.0)  
  - Installing tzdata (2025.2)  
  - Installing fastapi (0.123.0)  
  - Installing langchain (1.1.0)  
  - Installing langchain-community (0.4.1)  
  - Installing pandas (2.3.3)  
  - Installing polars (1.35.2)  
  - Installing uvicorn (0.38.0)  

Installing the current project: insilico (0.1.0)  

# 설정 확인  
azureuser@test-agent:~/projects/insilico$ poetry config --list  

cache-dir = "/home/azureuser/.cache/pypoetry"  
data-dir = "/home/azureuser/.local/share/pypoetry"  
installer.max-workers = null  
installer.no-binary = null  
installer.only-binary = null  
installer.parallel = true  
installer.re-resolve = true  
keyring.enabled = true  
python.installation-dir = "{data-dir}/python"  # /home/azureuser/.local/share/pypoetry/python  
requests.max-retries = 0  
solver.lazy-wheel = true  
system-git-client = false  
virtualenvs.create = true # Poetry가 poetry install 또는 poetry shell 실행 시 가상환경을 생성하도록 설정되어 있다.  
virtualenvs.in-project = true # 가상환경을 프로젝트 루트 디렉토리 내부에 생성하도록 설정되어 있다.   
virtualenvs.options.always-copy = false  
virtualenvs.options.no-pip = false  
virtualenvs.options.system-site-packages = false  
virtualenvs.path = "{cache-dir}/virtualenvs"  # /home/azureuser/.cache/pypoetry/virtualenvs  
virtualenvs.prompt = "{project_name}-py{python_version}"  
virtualenvs.use-poetry-python = false  

2.5 현재 가상환경 정보

# Poetry가 사용 중인 가상환경 경로  
azureuser@test-agent:~/projects/insilico$ poetry env info  

# Virtualenv  
# Python:         3.11.10  
# Implementation: CPython  
# Path:           /home/azureuser/projects/insilico/.venv  
# Executable:     /home/azureuser/projects/insilico/.venv/bin/python  
# Valid:          True  
#   
# Base  
# Platform:   linux  
# OS:         posix  
# Python:     3.11.10  
# Path:       /home/azureuser/.pyenv/versions/3.11.10  
# Executable: /home/azureuser/.pyenv/versions/3.11.10/bin/python3.11  

2.6 설치된 패키지 확인

# 현재 설치된 모든 패키지  
azureuser@test-agent:~/projects/insilico$ poetry show  

# aiohappyeyeballs         2.6.1       Happy Eyeballs for asyncio  
# aiohttp                  3.13.2      Async http client/server framework (asyncio)  
# aiosignal                1.4.0       aiosignal: a list of registered asynchronous callbacks  
# annotated-doc            0.0.4       Document parameters, class attributes, return types, and variables inline, with Annotated.  
# annotated-types          0.7.0       Reusable constraint types to use with typing.Annotated  
# anyio                    4.12.0      High-level concurrency and networking framework on top of asyncio or Trio  
# attrs                    25.4.0      Classes Without Boilerplate  
# certifi                  2025.11.12  Python package for providing Mozilla's CA Bundle.  
# charset-normalizer       3.4.4       The Real First Universal Charset Detector. Open, modern and actively maintained alternative to Chardet.  
# click                    8.3.1       Composable command line interface toolkit  
# dataclasses-json         0.6.7       Easily serialize dataclasses to and from JSON.  
# fastapi                  0.123.0     FastAPI framework, high performance, easy to learn, fast to code, ready for production  
# frozenlist               1.8.0       A list-like structure which implements collections.abc.MutableSequence  
# greenlet                 3.2.4       Lightweight in-process concurrent programming  
# (중략)  

# 특정 패키지 상세 정보  
azureuser@test-agent:~/projects/insilico$ poetry show langchain  

#  name         : langchain  
#  version      : 1.1.0  
#  description  : Building applications with LLMs through composability  
#   
# dependencies  
#  - langchain-core >=1.1.0,<2.0.0  
#  - langgraph >=1.0.2,<1.1.0  
#  - pydantic >=2.7.4,<3.0.0  

# 디펜던시 트리 확인  
azureuser@test-agent:~/projects/insilico$ poetry show --tree  

# (중략)  
# langgraph 1.0.4 Building stateful, multi-actor applications with LLMs  
# ├── langchain-core >=0.1  
# │   ├── jsonpatch >=1.33.0,<2.0.0  
# │   │   └── jsonpointer >=1.9  
# │   ├── langsmith >=0.3.45,<1.0.0  
# │   │   ├── httpx >=0.23.0,<1  
# │   │   │   ├── anyio *  
# │   │   │   │   ├── idna >=2.8  
# │   │   │   │   └── typing-extensions >=4.5  
# │   │   │   ├── certifi *  
# │   │   │   ├── httpcore ==1.*  
# │   │   │   │   ├── certifi * (circular dependency aborted here)  
# │   │   │   │   └── h11 >=0.16  
# │   │   │   └── idna * (circular dependency aborted here)  
# │   │   ├── orjson >=3.9.14  
# │   │   ├── packaging >=23.2  
# │   │   ├── pydantic >=1,<3  
# │   │   │   ├── annotated-types >=0.6.0  
# │   │   │   ├── pydantic-core 2.41.5  
# │   │   │   │   └── typing-extensions >=4.14.1 (circular dependency aborted here)  
# │   │   │   ├── typing-extensions >=4.14.1 (circular dependency aborted here)  
# │   │   │   └── typing-inspection >=0.4.2  
# │   │   │       └── typing-extensions >=4.12.0 (circular dependency aborted here)  
# │   │   ├── requests >=2.0.0  
# │   │   │   ├── certifi >=2017.4.17 (circular dependency aborted here)  
# │   │   │   ├── charset-normalizer >=2,<4  
# │   │   │   ├── idna >=2.5,<4 (circular dependency aborted here)  
# │   │   │   └── urllib3 >=1.21.1,<3  
# │   │   ├── requests-toolbelt >=1.0.0  
# │   │   │   └── requests >=2.0.1,<3.0.0 (circular dependency aborted here)  
# │   │   └── zstandard >=0.23.0  
# │   ├── packaging >=23.2.0,<26.0.0 (circular dependency aborted here)  
# │   ├── pydantic >=2.7.4,<3.0.0 (circular dependency aborted here)  
# │   ├── pyyaml >=5.3.0,<7.0.0  
# │   ├── tenacity >=8.1.0,<8.4.0 || >8.4.0,<10.0.0  
# │   └── typing-extensions >=4.7.0,<5.0.0 (circular dependency aborted here)  
# ```  
# (중략)  

2.7 Python 버전 확인

# Poetry 환경의 Python 버전  
azureuser@test-agent:~/projects/insilico$ poetry run python --version  
# Python 3.11.10  

또는

azureuser@test-agent:~/projects/insilico$ eval $(poetry env activate)  
(insilico-py3.11) azureuser@test-agent:~/projects/insilico$ python --version  
# Python 3.11.10  
(insilico-py3.11) azureuser@test-agent:~/projects/insilico$ which python  
# /home/azureuser/projects/insilico/.venv/bin/python  

3 pyproject.toml 입력 가이드

3.1 버전 지정 방식

표기법	의미	예시
^1.2.3	1.2.3 이상, 2.0.0 미만	^1.2.3 → >=1.2.3 <2.0.0
~1.2.3	1.2.3 이상, 1.3.0 미만	~1.2.3 → >=1.2.3 <1.3.0
>=1.2.3	1.2.3 이상	최신 버전까지 허용
1.2.3	정확히 1.2.3만	고정 버전
*	모든 버전	최신 버전 (비권장)

3.2 개발/운영 디펜던시 분리

[tool.poetry.dependencies]  
# 운영 환경에 필요한 패키지  
python = "^3.11"  
fastapi = "^0.109.0"  
langchain = "^0.1.0"  

[tool.poetry.group.dev.dependencies]  
# 개발 환경에서만 필요한 패키지  
pytest = "^8.0.0"  
black = "^24.0.0"  
mypy = "^1.8.0"  

설치 시 차이:

# 운영 + 개발 디펜던시 모두 설치  
poetry install  

# 운영 디펜던시만 설치 (프로덕션 배포 시)  
poetry install --only main  

4 디펜던시 설치

4.1 Agent 개발 핵심 패키지

4.1.1 데이터 처리

# Pandas: 데이터 분석 및 처리  
poetry add pandas  

# Polars: 고성능 데이터프레임 (Pandas보다 빠름)  
poetry add polars  

# NumPy: 수치 계산  
poetry add numpy  

pyproject.toml에 자동 추가됨:

[tool.poetry.dependencies]  
pandas = "^2.2.0"  
polars = "^0.20.0"  
numpy = "^1.26.0"  

4.1.2 LangChain 생태계

# LangChain 코어: Agent 프레임워크  
poetry add langchain  

# LangChain Community: 추가 통합 기능  
poetry add langchain-community  

# LangGraph: Agent 워크플로우 오케스트레이션  
poetry add langgraph  

LangChain 패키지 구성:

패키지	용도
langchain	코어 프레임워크 (LLM, Chains, Agents)
langchain-community	써드파티 통합 (Vector DB, APIs)
langgraph	상태 기반 Agent 워크플로우
langchain-openai	OpenAI 통합 (별도 설치 시)

4.1.3 환경 변수 및 설정

# Python-dotenv: .env 파일 로드  
poetry add python-dotenv  

# Pydantic: 데이터 검증 및 설정 관리  
poetry add pydantic  

사용 예시:

# .env 파일  
OPENAI_API_KEY=sk-...  
DATABASE_URL=postgresql://...  

# main.py  
from dotenv import load_dotenv  
from pydantic import BaseModel  

load_dotenv()  # .env 파일 로드  

class AgentConfig(BaseModel):  
    model: str = "gpt-4"  
    temperature: float = 0.7  

4.1.4 API 서버

# FastAPI: 웹 API 프레임워크  
poetry add fastapi  

# Uvicorn: ASGI 서버  
poetry add uvicorn[standard]  

FastAPI 기본 템플릿:

from fastapi import FastAPI  
from pydantic import BaseModel  

app = FastAPI()  

class AgentRequest(BaseModel):  
    query: str  
    model: str = "gpt-4"  

@app.post("/agent/chat")  
async def chat(request: AgentRequest):  
    # Agent 로직  
    return {"response": "..."}  

서버 실행:

poetry run uvicorn main:app --reload --host 0.0.0.0 --port 8000  

4.2 전체 디펜던시 한 번에 설치

poetry add pandas polars numpy \  
  langchain langchain-community langgraph \  
  python-dotenv pydantic \  
  fastapi uvicorn[standard]  

4.3 개발 도구 추가 (선택사항)

# 코드 포맷터  
poetry add --group dev black ruff  

# 타입 체커  
poetry add --group dev mypy  

# 테스트 프레임워크  
poetry add --group dev pytest pytest-asyncio  

# Jupyter Notebook (실험용)  
poetry add --group dev jupyter ipykernel  

5 디펜던시 관리 명령어

5.1 패키지 추가/제거

# 패키지 추가  
poetry add <package-name>  

# 특정 버전 설치  
poetry add langchain@^0.1.0  

# 개발 디펜던시로 추가  
poetry add --group dev pytest  

# 패키지 제거  
poetry remove <package-name>  

5.2 업데이트

# 모든 패키지 최신 버전으로 업데이트  
poetry update  

# 특정 패키지만 업데이트  
poetry update langchain  

# Lock 파일만 업데이트 (설치는 안 함)  
poetry lock --no-update  

5.3 의존성 확인

# 오래된 패키지 확인  
poetry show --outdated  

# 보안 취약점 확인 (별도 플러그인 필요)  
poetry run pip-audit  

6 완성된 pyproject.toml 예시

[tool.poetry]  
name = "agent-platform"  
version = "0.1.0"  
description = "AI Agent Platform with LangChain and FastAPI"  
authors = ["Kwangmin Kim <your@email.com>"]  
readme = "README.md"  
license = "MIT"  
packages = [{include = "agent_platform"}]  

[tool.poetry.dependencies]  
python = "^3.11"  
# 데이터 처리  
pandas = "^2.2.0"  
polars = "^0.20.0"  
numpy = "^1.26.0"  
# LangChain 생태계  
langchain = "^0.1.0"  
langchain-community = "^0.0.20"  
langgraph = "^0.0.20"  
# 환경 설정  
python-dotenv = "^1.0.0"  
pydantic = "^2.5.0"  
# API 서버  
fastapi = "^0.109.0"  
uvicorn = {extras = ["standard"], version = "^0.27.0"}  

[tool.poetry.group.dev.dependencies]  
pytest = "^8.0.0"  
pytest-asyncio = "^0.23.0"  
black = "^24.0.0"  
ruff = "^0.1.0"  
mypy = "^1.8.0"  
jupyter = "^1.0.0"  
ipykernel = "^6.29.0"  

[build-system]  
requires = ["poetry-core"]  
build-backend = "poetry.core.masonry.api"  

[tool.black]  
line-length = 100  
target-version = ['py311']  

[tool.ruff]  
line-length = 100  
target-version = "py311"  

7 프로젝트 공유 및 배포

7.1 다른 환경에서 프로젝트 복원

# 1. 프로젝트 클론  
git clone <repository-url>  
cd agent-platform  

# 2. Poetry로 디펜던시 설치  
poetry install  

# poetry.lock 파일이 있으면 정확히 같은 버전 설치됨  

7.2 Requirements.txt 생성 (레거시 호환)

# Poetry 디펜던시를 requirements.txt로 변환  
poetry export -f requirements.txt --output requirements.txt  

# 개발 디펜던시 제외  
poetry export -f requirements.txt --output requirements.txt --without dev  

8 실전 워크플로우

8.1 일반적인 개발 흐름

# 1. 프로젝트 생성  
poetry new agent-platform  
cd agent-platform  

# 2. 가상환경 설정  
poetry config virtualenvs.in-project true  
poetry install  

# 3. 필요한 패키지 추가  
poetry add langchain fastapi  

# 4. 개발 시작  
poetry shell  
python main.py  

# 5. 새로운 패키지 필요 시  
poetry add <package-name>  

# 6. 테스트 실행  
poetry run pytest  

# 7. 코드 포맷팅  
poetry run black .  
poetry run ruff check .  

8.2 Git 관리

.gitignore 권장 설정:

# Python  
__pycache__/  
*.py[cod]  
*$py.class  
*.so  

# Poetry  
.venv/  
dist/  
*.egg-info/  

# 환경 변수  
.env  
.env.local  

# IDE  
.vscode/  
.idea/  
*.swp  

# OS  
.DS_Store  
Thumbs.db  

Git에 포함할 파일:

✅ pyproject.toml      # 디펜던시 정의  
✅ poetry.lock         # 정확한 버전 고정  
✅ README.md  
✅ .gitignore  
❌ .venv/              # 가상환경은 제외  
❌ __pycache__/        # 캐시 파일 제외  

9 문제 해결

9.1 가상환경 재생성

# 기존 가상환경 삭제  
poetry env remove python  

# 또는 .venv 폴더 직접 삭제  
rm -rf .venv  

# 재생성  
poetry install  

9.2 Lock 파일 충돌

# Lock 파일 재생성  
poetry lock --no-update  

# 강제 업데이트  
poetry lock  
poetry install  

9.3 캐시 정리

# Poetry 캐시 정리  
poetry cache clear pypi --all  

10 요약

단계	명령어	설명
1. 프로젝트 생성	poetry new <project>	새 프로젝트 생성
2. 가상환경 설정	poetry config virtualenvs.in-project true	.venv 로컬 생성
3. 디펜던시 설치	poetry add <package>	패키지 추가
4. 환경 활성화	poetry shell	Shell 진입
5. 확인	poetry show	설치된 패키지 확인
6. 업데이트	poetry update	패키지 업데이트

핵심 파일:
- pyproject.toml: 프로젝트 설정 및 디펜던시 정의
- poetry.lock: 정확한 버전 고정 (Git 포함 필수)
- .venv/: 가상환경 폴더 (Git 제외)

Poetry를 사용하면 Python 프로젝트의 디펜던시 관리가 일관되고, 재현 가능하며, 충돌 없이 진행됩니다.